Check and refine the direction of reactions
===========================================

Most databases (e.g. KEGG) that are used to generate and curate metabolic models automatically, do not save 
the directionality of reactions. This can become a problem in downstream analyses as the direction of 
reactions is important for the correctness of the model. Since the direction of a reaction is often missing from databases, 
the default is to set the reaction to reversible. However, in the worst case, wrongly set reaction directions 
can be the cause of energy generating cycles (EGCs), which are thermodynamically infeasible. 

One of the few databases to reliably store information about a large number of reactions is `MetaCyc <https://metacyc.org>`_ / `BioCyc <https://biocyc.org>`_ .
The :py:func:`~refinegems.curation.curate.check_direction` function enables the user to check the 
directions of reactions in a metabolic model against a given either species-specific BioCyc or general MetaCyc database 
table containing the information about the direction of reactions. 

The table should contain all reactions (of interest) and it **MUST** contain the following columns:

- `Reaction`: contains the MetaCyc ID
- `EC-Number`: contains the EC number associated with the reactions (EC-X.X.X.X) or nan
- `KEGG reaction`: contains the href link to the associated KEGG reaction or nan
- `METANETX`: contains the href link to the associated MetaNetX reaction or nan
- `Reaction-Direction`: contains a string describing the directionality of the reaction

How to get the table from BioCyc
""""""""""""""""""""""""""""""""
1. If you have no BioCyc account you will need to create one. See `BioCyc Create Free Account <https://biocyc.org/new-account.shtml>`__ to create an account. 
2. Then you need to search for your specific organism, i.e. the exact strain, and change to the corresponding organism database.
   In case you want to use MetaCyc, you have to switch to the MetaCyc database.
3. Within the chosen database you need to click on `Tools` in the menu bar and select `Special SmartTables` under `SmartTables`.
   (There you need to make an adjustable copy of the table "All reactions of <organism>/MetaCyc".)
4. Then follow these steps to obtain the table:

    i. Select the column 'Reaction',
    ii. then select
    
        a. 'Database Links'
        b. and 'Reaction-Direction'

        under `ADD COLUMN` and click `submit`.
    iii. From the popup select `KEGG reaction` and `METANETX` under `Database Links` and click `Go`.
    iv. [Optional] If you want the specified order you can click on the 'Reaction-Direction' column, then select `Move` and then `Move Column Full Right`.
    v. Finally, click `Export to Spreadsheet File` in the box on the right side and choose `frame IDs`.

The resulting table should look like this (start of the downloaded file):

.. code-block:: text

    Reaction	EC-Number	KEGG reaction	METANETX	Reaction-Direction
    RXN-22670	EC-6.3.2			PHYSIOL-LEFT-TO-RIGHT
    RXN-9464	EC-3.3.2.8		<a href='https://www.metanetx.org/equa_info/~A'>MNXR122834</a>	PHYSIOL-LEFT-TO-RIGHT

..  note::

    The requested format is automatically generated by BioCyc by choosing all reactions for a smart table
    and adding the properties described above as columns and finally exporting it as a `txt`-file.