docs: extend main documentation (#81)

Dockerfile

@@ -6,12 +6,12 @@ LABEL base_image="continuumio/miniconda3:4.11.0"
 LABEL version="1.0"
 LABEL software="HTSinfer"
 LABEL software.version="v0.9.0"
-LABEL about.summary="HTSinfer infers metadata from High Throughput Sequencing (HTS) data"
+LABEL about.summary="HTSinfer infers metadata from Illumina high-throughput sequencing (HTS) data"
 LABEL about.home="https://github.com/zavolanlab/htsinfer"
 LABEL about.documentation="https://htsinfer.readthedocs.io/"
 LABEL about.license_file="https://spdx.org/licenses/Apache-2.0"
 LABEL about.license="Apache License 2.0"
-LABEL about.tags="bioinformatics, ngs"
+LABEL about.tags="Transcriptomics"
 
 ###### MAINTAINER ######
 LABEL maintainer="Alexander Kanitz <[email protected]>"

README.md

@@ -1,16 +1,93 @@
 # HTSinfer
 
 [![license][badge-license]][badge-url-license]
-[![ci][badge-ci]][badge-url-ci]
 [![docs][badge-docs]][badge-url-docs]
+[![release_gh][badge-release-gh]][badge-url-release-gh]
+[![release_docker][badge-release-docker]][badge-url-release-docker]
+[![ci][badge-ci]][badge-url-ci]
 [![coverage][badge-coverage]][badge-url-coverage]
 
-HTSinfer infers metadata from High Throughput Sequencing (HTS) data.
+HTSinfer infers metadata from Illumina high-throughput sequencing (HTS) data.
+
+## Examples
+
+**Single-ended library***
+
+```sh
+htsinfer tests/files/adapter_single.fastq
+```
+
+**Paired-ended library***
+
+```sh
+htsinfer tests/files/adapter_1.fastq tests/files/adapter_2.fastq
+```
+
+Output is written to `STDOUT` in JSON format. The log is written to `STDERR`.
+
+### Example output
+
+This is the output (`STDOUT`) of the above-mentioned call on a paired-ended
+example library:
+
+```json
+{
+   "library_source": {
+      "file_1": {
+         "short_name": "hsapiens",
+         "taxon_id": "9606"
+      },
+      "file_2": {
+         "short_name": "hsapiens",
+         "taxon_id": "9606"
+      }
+   },
+   "library_stats": {
+      "file_1": {
+         "read_length": {
+            "max": 75,
+            "min": 75
+         }
+      },
+      "file_2": {
+         "read_length": {
+            "max": 75,
+            "min": 75
+         }
+      }
+   },
+   "library_type": {
+      "file_1": "first_mate",
+      "file_2": "second_mate",
+      "relationship": "split_mates"
+   },
+   "read_layout": {
+      "file_1": {
+         "adapt_3": "AATGATACGGCGACC"
+      },
+      "file_2": {
+         "adapt_3": "AATGATACGGCGACC"
+      }
+   },
+   "read_orientation": {
+      "file_1": "SF",
+      "file_2": "SR",
+      "relationship": "ISF"
+   }
+}
+```
+
+To better understand the output, please refer to the [`Results`
+model][docs-api-results] in the [API documentation][badge-url-docs]. Note that
+`Results` model has several nested child models, such as enumerators of
+possible outcomes. Simply follow the references in each parent model for
+detailed descriptions of each child model's attributes.
 
-## Usage
+## General usage
 
 ```sh
-htsinfer [--output-directory PATH] [--temporary-directory PATH]
+htsinfer [--output-directory PATH]
+         [--temporary-directory PATH]
          [--cleanup-regime {DEFAULT,KEEP_ALL,KEEP_NONE,KEEP_RESULTS}]
          [--records INT]
          [--threads INT]
@@ -99,27 +176,30 @@ optional arguments:
 ## Installation
 
 In order to use the HTSinfer, clone the repository and install the
-dependencies with [Conda][conda]:
+dependencies via [Conda][conda]:
 
 ```sh
 git clone https://github.com/zavolanlab/htsinfer
 cd htsinfer
 conda env create --file environment.yml
 conda env update --file environment-dev.yml  # optional: install development/testing dependencies
+```
+
+Then, activate the `htsinfer` Conda environment with:
+
+```sh
 conda activate htsinfer
-python setup.py install
 ```
 
-If you have installed the development/testing dependencies, you can verify
-that HTSinfer was installed correctly by executing the tests shipped with
-the package:
+If you have installed the development/testing dependencies, you may first want
+to verify that HTSinfer was installed correctly by executing the tests shipped
+with the package:
 
 ```sh
 python -m pytest
 ```
 
-Run HTSinfer via the CLI script `htsinfer` as described in the [Usage](#Usage)
-section.
+Otherwise just go ahead and try one of the [examples](#Examples).
 
 ## API documentation
 
@@ -142,13 +222,18 @@ by email: <[email protected]>
 (c) 2020 [Zavolan lab, Biozentrum, University of Basel][contact]
 
 [badge-ci]: <https://travis-ci.com/zavolanlab/htsinfer.svg?branch=master>
-[badge-coverage]: <https://img.shields.io/coveralls/github/zavolanlab/htsinfer/master>
+[badge-coverage]: <https://codecov.io/gh/zavolanlab/htsinfer/branch/dev/graph/badge.svg?token=KYGJ9MUPHT>
 [badge-docs]: <https://readthedocs.org/projects/htsinfer/badge/?version=latest>
 [badge-license]: <https://img.shields.io/badge/license-Apache%202.0-blue.svg>
+[badge-release-docker]: <https://img.shields.io/docker/image-size/zavolab/htsinfer?color=C39BD3&label=docker>
+[badge-release-gh]: <https://img.shields.io/github/v/tag/zavolanlab/htsinfer?color=C39BD3>
 [badge-url-ci]: <https://travis-ci.com/zavolanlab/htsinfer>
-[badge-url-coverage]: <https://coveralls.io/github/zavolanlab/htsinfer>
+[badge-url-coverage]: <https://codecov.io/gh/zavolanlab/htsinfer>
 [badge-url-docs]: <https://htsinfer.readthedocs.io/en/latest/?badge=latest>
 [badge-url-license]: <http://www.apache.org/licenses/LICENSE-2.0>
+[badge-url-release-docker]: <https://hub.docker.com/repository/docker/zavolab/htsinfer>
+[badge-url-release-gh]: <https://github.com/zavolanlab/htsinfer/releases>
 [conda]: <https://docs.conda.io/en/latest/miniconda.html>
 [contact]: <https://zavolan.biozentrum.unibas.ch/>
+[docs-api-results]: <https://htsinfer.readthedocs.io/en/latest/modules/htsinfer.html#htsinfer.models.Results>
 [issue-tracker]: <https://github.com/zavolanlab/htsinfer/issues>

htsinfer/htsinfer.py

@@ -410,4 +410,9 @@ def clean_up(self):
 
     def print(self):
         """Print results to STDOUT."""
-        sys.stdout.write(self.results.json() + linesep)
+        sys.stdout.write(
+            self.results.json(
+                indent=3,
+                sort_keys=True,
+            ) + linesep
+        )

tests/test_htsinfer.py

@@ -379,14 +379,48 @@ def test_print(self, capsys):
         test_instance = HtsInfer(path_1=FILE_MATE_1)
         test_instance.print()
         captured = capsys.readouterr()
-        assert captured.out == (
-            '{"library_stats": {"file_1": {"read_length": {"min": null, '
-            '"max": null}}, "file_2": {"read_length": {"min": null, "max": '
-            'null}}}, "library_type": {"file_1": null, "file_2": null, '
-            '"relationship": null}, "library_source": {"file_1": '
-            '{"short_name": null, "taxon_id": null}, "file_2": {"short_name": '
-            'null, "taxon_id": null}}, "read_orientation": {"file_1": null, '
-            '"file_2": null, "relationship": null}, "read_layout": {"file_1": '
-            '{"adapt_3": null}, "file_2": {"adapt_3": null}}}'
-        ) + linesep
+        assert captured.out == ('''{
+   "library_source": {
+      "file_1": {
+         "short_name": null,
+         "taxon_id": null
+      },
+      "file_2": {
+         "short_name": null,
+         "taxon_id": null
+      }
+   },
+   "library_stats": {
+      "file_1": {
+         "read_length": {
+            "max": null,
+            "min": null
+         }
+      },
+      "file_2": {
+         "read_length": {
+            "max": null,
+            "min": null
+         }
+      }
+   },
+   "library_type": {
+      "file_1": null,
+      "file_2": null,
+      "relationship": null
+   },
+   "read_layout": {
+      "file_1": {
+         "adapt_3": null
+      },
+      "file_2": {
+         "adapt_3": null
+      }
+   },
+   "read_orientation": {
+      "file_1": null,
+      "file_2": null,
+      "relationship": null
+   }
+}''') + linesep
         assert captured.err == ""