<commit_before>Extending piquant
=================

*piquant* is designed to be extensible in three principal ways:

* :ref:`extending-adding-new-quantifiers`: Adding an additional quantification tool or pipeline whose comparative performance can then be assessed.
* :ref:`extending-adding-new-statistics`: Adding an additional statistic to be calculated for each quantification run.
* :ref:`extending-adding-new-classifiers`: Adding an additional classifier to split transcripts into discrete groups, so that the performance of quantification tools can be assessed across these sets of transcripts.

All three methods of extension currently require some coding in Python.

.. _extending-adding-new-quantifiers:

Adding a new quantifier
-----------------------

To enable *piquant* to run a particular quantification tool or pipeline, a new class should be added to the Python module ``quantifiers.py``, marked with the decorator ``@_Quantifier``, and fulfilling the API requirements detailed below. Any such tool will then be automatically available to be included in quantification runs from the *piquant* command line.

A quantifier class has three main responsibilities:

* It must supply commands to be written to ``run_quantification.sh`` scripts that will be executed when the scripts are run with the command line flag ``-p``; that is, preparatory actions that must be taken prior to quantifying transcripts with this quantificaton tool, but that only need to be executed once for a particular set of input transcripts and genome sequences.
* It must supply commands to be written to ``run_quantification.sh`` scripts that will be executed when the scripts are run with the command line flag ``-q``; that is, actions that must be taken to calculate transcript abundances with this quantification tool for a particular set of simulated reads.
* It must specify a file that contains the transcript abundance estimates calculated by the quantification tool, and know how to extract the calculated abundance for a particular transcript from this file.

In detail, in addition to being marked with the decorator ``@_Quantifier``, a quantifier class should implement the following methods:

``get_name()``

TODO

``write_preparatory_commands(writer, params)``

TODO

``write_quantification_commands(writer, params)``

TODO

``write_post_quantification_cleanup(writer)``

TODO

``get_results_file()``

TODO

``read_transcript_abundances(quant_file)``

TODO

``get_transcript_abundance(transcript_id)``

TODO

.. _extending-adding-new-statistics:

Adding a new statistic<commit_msg>Start documenting the quantifier API.<commit_after>Extending piquant
=================

*piquant* is designed to be extensible in three principal ways:

* :ref:`extending-adding-new-quantifiers`: Adding an additional quantification tool or pipeline whose comparative performance can then be assessed.
* :ref:`extending-adding-new-statistics`: Adding an additional statistic to be calculated for each quantification run.
* :ref:`extending-adding-new-classifiers`: Adding an additional classifier to split transcripts into discrete groups, so that the performance of quantification tools can be assessed across these sets of transcripts.

All three methods of extension currently require some coding in Python.

.. _extending-adding-new-quantifiers:

Adding a new quantifier
-----------------------

To enable *piquant* to run a particular quantification tool or pipeline, a new class should be added to the Python module ``quantifiers.py``, marked with the decorator ``@_Quantifier``, and fulfilling the API requirements detailed below. Any such tool will then be automatically available to be included in quantification runs from the *piquant* command line.

A quantifier class has three main responsibilities:

* It must supply commands to be written to ``run_quantification.sh`` scripts that will be executed when the scripts are run with the command line flag ``-p``; that is, preparatory actions that must be taken prior to quantifying transcripts with this quantification tool, but that only need to be executed once for a particular set of input transcripts and genome sequences.
* It must supply commands to be written to ``run_quantification.sh`` scripts that will be executed when the scripts are run with the command line flag ``-q``; that is, actions that must be taken to calculate transcript abundances with this quantification tool for a particular set of simulated reads.
* It must specify a file that contains the transcript abundance estimates calculated by the quantification tool, and know how to extract the calculated abundance for a particular transcript from this file.

In detail, in addition to being marked with the decorator ``@_Quantifier``, a quantifier class should implement the following methods:

``get_name()``

``get_name`` should return the string to be given when specifying a list of quantifiers to be used by *piquant* via the command-line or parameters file option ``--quant-method``.

``write_preparatory_commands(writer, params)``

``write_preparatory_commands`` writes commands to a ``run_quantification.sh`` script that should be executed prior to quantifying transcripts with the particular quantification tool, but that only need to be executed once for a particular set of input transcripts and genome sequences - for example, preparing a Bowtie index for the genome, or constructing transcript sequences.

Commands are written via the ``writer`` parameter, an instance of the BashScriptWriter class (see :ref:`extending-bash-script-writer below`), which facilitates writing commands to a Bash script.

``write_quantification_commands(writer, params)``

TODO

``write_post_quantification_cleanup(writer)``

TODO

``get_results_file()``

TODO

``read_transcript_abundances(quant_file)``

TODO

``get_transcript_abundance(transcript_id)``

TODO

.. _extending-bash-script-writer:

The BashScriptWriter class
^^^^^^^^^^^^^^^^^^^^^^^^^^

TODO

.. _extending-adding-new-statistics:

Adding a new statistic
{'fraction_non_alphanumeric': 0.07729308343008791, 'fraction_numerical': 0.0, 'mean_word_length': 5.340694006309148, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1411653', 'n_tokens_mistral': 1513, 'n_tokens_neox': 1411, 'n_words': 744}