<commit_before>= Crimson

image::https://img.shields.io/pypi/v/crimson[link="https://pypi.org/project/crimson"]
image::https://builds.sr.ht/~bow/crimson.svg[link="https://builds.sr.ht/%7Ebow/crimson?"]


`crimson` converts non-standard bioinformatics tool outputs to JSON or YAML.

Currently it can convert outputs of the following tools:

* http://www.bioinformatics.babraham.ac.uk/projects/fastqc[FastQC] (``fastqc``)
* https://github.com/ndaniel/fusioncatcher[FusionCatcher] (``fusioncatcher``)
* http://www.htslib.org/doc/samtools.html[samtools] flagstat (``flagstat``)
* https://broadinstitute.github.io/picard[Picard] metrics tools (``picard``)
* https://github.com/alexdobin/STAR[STAR] log file (``star``)
* https://github.com/STAR-Fusion/STAR-Fusion[STAR-Fusion] hits table (``star-fusion``)
* http://www.ensembl.org/info/docs/tools/vep/index.html[Variant Effect Predictor]
  plain text output (``vep``)

The conversion can be done using the command line interface or by calling the
tool-specificparser functions in your Python script.


== Installation

`crimson` is available on the https://pypi.org/project/crimson/[Python Package Index]
and you can install it via `pip`:

[source,shell]
----
$ pip install crimson
----

It is also available on
https://bioconda.github.io/recipes/crimson/README.html[BioConda], both through the
`conda` package manager or as a
https://quay.io/repository/biocontainers/crimson?tab=tags[Docker container].


== Usage

=== As a command line tool

The general command is `crimson {program_name}` and by default the output is written to
`stdout`. For example, to use the `picard` parser, you would execute:

[source,shell]
----
$ crimson picard /path/to/a/picard.metrics
----

You can also specify a file name directly to write to a file. The following command will
write the output to a file named ``converted.json``:

[source,shell]
----
$ crimson picard /path/to/a/picard.metrics converted.json
----

Some parsers may also accept additional input format. The FastQC parser, for example, also
works if you specify a path to a FastQC output directory:


[source,shell]
----
$ crimson fastqc /path/to/a/fastqc/dir
----

or path to a zipped result:

[source,shell]
----
$ crimson fastqc /path/to/a/fastqc_result.zip
----

When in doubt, use the ``--help`` flag:

[source,shell]
----
$ crimson --help            # for the general help
$ crimson fastqc --help     # for parser-specific (FastQC) help
----

=== As a Python library function

Generally, the function to import is located at `crimson.{program_name}.parser`. For
example, to use the `picard` parser in your script, you can do:

[source,python]
----
from crimson import picard

# You can specify the input file name as a string ...
parsed = picard.parse("/path/to/a/picard.metrics")

# ... or a file handle
with open("/path/to/a/picard.metrics") as src:
    parsed = picard.parse(src)
----

== Why?

* Not enough tools use standard output formats.
* Writing and re-writing the same parsers across different scripts is not a productive
  way to spend the day.


== Local Development

Setting up a local development requires that you set up all of the supported Python
versions. We recommend using [pyenv](https://github.com/pyenv/pyenv) for this.

The following steps can be your guide for your local development setup:

[source,shell]
----
# Clone the repository and cd into it.
$ git clone https://git.sr.ht/~bow/crimson
$ cd crimson

# Create your virtualenv.<commit_msg>docs: Fix minor issues<commit_after>= Crimson

image:https://img.shields.io/pypi/v/crimson[link="https://pypi.org/project/crimson"] image:https://builds.sr.ht/~bow/crimson.svg[link="https://builds.sr.ht/%7Ebow/crimson?"]

`crimson` converts non-standard bioinformatics tool outputs to JSON or YAML.

Currently it can convert outputs of the following tools:

* http://www.bioinformatics.babraham.ac.uk/projects/fastqc[FastQC] (``fastqc``)
* https://github.com/ndaniel/fusioncatcher[FusionCatcher] (``fusioncatcher``)
* http://www.htslib.org/doc/samtools.html[samtools] flagstat (``flagstat``)
* https://broadinstitute.github.io/picard[Picard] metrics tools (``picard``)
* https://github.com/alexdobin/STAR[STAR] log file (``star``)
* https://github.com/STAR-Fusion/STAR-Fusion[STAR-Fusion] hits table (``star-fusion``)
* http://www.ensembl.org/info/docs/tools/vep/index.html[Variant Effect Predictor]
  plain text output (``vep``)

The conversion can be done using the command line interface or by calling the
tool-specificparser functions in your Python script.


== Installation

`crimson` is available on the https://pypi.org/project/crimson/[Python Package Index]
and you can install it via `pip`:

[source,shell]
----
$ pip install crimson
----

It is also available on
https://bioconda.github.io/recipes/crimson/README.html[BioConda], both through the
`conda` package manager or as a
https://quay.io/repository/biocontainers/crimson?tab=tags[Docker container].


== Usage

=== As a command line tool

The general command is `crimson {program_name}` and by default the output is written to
`stdout`. For example, to use the `picard` parser, you would execute:

[source,shell]
----
$ crimson picard /path/to/a/picard.metrics
----

You can also specify a file name directly to write to a file. The following command will
write the output to a file named ``converted.json``:

[source,shell]
----
$ crimson picard /path/to/a/picard.metrics converted.json
----

Some parsers may also accept additional input format. The FastQC parser, for example, also
works if you specify a path to a FastQC output directory:


[source,shell]
----
$ crimson fastqc /path/to/a/fastqc/dir
----

or path to a zipped result:

[source,shell]
----
$ crimson fastqc /path/to/a/fastqc_result.zip
----

When in doubt, use the ``--help`` flag:

[source,shell]
----
$ crimson --help            # for the general help
$ crimson fastqc --help     # for parser-specific (FastQC) help
----

=== As a Python library function

Generally, the function to import is located at `crimson.{program_name}.parser`. For
example, to use the `picard` parser in your script, you can do:

[source,python]
----
from crimson import picard

# You can specify the input file name as a string ...
parsed = picard.parse("/path/to/a/picard.metrics")

# ... or a file handle
with open("/path/to/a/picard.metrics") as src:
    parsed = picard.parse(src)
----

== Why?

* Not enough tools use standard output formats.
* Writing and re-writing the same parsers across different scripts is not a productive
  way to spend the day.


== Local Development

Setting up a local development requires that you set up all of the supported Python
versions. We recommend using https://github.com/pyenv/pyenv[pyenv] for this.

The following steps can be your guide for your local development setup:

[source,shell]
----
# Clone the repository and cd into it.
$ git clone https://git.sr.ht/~bow/crimson
$ cd crimson

# Create your virtualenv.
{'fraction_non_alphanumeric': 0.13263248847926268, 'fraction_numerical': 0.0002880184331797235, 'mean_word_length': 3.9360341151385927, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 26, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3158673', 'n_tokens_mistral': 2267, 'n_tokens_neox': 2195, 'n_words': 728}