From 8223260d861e497f7bf10fb6de003f2f1300c956 Mon Sep 17 00:00:00 2001 From: balajtimate Date: Mon, 18 Nov 2024 19:41:55 +0100 Subject: [PATCH] docs: update guides, README --- README.md | 26 +++++----------- docs/conf.py | 1 + docs/guides/examples.rst | 6 ++-- docs/guides/installation.rst | 58 ++++++++++++++++++---------------- docs/guides/usage.rst | 60 ++++++++++++++++++++++++++---------- 5 files changed, 86 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index 0b6acce..0e0a71b 100644 --- a/README.md +++ b/README.md @@ -16,24 +16,10 @@ For a more in-depth guide please refer to the [HTSinfer documentation][docs-docu ### Installation -HTSinfer is available as part of the [Bioconda][bioconda-release] channel, therefore the preferred installation method is via [Mamba][mamba] or [Conda][conda]. - -To create a new Conda environment with HTSinfer and its dependencies installed, run: - -```sh -mamba create --name htsinfer bioconda::htsinfer -``` - -Then, activate the `htsinfer` Conda environment with: - -```sh -conda activate htsinfer -``` - -To install HTSinfer in your current environment, run: +HTSinfer is available on [Bioconda][bioconda-release]. To install it in your currently active [Conda][conda] environment, run: ```sh -mamba install bioconda::htsinfer +conda install bioconda::htsinfer ``` ### General usage @@ -119,11 +105,13 @@ example library: } ``` -To better understand the output, please refer to the [`Results`][docs-api-results] model in the [API documentation][badge-url-docs]. +To better understand the output, please refer to the [`Results`][docs-results] +section in the [documentation][badge-url-docs]. ## Versioning -The project follows the [Semantic Versioning][semver] guidelines for version management. Currently, the service is in its beta phase, meaning API breaking changes or updates may occur without prior notice. +The project follows the [Semantic Versioning][semver] guidelines for version management. +Currently, the service is in its beta phase, meaning API breaking changes or updates may occur without prior notice. ## Contributing @@ -160,6 +148,6 @@ by email: [semver]: [contact]: [docs-documentation]: -[docs-api-results]: +[docs-results]: [issue-tracker]: [mamba]: diff --git a/docs/conf.py b/docs/conf.py index ece74e8..4323ffd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -38,6 +38,7 @@ extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', + 'sphinx.ext.autosectionlabel' ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/guides/examples.rst b/docs/guides/examples.rst index d9b5873..0718b3b 100644 --- a/docs/guides/examples.rst +++ b/docs/guides/examples.rst @@ -87,10 +87,10 @@ Here is a sample output for the paired-ended library: Results ------- -For more details on the output structure, refer to the :code:`Results` model in the API documentation. - - :code:`library_stats`: Read length statistics results, including the minimum, maximum, mean, median and mode. - :code:`library_source`: Library source inference results, with the short name and NCBI taxonomy ID of the source organism. - :code:`library_type`: Library type inference results, single- or paired-end. In case of paired-end samples, the mate designation. - :code:`read_orientation`: Read orientation inference results, based on the fragment library types notation from `Salmon `_. -- :code:`read_layout`: Read layout inference results, including the 3'-adapter sequence and the poly(A) fraction. \ No newline at end of file +- :code:`read_layout`: Read layout inference results, including the 3'-adapter sequence and the poly(A) fraction. + +For more details on the output structure, refer to the :code:`Results` model in the API documentation. \ No newline at end of file diff --git a/docs/guides/installation.rst b/docs/guides/installation.rst index aa8f9e1..eb44071 100644 --- a/docs/guides/installation.rst +++ b/docs/guides/installation.rst @@ -1,48 +1,57 @@ Installation ============ -This section describes how to install `HTSinfer`. +This section describes how to install `HTSinfer`, either from :ref:`Bioconda` (recommended for most users) or :ref:`GitHub` (for experienced users and developers). -Install using Conda -------------------- - -The easiest and quickest installation method is via `Mamba `_ or `Conda `_. -`HTSinfer` is available as part of the `Bioconda `_ channel. +Both installation methods require the popular package and environment manager `Conda `_ to be available on your system. -To create a new Conda environment with `HTSinfer` and its dependencies installed, run: +.. note:: -.. code-block:: bash + For improved performance, we recommend using Conda's drop-in replacement `Mamba `_ instead. + In that case, simply replace :code:`conda` with :code:`mamba` in all of the commands below. - mamba create --name htsinfer bioconda::htsinfer +Install from Bioconda +--------------------- +The easiest and quickest installation method is to install the latest `HTSinfer` release from `Bioconda `_. -Then, activate the `htsinfer` Conda environment with: +To install `HTSinfer` in your currently active environment, run: .. code-block:: bash - conda activate htsinfer + conda install bioconda::htsinfer +.. note:: -To install `HTSinfer` in your current environment, run: - -.. code-block:: bash - - mamba install bioconda::htsinfer + We do not recommend installing HTSinfer into the default (:code:`base`) environment. + Instead, activate a project- or tool-specific environment with :code:`conda activate MY_CONDA_PROJECT`. + If you do not have such an environment, just create one with :code:`conda create --name MY_CONDA_PROJECT`. + :code:`MY_CONDA_PROJECT` can be any name you like (with some constraints imposed by Conda), e.g., :code:`htsinfer`. Install from GitHub ------------------- -If you would like to contribute to the development of `HTSinfer`, or wishing to use unreleased versions, you can install `HTSinfer` from the `GitHub `_. -First clone the repository and install the dependencies via `Conda `_: +If you wish to use the latest unreleased version of the tool or if you would like to contribute to its further development, +please install `HTSinfer` from `GitHub `_. + +First clone the repository: .. code-block:: bash git clone https://github.com/zavolanlab/htsinfer.git cd htsinfer - mamba env create --file environment.yml - # Alternatively, to install with development dependencies, - # run the following instead - mamba env create --file environment-dev.ymls + +Then, install `HTSinfer` and its dependencies via `Conda `_: + +.. code-block:: bash + + conda env create --file environment.yml + +Alternatively, to include `HTSinfer`'s optional development dependencies, run the following instead: + +.. code-block:: bash + + conda env create --file environment-dev.yml After the installation is complete, activate the :code:`htsinfer` Conda environment with: @@ -50,10 +59,7 @@ After the installation is complete, activate the :code:`htsinfer` Conda environm conda activate htsinfer -Verify the installation (optional) ----------------------------------- - -If you have installed the development or testing dependencies, you can verify that `HTSinfer` was installed correctly by executing the tests shipped with the package: +If you have installed the development dependencies, you can verify that `HTSinfer` was installed correctly by executing the tests shipped with the package: .. code-block:: bash diff --git a/docs/guides/usage.rst b/docs/guides/usage.rst index c06e184..0f3669a 100644 --- a/docs/guides/usage.rst +++ b/docs/guides/usage.rst @@ -35,8 +35,10 @@ Command-line options Available command-line parameters are categorized as follows: -.. list-table:: General Options - :widths: 40 60 +**General options** + +.. list-table:: + :widths: 30 70 * - :code:`--output-directory` - Path where output data will be saved. @@ -52,8 +54,10 @@ Available command-line parameters are categorized as follows: - Show version information and exit. -.. list-table:: Processing and Performance Options - :widths: 40 60 +**Processing and performance options** + +.. list-table:: + :widths: 30 70 * - :code:`--records` - Limits the number of input records to process; setting this to 0 will process all records. @@ -62,29 +66,51 @@ Available command-line parameters are categorized as follows: * - :code:`--tax-id` - Taxonomy ID for the sample source, aiding in organism-specific analyses. -.. list-table:: Library-specific Options - :widths: 40 60 + +**Library-specific options** + +.. list-table:: + :widths: 30 70 * - :code:`PATH [PATH]` - - Path(s) to the RNA-Seq input data. For paired-end libraries, provide paths to both mate files. + - | + | Path(s) to the RNA-Seq input data. + | For paired-end libraries, provide paths to both mate files. * - :code:`--transcripts` - Path to the FASTA file containing transcript sequences for reference. * - :code:`--read-layout-adapters` - - Path to a file with 3' adapter sequences (one sequence per line) used to identify adapter content. + - | + | Path to a file with 3' adapter sequences (one sequence per line) + | used to identify adapter content. * - :code:`--read-layout-min-match-percentage` - - Minimum percentage of reads containing an adapter for\n it to be considered as the library’s 3’-end adapter. + - | + | Minimum percentage of reads containing an adapter + | for it to be considered as the library’s 3’-end adapter. * - :code:`--read-layout-min-frequency-ratio` - - Minimum frequency ratio between the most and second most frequent adapters to select the 3’-end adapter. + - | + | Minimum frequency ratio between the most and second most + | frequent adapters to select the 3’-end adapter. * - :code:`--library-source-min-match-percentage` - - Minimum percentage of reads aligning with a library source for it to be considered representative of the library. + - | + | Minimum percentage of reads aligning with a library source + | for it to be considered representative of the library. * - :code:`--library-source-min-frequency-ratio` - - Minimum frequency ratio between primary and secondary library sources, - ensuring only the most prominent source is identified. + - | + | Minimum frequency ratio between primary and secondary library sources, + | ensuring only the most prominent source is identified. * - :code:`--library-type-max-distance` - - Maximum allowable distance between read pairs to classify the library type. + - | + | Maximum allowable distance between read pairs + | to classify the library type. * - :code:`--library-type-mates-cutoff` - - Ratio cutoff to determine the consistency of mate orientation in paired-end reads. + - | + | Ratio cutoff to determine the consistency + | of mate orientation in paired-end reads. * - :code:`--read-orientation-min-mapped-reads` - - Minimum number of mapped reads to ensure reliable inference of read orientation. + - | + | Minimum number of mapped reads to ensure + | reliable inference of read orientation. * - :code:`--read-orientation-min-fraction` - - Minimum fraction (must exceed 0.5) of reads supporting a given orientation to confirm its accuracy. + - | + | Minimum fraction (must exceed 0.5) of reads + | supporting a given orientation to confirm its accuracy.