From 21695ca1110fea568295352e1f9c23f2a42217ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1t=C3=A9=20Balajti?= Date: Thu, 19 Sep 2024 11:49:28 +0200 Subject: [PATCH 01/23] docs: update RtD page --- docs/api/index.rst | 15 ++++++++++++++ docs/guides/installation.rst | 40 ++++++++++++++++++++++++++++++++++++ 2 files changed, 55 insertions(+) create mode 100644 docs/guides/installation.rst diff --git a/docs/api/index.rst b/docs/api/index.rst index 42e2e565..24ae531b 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -3,6 +3,21 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +Welcome to HTSinfer Documentation! +================================== + +HTSinfer is a tool for high-throughput sequencing inference. + +This documentation will guide you through installation, usage, and the API reference. + +HTSinfer Documentation +======================= + +.. toctree:: + :caption: Contents: + + guides/installation + HTSinfer API docs ================= diff --git a/docs/guides/installation.rst b/docs/guides/installation.rst new file mode 100644 index 00000000..63ca4e79 --- /dev/null +++ b/docs/guides/installation.rst @@ -0,0 +1,40 @@ +Installation Guide +================== + +This section describes how to install HTSinfer using Conda. + +Clone the Repository and Install Dependencies +--------------------------------------------- + +To install HTSinfer, first clone the repository and install the dependencies via `Conda`: + +.. code-block:: bash + + git clone https://github.com/zavolanlab/htsinfer + cd htsinfer + conda env create --file environment.yml + # Alternatively, to install with development dependencies, + # run the following instead + conda env create --file environment-dev.yml + +.. note:: + + Creating the environment may take some time. It is strongly recommended to install `Mamba`_ and replace ``conda`` with ``mamba`` in the previous commands for faster installation. + +Activate the Conda Environment +------------------------------ + +After the installation is complete, activate the `htsinfer` Conda environment with: + +.. code-block:: bash + + 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: + +.. code-block:: bash + + python -m pytest From eac14eda6192441312b54181842b6446a8c91564 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1t=C3=A9=20Balajti?= Date: Thu, 19 Sep 2024 13:40:43 +0200 Subject: [PATCH 02/23] docs: add installation guide --- docs/{api => }/conf.py | 4 ++-- docs/{api => }/index.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) rename docs/{api => }/conf.py (97%) rename docs/{api => }/index.rst (96%) diff --git a/docs/api/conf.py b/docs/conf.py similarity index 97% rename from docs/api/conf.py rename to docs/conf.py index eacbee59..af28a87f 100644 --- a/docs/api/conf.py +++ b/docs/conf.py @@ -17,7 +17,7 @@ from sphinx.ext import apidoc -sys.path.insert(0, os.path.abspath('../..')) +sys.path.insert(0, os.path.abspath('..')) # -- Project information ----------------------------------------------------- @@ -74,7 +74,7 @@ def run_apidoc(_): "--force", "--module-first", "-o", "./modules", - "../../htsinfer" + "../htsinfer" ] + ignore_paths apidoc.main(argv) diff --git a/docs/api/index.rst b/docs/index.rst similarity index 96% rename from docs/api/index.rst rename to docs/index.rst index 24ae531b..5f99c239 100644 --- a/docs/api/index.rst +++ b/docs/index.rst @@ -14,7 +14,7 @@ HTSinfer Documentation ======================= .. toctree:: - :caption: Contents: + :caption: Contents guides/installation From acba20309de487dfdaf339abcc0a21a2e1cdf6a6 Mon Sep 17 00:00:00 2001 From: balajtimate Date: Mon, 21 Oct 2024 15:20:17 +0200 Subject: [PATCH 03/23] docs: add usage and examples pages --- docs/conf.py | 13 ++++++++++--- docs/guides/examples.rst | 2 ++ docs/guides/installation.rst | 4 ++-- docs/guides/usage.rst | 2 ++ docs/index.rst | 19 +++++++------------ 5 files changed, 23 insertions(+), 17 deletions(-) create mode 100644 docs/guides/examples.rst create mode 100644 docs/guides/usage.rst diff --git a/docs/conf.py b/docs/conf.py index af28a87f..b6630504 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -17,7 +17,7 @@ from sphinx.ext import apidoc -sys.path.insert(0, os.path.abspath('..')) +sys.path.insert(0, os.path.abspath('../htsinfer')) # -- Project information ----------------------------------------------------- @@ -46,7 +46,14 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ['_build', 'api/yourpackage.rst'] +exclude_patterns = [ + '_build', + 'api/yourpackage.rst', + 'setup.py', + 'Thumbs.db', + '.DS_Store', + '.eggs' +] # Default doc to search for master_doc = 'index' @@ -61,7 +68,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = [] +html_static_path = ['_static'] # -- Automation ------------------------------------------------------------- diff --git a/docs/guides/examples.rst b/docs/guides/examples.rst new file mode 100644 index 00000000..7d4d0aae --- /dev/null +++ b/docs/guides/examples.rst @@ -0,0 +1,2 @@ +Examples +======== \ No newline at end of file diff --git a/docs/guides/installation.rst b/docs/guides/installation.rst index 63ca4e79..5712d5ec 100644 --- a/docs/guides/installation.rst +++ b/docs/guides/installation.rst @@ -1,5 +1,5 @@ -Installation Guide -================== +Installation +============ This section describes how to install HTSinfer using Conda. diff --git a/docs/guides/usage.rst b/docs/guides/usage.rst new file mode 100644 index 00000000..9fa12ad8 --- /dev/null +++ b/docs/guides/usage.rst @@ -0,0 +1,2 @@ +Usage +===== \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 5f99c239..52351df1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,28 +11,23 @@ HTSinfer is a tool for high-throughput sequencing inference. This documentation will guide you through installation, usage, and the API reference. HTSinfer Documentation -======================= +---------------------- .. toctree:: - :caption: Contents + :maxdepth: 1 guides/installation - -HTSinfer API docs -================= + guides/usage + guides/examples .. toctree:: - :caption: Modules + :caption: API Documentation + :maxdepth: 1 modules/modules -.. toctree:: - :caption: Index - - indices - Indices and tables -================== +------------------ * :ref:`genindex` * :ref:`modindex` From 488d4b756e1964d512bdd33f439dd15ba236d170 Mon Sep 17 00:00:00 2001 From: balajtimate Date: Mon, 21 Oct 2024 17:40:13 +0200 Subject: [PATCH 04/23] docs: update guides --- docs/guides/examples.rst | 86 +++++++++++++++++++++++++++++++++++- docs/guides/installation.rst | 8 ++-- docs/guides/usage.rst | 45 ++++++++++++++++++- 3 files changed, 133 insertions(+), 6 deletions(-) diff --git a/docs/guides/examples.rst b/docs/guides/examples.rst index 7d4d0aae..a93a0444 100644 --- a/docs/guides/examples.rst +++ b/docs/guides/examples.rst @@ -1,2 +1,86 @@ Examples -======== \ No newline at end of file +======== + +HTSinfer provides easy-to-use commands for analyzing single- and paired-ended RNA-Seq libraries. + +Single-ended Library Example +---------------------------- + +To run HTSinfer on a single-ended RNA-Seq library, use the following command: + +.. code-block:: bash + + htsinfer tests/files/adapter_single.fastq + +Paired-ended Library Example +---------------------------- + +To run HTSinfer on a paired-ended RNA-Seq library, use the following command: + +.. code-block:: bash + + htsinfer tests/files/adapter_1.fastq tests/files/adapter_2.fastq + +Both commands will output the results in JSON format to `STDOUT` and the log to `STDERR`. + +Example Output +-------------- + +Here is a sample output for the paired-ended library: + +.. code-block:: json + + { + "library_stats": { + "file_1": { + "read_length": { + "min": 75, + "max": 75, + "mean": 75.0, + "median": 75, + "mode": 75 + } + }, + "file_2": { + "read_length": { + "min": 75, + "max": 75, + "mean": 75.0, + "median": 75, + "mode": 75 + } + } + }, + "library_source": { + "file_1": { + "short_name": "hsapiens", + "taxon_id": "9606" + }, + "file_2": { + "short_name": "hsapiens", + "taxon_id": "9606" + } + }, + "library_type": { + "file_1": "first_mate", + "file_2": "second_mate", + "relationship": "split_mates" + }, + "read_orientation": { + "file_1": "SF", + "file_2": "SR", + "relationship": "ISF" + }, + "read_layout": { + "file_1": { + "adapt_3": "AATGATACGGCGACC", + "polyA_frac": 10.0 + }, + "file_2": { + "adapt_3": "AATGATACGGCGACC", + "polyA_frac": 10.0 + } + } + } + +For more details on the output structure, refer to the `Results` model in the API documentation. diff --git a/docs/guides/installation.rst b/docs/guides/installation.rst index 5712d5ec..14c007d7 100644 --- a/docs/guides/installation.rst +++ b/docs/guides/installation.rst @@ -6,20 +6,20 @@ This section describes how to install HTSinfer using Conda. Clone the Repository and Install Dependencies --------------------------------------------- -To install HTSinfer, first clone the repository and install the dependencies via `Conda`: +To install HTSinfer, first clone the repository and install the dependencies via `Conda `_: .. code-block:: bash - git clone https://github.com/zavolanlab/htsinfer + git clone https://github.com/zavolanlab/htsinfer.git cd htsinfer conda env create --file environment.yml # Alternatively, to install with development dependencies, # run the following instead - conda env create --file environment-dev.yml + conda env create --file environment-dev.ymls .. note:: - Creating the environment may take some time. It is strongly recommended to install `Mamba`_ and replace ``conda`` with ``mamba`` in the previous commands for faster installation. + Creating the environment may take some time. It is strongly recommended to install `Mamba `_ and replace ``conda`` with ``mamba`` in the previous commands for faster installation. Activate the Conda Environment ------------------------------ diff --git a/docs/guides/usage.rst b/docs/guides/usage.rst index 9fa12ad8..7c435d38 100644 --- a/docs/guides/usage.rst +++ b/docs/guides/usage.rst @@ -1,2 +1,45 @@ Usage -===== \ No newline at end of file +===== + +General Usage +------------- + +.. code-block:: bash + + htsinfer [--output-directory PATH] + [--temporary-directory PATH] + [--cleanup-regime {DEFAULT,KEEP_ALL,KEEP_NONE,KEEP_RESULTS}] + [--records INT] + [--threads INT] + [--transcripts FASTA] + [--read-layout-adapters PATH] + [--read-layout-min-match-percentage FLOAT] + [--read-layout-min-frequency-ratio FLOAT] + [--library-source-min-match-percentage FLOAT] + [--library-source-min-frequency-ratio FLOAT] + [--library-type-max-distance INT] + [--library-type-mates-cutoff FLOAT] + [--read-orientation-min-mapped-reads INT] + [--read-orientation-min-fraction FLOAT] + [--tax-id INT] + [--verbosity {DEBUG,INFO,WARN,ERROR,CRITICAL}] + [-h] [--version] + PATH [PATH] + +The above command allows the user to infer metadata for single- or paired-ended RNA-Seq libraries by specifying file paths and relevant parameters. The tool outputs metadata in JSON format to `STDOUT` and logs to `STDERR`. + +Command-line Options +--------------------- + +Available command-line parameters are categorized as follows: + +- **General Options**: These include specifying directories, verbosity level, and other global settings. +- **Library-specific Options**: These parameters allow the user to modify settings related to the input data, such as transcript references, adapter sequences, and match thresholds. +- **Output Options**: These settings control the output format, including the number of records and the output destination. +- **Meta Options**: The user can also control the behavior of the tool with meta options such as cleanup regimes, thread count, and version information. + +For a complete list of all available options, use the following command: + +.. code-block:: bash + + htsinfer --help From f9a1a3b7735cc9f58a1cd529b382c86e25d1c099 Mon Sep 17 00:00:00 2001 From: balajtimate Date: Mon, 21 Oct 2024 17:40:21 +0200 Subject: [PATCH 05/23] docs: update README --- README.md | 116 +++++++++++++++++++++++++++--------------------------- 1 file changed, 59 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index 391892b5..399866d6 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,65 @@ HTSinfer infers metadata from Illumina high-throughput sequencing (HTS) data. +## Quick start +## Installation + +In order to use the HTSinfer, clone the repository and install the +dependencies via [Conda][conda]: + +```sh +git clone https://github.com/zavolanlab/htsinfer +cd htsinfer +conda env create --file environment.yml +# Alternatively, to install with development dependencies, +# run the following instead +conda env create --file environment-dev.yml +``` + +> Note that creating the environment takes non-trivial time and it is strongly +> recommended that you install [Mamba][mamba] and replace `conda` with `mamba` +> in the previous command. + +Then, activate the `htsinfer` Conda environment with: + +```sh +conda activate htsinfer +``` + +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 +``` + +Otherwise just go ahead and try one of the [examples](#Examples). + +## General usage + +```sh +htsinfer [--output-directory PATH] + [--temporary-directory PATH] + [--cleanup-regime {DEFAULT,KEEP_ALL,KEEP_NONE,KEEP_RESULTS}] + [--records INT] + [--threads INT] + [--transcripts FASTA] + [--read-layout-adapters PATH] + [--read-layout-min-match-percentage FLOAT] + [--read-layout-min-frequency-ratio FLOAT] + [--library-source-min-match-percentage FLOAT] + [--library-source-min-frequency-ratio FLOAT] + [--library-type-max-distance INT] + [--library-type-mates-cutoff FLOAT] + [--read-orientation-min-mapped-reads INT] + [--read-orientation-min-fraction FLOAT] + [--tax-id INT] + [--verbosity {DEBUG,INFO,WARN,ERROR,CRITICAL}] + [-h] [--version] + PATH [PATH] +``` + ## Examples **Single-ended library*** @@ -91,63 +150,6 @@ model][docs-api-results] in the [API documentation][badge-url-docs]. Note that possible outcomes. Simply follow the references in each parent model for detailed descriptions of each child model's attributes. -## General usage - -```sh -htsinfer [--output-directory PATH] - [--temporary-directory PATH] - [--cleanup-regime {DEFAULT,KEEP_ALL,KEEP_NONE,KEEP_RESULTS}] - [--records INT] - [--threads INT] - [--transcripts FASTA] - [--read-layout-adapters PATH] - [--read-layout-min-match-percentage FLOAT] - [--read-layout-min-frequency-ratio FLOAT] - [--library-source-min-match-percentage FLOAT] - [--library-source-min-frequency-ratio FLOAT] - [--library-type-max-distance INT] - [--library-type-mates-cutoff FLOAT] - [--read-orientation-min-mapped-reads INT] - [--read-orientation-min-fraction FLOAT] - [--tax-id INT] - [--verbosity {DEBUG,INFO,WARN,ERROR,CRITICAL}] - [-h] [--version] - PATH [PATH] -``` - -## Installation - -In order to use the HTSinfer, clone the repository and install the -dependencies via [Conda][conda]: - -```sh -git clone https://github.com/zavolanlab/htsinfer -cd htsinfer -conda env create --file environment.yml -# Alternatively, to install with development dependencies, -# run the following instead -conda env create --file environment-dev.yml -``` - -> Note that creating the environment takes non-trivial time and it is strongly -> recommended that you install [Mamba][mamba] and replace `conda` with `mamba` -> in the previous command. - -Then, activate the `htsinfer` Conda environment with: - -```sh -conda activate htsinfer -``` - -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 -``` - -Otherwise just go ahead and try one of the [examples](#Examples). ## API documentation From f1b4b4c7251bc36803655ecd116e58eb440e11bc Mon Sep 17 00:00:00 2001 From: balajtimate Date: Mon, 21 Oct 2024 18:17:31 +0200 Subject: [PATCH 06/23] docs: update guides --- docs/_static/custom.css | 4 ++++ docs/conf.py | 1 + docs/guides/examples.rst | 1 + docs/guides/installation.rst | 6 +++--- docs/guides/usage.rst | 2 ++ docs/index.rst | 17 +++++++++++------ 6 files changed, 22 insertions(+), 9 deletions(-) create mode 100644 docs/_static/custom.css diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 00000000..e73a1dd0 --- /dev/null +++ b/docs/_static/custom.css @@ -0,0 +1,4 @@ +/* Increase font size for toctree elements */ +.toctree-l1 { + font-size: 18px; /* Adjust the size as needed */ +} diff --git a/docs/conf.py b/docs/conf.py index b6630504..08c429c3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -88,3 +88,4 @@ def run_apidoc(_): def setup(app): app.connect('builder-inited', run_apidoc) + app.add_css_file('custom.css') diff --git a/docs/guides/examples.rst b/docs/guides/examples.rst index a93a0444..97919dcd 100644 --- a/docs/guides/examples.rst +++ b/docs/guides/examples.rst @@ -3,6 +3,7 @@ Examples HTSinfer provides easy-to-use commands for analyzing single- and paired-ended RNA-Seq libraries. + Single-ended Library Example ---------------------------- diff --git a/docs/guides/installation.rst b/docs/guides/installation.rst index 14c007d7..dd767cc8 100644 --- a/docs/guides/installation.rst +++ b/docs/guides/installation.rst @@ -1,12 +1,12 @@ Installation ============ -This section describes how to install HTSinfer using Conda. +This section describes how to install `HTSinfer` using Conda. Clone the Repository and Install Dependencies --------------------------------------------- -To install HTSinfer, first clone the repository and install the dependencies via `Conda `_: +To install `HTSinfer`, first clone the repository and install the dependencies via `Conda `_: .. code-block:: bash @@ -33,7 +33,7 @@ After the installation is complete, activate the `htsinfer` Conda environment wi 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 or testing 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 7c435d38..1971df49 100644 --- a/docs/guides/usage.rst +++ b/docs/guides/usage.rst @@ -1,6 +1,8 @@ Usage ===== +This sections describes the general usage of `HTSinfer`. + General Usage ------------- diff --git a/docs/index.rst b/docs/index.rst index 52351df1..b623fad3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,15 +3,20 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to HTSinfer Documentation! -================================== +Welcome to the HTSinfer documentation pages! +============================================ -HTSinfer is a tool for high-throughput sequencing inference. +`HTSinfer` is a command-line tool that infers metadata from Illumina high-throughput sequencing (HTS) data. This documentation will guide you through installation, usage, and the API reference. -HTSinfer Documentation ----------------------- +.. toctree:: + :hidden: + + Home + +Documentation +------------- .. toctree:: :maxdepth: 1 @@ -21,7 +26,7 @@ HTSinfer Documentation guides/examples .. toctree:: - :caption: API Documentation + :caption: API Overview :maxdepth: 1 modules/modules From 206d146f9009ded768330e535634105832458b76 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1t=C3=A9=20Balajti?= Date: Thu, 24 Oct 2024 16:09:35 +0200 Subject: [PATCH 07/23] fix README badges --- README.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 62 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 399866d6..6a1f23c8 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ [![release_docker][badge-release-docker]][badge-url-release-docker] [![ci][badge-ci]][badge-url-ci] [![coverage][badge-coverage]][badge-url-coverage] +[![DOI:zenodo][badge-doi-zenodo]][badge-url-doi-zenodo] HTSinfer infers metadata from Illumina high-throughput sequencing (HTS) data. @@ -150,6 +151,63 @@ model][docs-api-results] in the [API documentation][badge-url-docs]. Note that possible outcomes. Simply follow the references in each parent model for detailed descriptions of each child model's attributes. +## General usage + +```sh +htsinfer [--output-directory PATH] + [--temporary-directory PATH] + [--cleanup-regime {DEFAULT,KEEP_ALL,KEEP_NONE,KEEP_RESULTS}] + [--records INT] + [--threads INT] + [--transcripts FASTA] + [--read-layout-adapters PATH] + [--read-layout-min-match-percentage FLOAT] + [--read-layout-min-frequency-ratio FLOAT] + [--library-source-min-match-percentage FLOAT] + [--library-source-min-frequency-ratio FLOAT] + [--library-type-max-distance INT] + [--library-type-mates-cutoff FLOAT] + [--read-orientation-min-mapped-reads INT] + [--read-orientation-min-fraction FLOAT] + [--tax-id INT] + [--verbosity {DEBUG,INFO,WARN,ERROR,CRITICAL}] + [-h] [--version] + PATH [PATH] +``` + +## Installation + +In order to use the HTSinfer, clone the repository and install the +dependencies via [Conda][conda]: + +```sh +git clone https://github.com/zavolanlab/htsinfer +cd htsinfer +conda env create --file environment.yml +# Alternatively, to install with development dependencies, +# run the following instead +conda env create --file environment-dev.yml +``` + +> Note that creating the environment takes non-trivial time and it is strongly +> recommended that you install [Mamba][mamba] and replace `conda` with `mamba` +> in the previous command. + +Then, activate the `htsinfer` Conda environment with: + +```sh +conda activate htsinfer +``` + +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 +``` + +Otherwise just go ahead and try one of the [examples](#Examples). ## API documentation @@ -171,18 +229,20 @@ by email: (c) 2020 [Zavolan lab, Biozentrum, University of Basel][contact] -[badge-ci]: +[badge-ci]: [badge-coverage]: [badge-docs]: [badge-license]: [badge-release-docker]: [badge-release-gh]: -[badge-url-ci]: +[badge-doi-zenodo]: +[badge-url-ci]: [badge-url-coverage]: [badge-url-docs]: [badge-url-license]: [badge-url-release-docker]: [badge-url-release-gh]: +[badge-url-doi-zenodo]: [conda]: [contact]: [docs-api-results]: From db6bd5c154130b5ab2ef25381dbb660ddae714b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1t=C3=A9=20Balajti?= Date: Thu, 31 Oct 2024 14:19:42 +0100 Subject: [PATCH 08/23] docs: update README, guides --- README.md | 102 +++++------------------------------ docs/guides/examples.rst | 10 ++-- docs/guides/installation.rst | 4 +- docs/guides/usage.rst | 38 ++++++++++--- 4 files changed, 52 insertions(+), 102 deletions(-) diff --git a/README.md b/README.md index 6a1f23c8..7557cb76 100644 --- a/README.md +++ b/README.md @@ -11,41 +11,27 @@ HTSinfer infers metadata from Illumina high-throughput sequencing (HTS) data. ## Quick start -## Installation + +For a more in-depth guide please refer to the [HTSinfer documentation][docs-documentation]. + +### Installation In order to use the HTSinfer, clone the repository and install the -dependencies via [Conda][conda]: +dependencies via [Conda][conda] or [Mamba][mamba]: ```sh git clone https://github.com/zavolanlab/htsinfer cd htsinfer conda env create --file environment.yml -# Alternatively, to install with development dependencies, -# run the following instead -conda env create --file environment-dev.yml ``` -> Note that creating the environment takes non-trivial time and it is strongly -> recommended that you install [Mamba][mamba] and replace `conda` with `mamba` -> in the previous command. - Then, activate the `htsinfer` Conda environment with: ```sh conda activate htsinfer ``` -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 -``` - -Otherwise just go ahead and try one of the [examples](#Examples). - -## General usage +### General usage ```sh htsinfer [--output-directory PATH] @@ -69,15 +55,15 @@ htsinfer [--output-directory PATH] PATH [PATH] ``` -## Examples +### Examples -**Single-ended library*** +**Single-ended library** ```sh htsinfer tests/files/adapter_single.fastq ``` -**Paired-ended library*** +**Paired-ended library** ```sh htsinfer tests/files/adapter_1.fastq tests/files/adapter_2.fastq @@ -146,74 +132,13 @@ example library: ``` 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. - -## General usage - -```sh -htsinfer [--output-directory PATH] - [--temporary-directory PATH] - [--cleanup-regime {DEFAULT,KEEP_ALL,KEEP_NONE,KEEP_RESULTS}] - [--records INT] - [--threads INT] - [--transcripts FASTA] - [--read-layout-adapters PATH] - [--read-layout-min-match-percentage FLOAT] - [--read-layout-min-frequency-ratio FLOAT] - [--library-source-min-match-percentage FLOAT] - [--library-source-min-frequency-ratio FLOAT] - [--library-type-max-distance INT] - [--library-type-mates-cutoff FLOAT] - [--read-orientation-min-mapped-reads INT] - [--read-orientation-min-fraction FLOAT] - [--tax-id INT] - [--verbosity {DEBUG,INFO,WARN,ERROR,CRITICAL}] - [-h] [--version] - PATH [PATH] -``` - -## Installation - -In order to use the HTSinfer, clone the repository and install the -dependencies via [Conda][conda]: - -```sh -git clone https://github.com/zavolanlab/htsinfer -cd htsinfer -conda env create --file environment.yml -# Alternatively, to install with development dependencies, -# run the following instead -conda env create --file environment-dev.yml -``` - -> Note that creating the environment takes non-trivial time and it is strongly -> recommended that you install [Mamba][mamba] and replace `conda` with `mamba` -> in the previous command. - -Then, activate the `htsinfer` Conda environment with: - -```sh -conda activate htsinfer -``` - -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 -``` - -Otherwise just go ahead and try one of the [examples](#Examples). +model][docs-api-results] in the [API documentation][badge-url-docs]. -## API documentation +### API documentation Auto-built API documentation is hosted on [ReadTheDocs][badge-url-docs]. -## Contributing +### Contributing This project lives off your contributions, be it in the form of bug reports, feature requests, discussions, or fixes and other code changes. Please refer @@ -221,7 +146,7 @@ to the [contributing guidelines](CONTRIBUTING.md) if you are interested to contribute. Please mind the [code of conduct](CODE_OF_CONDUCT.md) for all interactions with the community. -## Contact +### Contact For questions or suggestions regarding the code, please use the [issue tracker][issue-tracker]. For any other inquiries, please contact us @@ -245,6 +170,7 @@ by email: [badge-url-doi-zenodo]: [conda]: [contact]: +[docs-documentation]: [docs-api-results]: [issue-tracker]: [mamba]: diff --git a/docs/guides/examples.rst b/docs/guides/examples.rst index 97919dcd..a3be4235 100644 --- a/docs/guides/examples.rst +++ b/docs/guides/examples.rst @@ -1,13 +1,13 @@ Examples ======== -HTSinfer provides easy-to-use commands for analyzing single- and paired-ended RNA-Seq libraries. +`HTSinfer` provides easy-to-use commands for analyzing single- and paired-ended RNA-Seq libraries. Single-ended Library Example ---------------------------- -To run HTSinfer on a single-ended RNA-Seq library, use the following command: +To run `HTSinfer` on a single-ended RNA-Seq library, use the following command: .. code-block:: bash @@ -16,13 +16,13 @@ To run HTSinfer on a single-ended RNA-Seq library, use the following command: Paired-ended Library Example ---------------------------- -To run HTSinfer on a paired-ended RNA-Seq library, use the following command: +To run `HTSinfer` on a paired-ended RNA-Seq library, use the following command: .. code-block:: bash htsinfer tests/files/adapter_1.fastq tests/files/adapter_2.fastq -Both commands will output the results in JSON format to `STDOUT` and the log to `STDERR`. +Both commands will output the results in JSON format to :code:`STDOUT` and the log to :code:`STDERR`. Example Output -------------- @@ -84,4 +84,4 @@ Here is a sample output for the paired-ended library: } } -For more details on the output structure, refer to the `Results` model in the API documentation. +For more details on the output structure, refer to the :code:`Results` model in the API documentation. diff --git a/docs/guides/installation.rst b/docs/guides/installation.rst index dd767cc8..c71ea5f3 100644 --- a/docs/guides/installation.rst +++ b/docs/guides/installation.rst @@ -19,12 +19,12 @@ To install `HTSinfer`, first clone the repository and install the dependencies v .. note:: - Creating the environment may take some time. It is strongly recommended to install `Mamba `_ and replace ``conda`` with ``mamba`` in the previous commands for faster installation. + Creating the environment may take some time. It is strongly recommended to install `Mamba `_ and replace :code:`conda` with :code:`mamba` in the previous commands for faster installation. Activate the Conda Environment ------------------------------ -After the installation is complete, activate the `htsinfer` Conda environment with: +After the installation is complete, activate the :code:`htsinfer` Conda environment with: .. code-block:: bash diff --git a/docs/guides/usage.rst b/docs/guides/usage.rst index 1971df49..15b25ce9 100644 --- a/docs/guides/usage.rst +++ b/docs/guides/usage.rst @@ -1,7 +1,7 @@ Usage ===== -This sections describes the general usage of `HTSinfer`. +This section describes the general usage of `HTSinfer`. General Usage ------------- @@ -28,20 +28,44 @@ General Usage [-h] [--version] PATH [PATH] -The above command allows the user to infer metadata for single- or paired-ended RNA-Seq libraries by specifying file paths and relevant parameters. The tool outputs metadata in JSON format to `STDOUT` and logs to `STDERR`. +The above command allows the user to infer metadata for single- or paired-ended RNA-Seq libraries by specifying file paths and relevant parameters. The tool outputs metadata in JSON format to :code:`STDOUT` and logs to :code:`STDERR`. Command-line Options --------------------- Available command-line parameters are categorized as follows: -- **General Options**: These include specifying directories, verbosity level, and other global settings. -- **Library-specific Options**: These parameters allow the user to modify settings related to the input data, such as transcript references, adapter sequences, and match thresholds. -- **Output Options**: These settings control the output format, including the number of records and the output destination. -- **Meta Options**: The user can also control the behavior of the tool with meta options such as cleanup regimes, thread count, and version information. +- **General Options**: + - :code:`--output-directory`: Path where output data will be saved. + - :code:`--temporary-directory`: Path for storing temporary files generated during execution. + - :code:`--cleanup-regime`: Specifies which data should be kept after completion. Available options are :code:`DEFAULT`, :code:`KEEP_ALL`, :code:`KEEP_NONE`, and :code:`KEEP_RESULTS`. + - :code:`--verbosity`: Controls the verbosity level of log output; options are :code:`DEBUG`, :code:`INFO`, :code:`WARN`, :code:`ERROR`, and :code:`CRITICAL`. -For a complete list of all available options, use the following command: +- **Library-specific Options**: + - :code:`PATH [PATH]`: 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. + - :code:`--read-layout-min-match-percentage`: 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. + - :code:`--library-source-min-match-percentage`: 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. + - :code:`--library-type-max-distance`: 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. + - :code:`--read-orientation-min-mapped-reads`: 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. + +- **Processing and Performance Options**: + - :code:`--records`: Limits the number of input records to process; setting this to 0 will process all records. + - :code:`--threads`: Specifies the number of threads for concurrent processing to optimize performance. + - :code:`--tax-id`: Taxonomy ID for the sample source, aiding in organism-specific analyses. + +Meta Options +------------ + +For help or version information, use the following: .. code-block:: bash htsinfer --help + htsinfer --version + From 2b17aca52bc9db89d64eaa86e5ca22033f3b7a5e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1t=C3=A9=20Balajti?= Date: Thu, 31 Oct 2024 14:23:00 +0100 Subject: [PATCH 09/23] update version --- Dockerfile | 2 +- htsinfer/__init__.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Dockerfile b/Dockerfile index 9329b4f3..a12a675a 100644 --- a/Dockerfile +++ b/Dockerfile @@ -5,7 +5,7 @@ FROM continuumio/miniconda3:4.12.0 LABEL base_image="continuumio/miniconda3:4.12.0" LABEL version="1.0" LABEL software="HTSinfer" -LABEL software.version="v0.9.0" +LABEL software.version="v1.0.0" 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/" diff --git a/htsinfer/__init__.py b/htsinfer/__init__.py index 12ac9814..6137c408 100644 --- a/htsinfer/__init__.py +++ b/htsinfer/__init__.py @@ -2,4 +2,4 @@ from htsinfer.htsinfer import HtsInfer # noqa:F401 -__version__ = "0.11.0" +__version__ = "1.0.0" From b3d5d0587090ed838dd9c309b616b6ca3d3ea257 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1t=C3=A9=20Balajti?= Date: Mon, 4 Nov 2024 12:23:10 +0100 Subject: [PATCH 10/23] update rtd config --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 0922ec04..bbfa0038 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -8,7 +8,7 @@ build: tools: python: "mambaforge-4.10" sphinx: - configuration: docs/api/conf.py + configuration: docs/conf.py formats: - pdf - epub From 4623fe25f1d907555065337bdcf84791d240fab2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1t=C3=A9=20Balajti?= Date: Wed, 13 Nov 2024 11:29:18 +0100 Subject: [PATCH 11/23] update versioning --- htsinfer/__init__.py | 2 -- htsinfer/cli.py | 6 ++---- htsinfer/version.py | 3 +++ setup.py | 4 ++-- 4 files changed, 7 insertions(+), 8 deletions(-) create mode 100644 htsinfer/version.py diff --git a/htsinfer/__init__.py b/htsinfer/__init__.py index 6137c408..de38280e 100644 --- a/htsinfer/__init__.py +++ b/htsinfer/__init__.py @@ -1,5 +1,3 @@ """HTSinfer project root""" from htsinfer.htsinfer import HtsInfer # noqa:F401 - -__version__ = "1.0.0" diff --git a/htsinfer/cli.py b/htsinfer/cli.py index 68506000..b0723f96 100644 --- a/htsinfer/cli.py +++ b/htsinfer/cli.py @@ -10,10 +10,8 @@ import sys import tempfile -from htsinfer import ( - HtsInfer, - __version__, -) +from htsinfer import HtsInfer +from htsinfer.version import __version__ from htsinfer.models import ( CleanupRegimes, LogLevels, diff --git a/htsinfer/version.py b/htsinfer/version.py new file mode 100644 index 00000000..257c5c63 --- /dev/null +++ b/htsinfer/version.py @@ -0,0 +1,3 @@ +"""Single source of truth for package version.""" + +__version__ = "1.0.0-rc.1" diff --git a/setup.py b/setup.py index ed2144a3..b8b915a4 100644 --- a/setup.py +++ b/setup.py @@ -1,8 +1,8 @@ """HTSinfer package definition""" -from setuptools import setup, find_packages +from setuptools import (setup, find_packages) -from htsinfer import __version__ +from htsinfer.version import __version__ # Read long description from file with open("README.md", "r", encoding="utf-8") as fh: From 6bfcf1a2cc6411f7abf7a139bebb65b97f0c3c6d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1t=C3=A9=20Balajti?= Date: Wed, 13 Nov 2024 11:32:51 +0100 Subject: [PATCH 12/23] remove docker image and build --- .dockerignore | 8 ------- .github/workflows/ci.yml | 35 ----------------------------- Dockerfile | 48 ---------------------------------------- 3 files changed, 91 deletions(-) delete mode 100644 .dockerignore delete mode 100644 Dockerfile diff --git a/.dockerignore b/.dockerignore deleted file mode 100644 index 2de06c86..00000000 --- a/.dockerignore +++ /dev/null @@ -1,8 +0,0 @@ -* -!data/ -!htsinfer/ -!tests/ -!setup.py -!environment.yml -!LICENSE -!README.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3993e32a..1fd8e310 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -126,38 +126,3 @@ jobs: - name: integration test - paired-ended library run: htsinfer --cleanup-regime=KEEP_NONE --verbosity=DEBUG tests/files/adapter_{1,2}.fastq - publish: - name: build and publish app image - runs-on: ubuntu-latest - if: | - github.event_name == 'push' && - github.ref == format('refs/heads/{0}', github.event.repository.default_branch) - - steps: - - - name: check out repository - uses: actions/checkout@v3 - - - name: generate tag - run: | - echo "TAG=$(date '+%Y%m%d')" >> $GITHUB_ENV - - - name: build and publish image - id: docker - uses: philips-software/docker-ci-scripts@v5.1.0 - with: - dockerfile: . - image-name: "htsinfer" - tags: "latest ${{ env.TAG }}" - push-branches: "${{ github.event.repository.default_branch }}" - env: - REGISTRY_USERNAME: ${{ secrets.DOCKERHUB_LOGIN }} - REGISTRY_TOKEN: "${{ secrets.DOCKERHUB_TOKEN }}" - DOCKER_ORGANIZATION: ${{ secrets.DOCKERHUB_ORG }} - GITHUB_ORGANIZATION: ${{ github.repository_owner }} - - - name: Verify that image was pushed - run: | - echo "Push indicator: ${{ steps.docker.outputs.push-indicator }}" - echo "# Set to 'true' if image was pushed, empty string otherwise" - test "${{ steps.docker.outputs.push-indicator }}" == "true" diff --git a/Dockerfile b/Dockerfile deleted file mode 100644 index a12a675a..00000000 --- a/Dockerfile +++ /dev/null @@ -1,48 +0,0 @@ -###### BASE IMAGE ###### -FROM continuumio/miniconda3:4.12.0 - -####### METADATA ####### -LABEL base_image="continuumio/miniconda3:4.12.0" -LABEL version="1.0" -LABEL software="HTSinfer" -LABEL software.version="v1.0.0" -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="Transcriptomics" - -###### MAINTAINER ###### -LABEL maintainer="Alexander Kanitz " -LABEL maintainer.organisation="Biozentrum, University of Basel" -LABEL maintainer.location="Spitalstrasse 41, CH-4056 Basel, Switzerland" -LABEL maintainer.lab="Zavolan Lab" - -##### INSTALLATION ##### - -# COPY THE YAML & INSTALL SOFTWARE WITH CONDA -WORKDIR /usr/src/app -COPY ./ ./ -RUN conda env create --file environment.yml \ - && conda clean --all - -# VARIABLES -ARG WORKDIR="/home/USER" -ARG USER="USER" -ARG GROUP="GROUP" -ENV PATH="${WORKDIR}:${PATH}" - -# CREATE USER -RUN groupadd -r ${GROUP} && useradd --no-log-init -r -g ${GROUP} ${USER} - -# SET ENVIRONMENT -WORKDIR ${WORKDIR} -RUN chown -R ${USER}:${GROUP} ${WORKDIR} && chmod 700 ${WORKDIR} -USER ${USER} -RUN echo "source activate htsinfer" > ~/.bashrc -ENV PATH /opt/conda/envs/htsinfer/bin:$PATH - -# SET ENTRYPOINT -ENTRYPOINT ["htsinfer"] -CMD ["-h"] From 89da34fed4926461b87c0599cc3bb7be0845d666 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1t=C3=A9=20Balajti?= Date: Wed, 13 Nov 2024 12:27:10 +0100 Subject: [PATCH 13/23] update readme --- README.md | 55 ++++++++++++++++++++++--------------------------------- 1 file changed, 22 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 7557cb76..0b6acce7 100644 --- a/README.md +++ b/README.md @@ -3,12 +3,12 @@ [![license][badge-license]][badge-url-license] [![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] +[![release_biocontainer][badge-release-biocontainer]][badge-url-release-biocontainer] [![DOI:zenodo][badge-doi-zenodo]][badge-url-doi-zenodo] -HTSinfer infers metadata from Illumina high-throughput sequencing (HTS) data. +HTSinfer infers RNA-Seq metadata from Illumina high-throughput sequencing (HTS) data. ## Quick start @@ -16,13 +16,12 @@ For a more in-depth guide please refer to the [HTSinfer documentation][docs-docu ### Installation -In order to use the HTSinfer, clone the repository and install the -dependencies via [Conda][conda] or [Mamba][mamba]: +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 -git clone https://github.com/zavolanlab/htsinfer -cd htsinfer -conda env create --file environment.yml +mamba create --name htsinfer bioconda::htsinfer ``` Then, activate the `htsinfer` Conda environment with: @@ -31,27 +30,16 @@ Then, activate the `htsinfer` Conda environment with: conda activate htsinfer ``` +To install HTSinfer in your current environment, run: + +```sh +mamba install bioconda::htsinfer +``` + ### General usage ```sh -htsinfer [--output-directory PATH] - [--temporary-directory PATH] - [--cleanup-regime {DEFAULT,KEEP_ALL,KEEP_NONE,KEEP_RESULTS}] - [--records INT] - [--threads INT] - [--transcripts FASTA] - [--read-layout-adapters PATH] - [--read-layout-min-match-percentage FLOAT] - [--read-layout-min-frequency-ratio FLOAT] - [--library-source-min-match-percentage FLOAT] - [--library-source-min-frequency-ratio FLOAT] - [--library-type-max-distance INT] - [--library-type-mates-cutoff FLOAT] - [--read-orientation-min-mapped-reads INT] - [--read-orientation-min-fraction FLOAT] - [--tax-id INT] - [--verbosity {DEBUG,INFO,WARN,ERROR,CRITICAL}] - [-h] [--version] +htsinfer [-h] [--verbosity {DEBUG,INFO,WARN,ERROR,CRITICAL}] [--version] PATH [PATH] ``` @@ -131,14 +119,13 @@ example library: } ``` -To better understand the output, please refer to the [`Results` -model][docs-api-results] in the [API documentation][badge-url-docs]. +To better understand the output, please refer to the [`Results`][docs-api-results] model in the [API documentation][badge-url-docs]. -### API documentation +## Versioning -Auto-built API documentation is hosted on [ReadTheDocs][badge-url-docs]. +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 +## Contributing This project lives off your contributions, be it in the form of bug reports, feature requests, discussions, or fixes and other code changes. Please refer @@ -146,7 +133,7 @@ to the [contributing guidelines](CONTRIBUTING.md) if you are interested to contribute. Please mind the [code of conduct](CODE_OF_CONDUCT.md) for all interactions with the community. -### Contact +## Contact For questions or suggestions regarding the code, please use the [issue tracker][issue-tracker]. For any other inquiries, please contact us @@ -158,17 +145,19 @@ by email: [badge-coverage]: [badge-docs]: [badge-license]: -[badge-release-docker]: +[badge-release-biocontainer]: [badge-release-gh]: [badge-doi-zenodo]: [badge-url-ci]: [badge-url-coverage]: [badge-url-docs]: [badge-url-license]: -[badge-url-release-docker]: +[badge-url-release-biocontainer]: [badge-url-release-gh]: [badge-url-doi-zenodo]: [conda]: +[bioconda-release]: +[semver]: [contact]: [docs-documentation]: [docs-api-results]: From 47f3842aa20c57b613995d0d8625f2c84e8c4628 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1t=C3=A9=20Balajti?= Date: Wed, 13 Nov 2024 13:29:15 +0100 Subject: [PATCH 14/23] update versioning --- docs/conf.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 08c429c3..ece74e88 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,4 +1,4 @@ -from htsinfer import __version__ +from htsinfer.version import __version__ # Configuration file for the Sphinx documentation builder. # @@ -48,9 +48,7 @@ # This pattern also affects html_static_path and html_extra_path. exclude_patterns = [ '_build', - 'api/yourpackage.rst', 'setup.py', - 'Thumbs.db', '.DS_Store', '.eggs' ] From 125289960f0d2868df822958c1c4c2182ed13101 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1t=C3=A9=20Balajti?= Date: Fri, 15 Nov 2024 08:29:25 +0100 Subject: [PATCH 15/23] update guides --- docs/guides/usage.rst | 62 ++++++++++++++++++++++++------------------- docs/index.rst | 4 +-- 2 files changed, 36 insertions(+), 30 deletions(-) diff --git a/docs/guides/usage.rst b/docs/guides/usage.rst index 15b25ce9..d7525b95 100644 --- a/docs/guides/usage.rst +++ b/docs/guides/usage.rst @@ -35,37 +35,43 @@ Command-line Options Available command-line parameters are categorized as follows: -- **General Options**: - - :code:`--output-directory`: Path where output data will be saved. - - :code:`--temporary-directory`: Path for storing temporary files generated during execution. - - :code:`--cleanup-regime`: Specifies which data should be kept after completion. Available options are :code:`DEFAULT`, :code:`KEEP_ALL`, :code:`KEEP_NONE`, and :code:`KEEP_RESULTS`. - - :code:`--verbosity`: Controls the verbosity level of log output; options are :code:`DEBUG`, :code:`INFO`, :code:`WARN`, :code:`ERROR`, and :code:`CRITICAL`. +.. table:: General Options + :widths: 25, 75 -- **Library-specific Options**: - - :code:`PATH [PATH]`: 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. - - :code:`--read-layout-min-match-percentage`: 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. - - :code:`--library-source-min-match-percentage`: 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. - - :code:`--library-type-max-distance`: 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. - - :code:`--read-orientation-min-mapped-reads`: 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. +.. table:: General Options + :widths: 25, 75 -- **Processing and Performance Options**: - - :code:`--records`: Limits the number of input records to process; setting this to 0 will process all records. - - :code:`--threads`: Specifies the number of threads for concurrent processing to optimize performance. - - :code:`--tax-id`: Taxonomy ID for the sample source, aiding in organism-specific analyses. + | Option | Description | + |---|---| + | :code:`--output-directory PATH` | Path where output data will be saved. | + | :code:`--temporary-directory PATH` | Path for storing temporary files generated during execution. | + | :code:`--cleanup-regime {DEFAULT,KEEP_ALL,KEEP_NONE,KEEP_RESULTS}` | Specifies which data should be kept after completion. | + | :code:`--verbosity {DEBUG,INFO,WARN,ERROR,CRITICAL}` | Controls the verbosity level of log output. | + | :code:`-h, --help` | Show help screen and exit. | + | :code:`--version` | Show version information and exit. | -Meta Options ------------- +.. table:: Library-specific Options + :widths: 25, 75 -For help or version information, use the following: + | Option | Description | + |---|---| + | `PATH [PATH]` | Path(s) to the RNA-Seq input data. For paired-end libraries, provide paths to both mate files. | + | `--transcripts FASTA` | Path to the FASTA file containing transcript sequences for reference. | + | `--read-layout-adapters PATH` | Path to a file with 3' adapter sequences (one sequence per line) used to identify adapter content. | + | `--read-layout-min-match-percentage FLOAT` | Minimum percentage of reads containing an adapter for it to be considered as the library’s 3’-end adapter. | + | `--read-layout-min-frequency-ratio FLOAT` | Minimum frequency ratio between the most and second most frequent adapters to select the 3’-end adapter. | + | `--library-source-min-match-percentage FLOAT` | Minimum percentage of reads aligning with a library source for it to be considered representative of the library. | + | `--library-source-min-frequency-ratio FLOAT` | Minimum frequency ratio between primary and secondary library sources, ensuring only the most prominent source is identified. | + | `--library-type-max-distance INT` | Maximum allowable distance between read pairs to classify the library type. | + | `--library-type-mates-cutoff FLOAT` | Ratio cutoff to determine the consistency of mate orientation in paired-end reads. | + | `--read-orientation-min-mapped-reads INT` | Minimum number of mapped reads to ensure reliable inference of read orientation. | + | `--read-orientation-min-fraction FLOAT` | Minimum fraction (must exceed 0.5) of reads supporting a given orientation to confirm its accuracy. | -.. code-block:: bash - - htsinfer --help - htsinfer --version +.. table:: Processing and Performance Options + :widths: 25, 75 + | Option | Description | + |---|---| + | `--records INT` | Limits the number of input records to process; setting this to 0 will process all records. | + | `--threads INT` | Specifies the number of threads for concurrent processing to optimize performance. | + | `--tax-id INT` | Taxonomy ID for the sample source, aiding in organism-specific analyses. | diff --git a/docs/index.rst b/docs/index.rst index b623fad3..1b241c63 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,9 +6,9 @@ Welcome to the HTSinfer documentation pages! ============================================ -`HTSinfer` is a command-line tool that infers metadata from Illumina high-throughput sequencing (HTS) data. +`HTSinfer` is a command-line tool that infers RNA-Seq metadata from Illumina high-throughput sequencing (HTS) data. -This documentation will guide you through installation, usage, and the API reference. +This documentation will guide you through installation and usage. It also contains an API reference. .. toctree:: :hidden: From f36c81243a93da43b83fb2f18f007eb0d25c27f2 Mon Sep 17 00:00:00 2001 From: balajtimate Date: Fri, 15 Nov 2024 10:40:45 +0100 Subject: [PATCH 16/23] update usage guide with tables --- docs/guides/usage.rst | 81 +++++++++++++++++++++++++------------------ 1 file changed, 47 insertions(+), 34 deletions(-) diff --git a/docs/guides/usage.rst b/docs/guides/usage.rst index d7525b95..4c7631e5 100644 --- a/docs/guides/usage.rst +++ b/docs/guides/usage.rst @@ -35,43 +35,56 @@ Command-line Options Available command-line parameters are categorized as follows: -.. table:: General Options - :widths: 25, 75 +.. list-table:: General Options + :widths: 40 60 -.. table:: General Options - :widths: 25, 75 + * - :code:`--output-directory` + - Path where output data will be saved. + * - :code:`--temporary-directory` + - Path for storing temporary files generated during execution. + * - :code:`--cleanup-regime` + - Specifies which data should be kept after completion. Options are: :code:`DEFAULT, KEEP_ALL, KEEP_NONE, KEEP_RESULTS` + * - :code:`--verbosity` + - Controls the verbosity level of log output. Options are: :code:`DEBUG, INFO, WARN, ERROR, CRITICAL` + * - :code:`-h, --help` + - Show help screen and exit. + * - :code:`-v, --version` + - Show version information and exit. - | Option | Description | - |---|---| - | :code:`--output-directory PATH` | Path where output data will be saved. | - | :code:`--temporary-directory PATH` | Path for storing temporary files generated during execution. | - | :code:`--cleanup-regime {DEFAULT,KEEP_ALL,KEEP_NONE,KEEP_RESULTS}` | Specifies which data should be kept after completion. | - | :code:`--verbosity {DEBUG,INFO,WARN,ERROR,CRITICAL}` | Controls the verbosity level of log output. | - | :code:`-h, --help` | Show help screen and exit. | - | :code:`--version` | Show version information and exit. | -.. table:: Library-specific Options - :widths: 25, 75 +.. list-table:: Processing and Performance Options + :widths: 40 60 - | Option | Description | - |---|---| - | `PATH [PATH]` | Path(s) to the RNA-Seq input data. For paired-end libraries, provide paths to both mate files. | - | `--transcripts FASTA` | Path to the FASTA file containing transcript sequences for reference. | - | `--read-layout-adapters PATH` | Path to a file with 3' adapter sequences (one sequence per line) used to identify adapter content. | - | `--read-layout-min-match-percentage FLOAT` | Minimum percentage of reads containing an adapter for it to be considered as the library’s 3’-end adapter. | - | `--read-layout-min-frequency-ratio FLOAT` | Minimum frequency ratio between the most and second most frequent adapters to select the 3’-end adapter. | - | `--library-source-min-match-percentage FLOAT` | Minimum percentage of reads aligning with a library source for it to be considered representative of the library. | - | `--library-source-min-frequency-ratio FLOAT` | Minimum frequency ratio between primary and secondary library sources, ensuring only the most prominent source is identified. | - | `--library-type-max-distance INT` | Maximum allowable distance between read pairs to classify the library type. | - | `--library-type-mates-cutoff FLOAT` | Ratio cutoff to determine the consistency of mate orientation in paired-end reads. | - | `--read-orientation-min-mapped-reads INT` | Minimum number of mapped reads to ensure reliable inference of read orientation. | - | `--read-orientation-min-fraction FLOAT` | Minimum fraction (must exceed 0.5) of reads supporting a given orientation to confirm its accuracy. | + * - :code:`--records` + - Limits the number of input records to process; setting this to 0 will process all records. + * - :code:`--threads` + - Specifies the number of threads for STAR to optimize performance. + * - :code:`--tax-id` + - Taxonomy ID for the sample source, aiding in organism-specific analyses. -.. table:: Processing and Performance Options - :widths: 25, 75 +.. list-table:: Library-specific Options + :widths: 40 60 - | Option | Description | - |---|---| - | `--records INT` | Limits the number of input records to process; setting this to 0 will process all records. | - | `--threads INT` | Specifies the number of threads for concurrent processing to optimize performance. | - | `--tax-id INT` | Taxonomy ID for the sample source, aiding in organism-specific analyses. | + * - :code:`PATH [PATH]` + - 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. + * - :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. + * - :code:`--read-layout-min-frequency-ratio` + - 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. + * - :code:`--library-source-min-frequency-ratio` + - 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. + * - :code:`--library-type-mates-cutoff` + - 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. + * - :code:`--read-orientation-min-fraction` + - Minimum fraction (must exceed 0.5) of reads supporting a given orientation to confirm its accuracy. From 21f72f0837d839c56797950663dc8c63566bb965 Mon Sep 17 00:00:00 2001 From: balajtimate Date: Fri, 15 Nov 2024 10:51:00 +0100 Subject: [PATCH 17/23] update Results model description --- htsinfer/models.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/htsinfer/models.py b/htsinfer/models.py index 872e4135..8485974d 100644 --- a/htsinfer/models.py +++ b/htsinfer/models.py @@ -328,14 +328,16 @@ class Results(BaseModel): functionalities. Args: + library_stats: Read length statistics results. library_type: Library type inference results. library_source: Library source inference results. - orientation: Read orientation inference results. + read_orientation: Read orientation inference results. read_layout: Read layout inference results. - Args: - type: Library type inference results. - source: Library source inference results. + Attributes: + library_stats: Read length statistics results. + library_type: Library type inference results. + library_source: Library source inference results. read_orientation: Read orientation inference results. read_layout: Read layout inference results. """ From 3971d5efb0bc48ccd35123e564b3ddc16178b7c2 Mon Sep 17 00:00:00 2001 From: balajtimate Date: Fri, 15 Nov 2024 12:26:23 +0100 Subject: [PATCH 18/23] docs: update index, restructure API docs --- docs/guides/examples.rst | 9 +++++++ docs/guides/installation.rst | 46 ++++++++++++++++++++++++++---------- docs/index.rst | 13 +++------- docs/indices_and_tables.rst | 8 +++++++ 4 files changed, 53 insertions(+), 23 deletions(-) create mode 100644 docs/indices_and_tables.rst diff --git a/docs/guides/examples.rst b/docs/guides/examples.rst index a3be4235..9f2ad42c 100644 --- a/docs/guides/examples.rst +++ b/docs/guides/examples.rst @@ -84,4 +84,13 @@ 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 diff --git a/docs/guides/installation.rst b/docs/guides/installation.rst index c71ea5f3..d7341568 100644 --- a/docs/guides/installation.rst +++ b/docs/guides/installation.rst @@ -1,28 +1,48 @@ Installation ============ -This section describes how to install `HTSinfer` using Conda. +This section describes how to install `HTSinfer`. -Clone the Repository and Install Dependencies ---------------------------------------------- +Install using Conda +------------------- -To install `HTSinfer`, first clone the repository and install the dependencies via `Conda `_: +The easiest and quickest installation method is via `Mamba `_ or `Conda `_. +`HTSinfer` is available as part of the `Bioconda `_ channel. + +To create a new Conda environment with `HTSinfer` and its dependencies installed, run: + +.. code-block:: bash + + mamba create --name htsinfer bioconda::htsinfer + + +Then, activate the `htsinfer` Conda environment with: + +.. code-block:: bash + + conda activate htsinfer + + +To install `HTSinfer` in your current environment, run: + +.. code-block:: bash + + mamba install bioconda::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 `_: .. code-block:: bash git clone https://github.com/zavolanlab/htsinfer.git cd htsinfer - conda env create --file environment.yml + mamba env create --file environment.yml # Alternatively, to install with development dependencies, # run the following instead - conda env create --file environment-dev.ymls - -.. note:: - - Creating the environment may take some time. It is strongly recommended to install `Mamba `_ and replace :code:`conda` with :code:`mamba` in the previous commands for faster installation. - -Activate the Conda Environment ------------------------------- + mamba env create --file environment-dev.ymls After the installation is complete, activate the :code:`htsinfer` Conda environment with: diff --git a/docs/index.rst b/docs/index.rst index 1b241c63..404304e1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,10 +15,8 @@ This documentation will guide you through installation and usage. It also contai Home -Documentation -------------- - .. toctree:: + :caption: Documentation :maxdepth: 1 guides/installation @@ -26,14 +24,9 @@ Documentation guides/examples .. toctree:: - :caption: API Overview + :caption: API overview :maxdepth: 1 modules/modules - -Indices and tables ------------------- - -* :ref:`genindex` -* :ref:`modindex` + indices_and_tables diff --git a/docs/indices_and_tables.rst b/docs/indices_and_tables.rst new file mode 100644 index 00000000..63d1b81d --- /dev/null +++ b/docs/indices_and_tables.rst @@ -0,0 +1,8 @@ +Indices and tables +------------------ + +.. toctree:: + :maxdepth: 1 + + genindex + modindex \ No newline at end of file From 140c918451d5e79e2a413cdd6d8c969191aa9d75 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1t=C3=A9=20Balajti?= Date: Fri, 15 Nov 2024 13:44:22 +0100 Subject: [PATCH 19/23] update style --- docs/guides/examples.rst | 6 +++--- docs/guides/installation.rst | 2 +- docs/guides/usage.rst | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/guides/examples.rst b/docs/guides/examples.rst index 9f2ad42c..d9b58730 100644 --- a/docs/guides/examples.rst +++ b/docs/guides/examples.rst @@ -4,7 +4,7 @@ Examples `HTSinfer` provides easy-to-use commands for analyzing single- and paired-ended RNA-Seq libraries. -Single-ended Library Example +Single-ended library example ---------------------------- To run `HTSinfer` on a single-ended RNA-Seq library, use the following command: @@ -13,7 +13,7 @@ To run `HTSinfer` on a single-ended RNA-Seq library, use the following command: htsinfer tests/files/adapter_single.fastq -Paired-ended Library Example +Paired-ended library example ---------------------------- To run `HTSinfer` on a paired-ended RNA-Seq library, use the following command: @@ -24,7 +24,7 @@ To run `HTSinfer` on a paired-ended RNA-Seq library, use the following command: Both commands will output the results in JSON format to :code:`STDOUT` and the log to :code:`STDERR`. -Example Output +Example output -------------- Here is a sample output for the paired-ended library: diff --git a/docs/guides/installation.rst b/docs/guides/installation.rst index d7341568..aa8f9e11 100644 --- a/docs/guides/installation.rst +++ b/docs/guides/installation.rst @@ -50,7 +50,7 @@ After the installation is complete, activate the :code:`htsinfer` Conda environm conda activate htsinfer -Verify the Installation (Optional) +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: diff --git a/docs/guides/usage.rst b/docs/guides/usage.rst index 4c7631e5..c06e1842 100644 --- a/docs/guides/usage.rst +++ b/docs/guides/usage.rst @@ -3,7 +3,7 @@ Usage This section describes the general usage of `HTSinfer`. -General Usage +General usage ------------- .. code-block:: bash @@ -30,7 +30,7 @@ General Usage The above command allows the user to infer metadata for single- or paired-ended RNA-Seq libraries by specifying file paths and relevant parameters. The tool outputs metadata in JSON format to :code:`STDOUT` and logs to :code:`STDERR`. -Command-line Options +Command-line options --------------------- Available command-line parameters are categorized as follows: From 8223260d861e497f7bf10fb6de003f2f1300c956 Mon Sep 17 00:00:00 2001 From: balajtimate Date: Mon, 18 Nov 2024 19:41:55 +0100 Subject: [PATCH 20/23] 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 0b6acce7..0e0a71b7 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 ece74e88..4323ffde 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 d9b58730..0718b3ba 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 aa8f9e11..eb440713 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 c06e1842..0f3669a7 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. From 316c173012aa94c5051d1e2d83c3538ec5ff377e Mon Sep 17 00:00:00 2001 From: balajtimate Date: Mon, 18 Nov 2024 19:44:29 +0100 Subject: [PATCH 21/23] update conf exclusions --- docs/conf.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 4323ffde..1f545f8d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -48,10 +48,7 @@ # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. exclude_patterns = [ - '_build', 'setup.py', - '.DS_Store', - '.eggs' ] # Default doc to search for From d9f56fa80ad9d34629c738cd738cc168f5397643 Mon Sep 17 00:00:00 2001 From: balajtimate Date: Mon, 18 Nov 2024 19:53:30 +0100 Subject: [PATCH 22/23] update conf exclusions --- docs/conf.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 1f545f8d..d0f9a45a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -49,6 +49,8 @@ # This pattern also affects html_static_path and html_extra_path. exclude_patterns = [ 'setup.py', + '.DS_Store', + '.eggs' ] # Default doc to search for From f231a5422017b63e2964dd6027bf7b0be4c958ec Mon Sep 17 00:00:00 2001 From: balajtimate Date: Mon, 18 Nov 2024 19:53:35 +0100 Subject: [PATCH 23/23] update conf exclusions --- docs/conf.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index d0f9a45a..fc96dc7f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -48,9 +48,7 @@ # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. exclude_patterns = [ - 'setup.py', - '.DS_Store', - '.eggs' + 'setup.py' ] # Default doc to search for