This tool computes the completeness of each KEGG pathway module for given set of KEGG orthologues (KOs) based on their presence/absence. The current version of this tool has 495 KEGG modules (updated 06/12/2024).
Please, read the Theory section at the bottom of this README for a detailed explanation.
- per contig annotation with KOs (ideally given from hmmscan annotation (see instructions));
OR
- list of KOs.
*_pathways.tsv(example) contains module pathways completeness calculated for all KOs in the given input file.
Optional:
*_contigs.tsv(example) contains module pathways completeness calculated per each contig (first column contains name of contig).pathways_plots/(example) folder containing PNG representation and graphs generated with--plot-pathwaysargument.*.with_weights.tsvexample of output generated with--include-weightsargument. Each KO has a weight in brackets.
Check more examples of different output files here.
This tool was published in Pypi and Bioconda.
Docker container is available on DockerHub and Quay.
pip install kegg-pathways-completeness
Follow bioconda instructions
docker pull quay.io/biocontainers/kegg-pathways-completeness
git clone https://github.com/EBI-Metagenomics/kegg-pathways-completeness-tool.git
cd kegg-pathways-completeness-tool
pip install .
# --- Using list of KOs
# simple run
give_completeness -l {INPUT_LIST}
# test example:
# give_completeness \
# --input-list 'tests/fixtures/give_completeness/test_kos.txt' \
# --outprefix test_list_kos \
# --list-separator ','
# --- per contig annotation with KOs
# simple run
give_completeness -i {INPUT_FILE}
# test example:
# give_completeness \
# --input 'tests/fixtures/give_completeness/test_pathway.txt' \
# --outprefix test_pathway \
# --add-per-contig \
Required arguments:
input file:
An input file is required under either of the following commands:
- input table (
-i/--input): hmmsearch table (example) that was run on KEGG profiles DB with annotated sequences (preferable). If you don't have this table, follow instructions to generate it. - file with KOs list (
-l/--input-list): file with list of KOs (example).
Optional arguments:
- KOs separator for list option (
-s/--list-separator): default is,(comma) - output directory (
-o/--outdir): default is currently working directory - output prefix (
-r/--outprefix): prefix for output tables (-r test_kosin example) - add weight information to output files (
-w/--include-weights). The output table will contain the weight of each KO edge in the pathway graph, for example K00942(0.25) means that the KO has 0.25 importance in the given pathway. Example of output. - plot present KOs in pathways (
-p/--plot-pathways): generates a PNG containing a schematic representation of the pathway. Presented KOs are marked with red edges. Example: M00002. - generate a table with per-contig modules completeness (
-m/--add-per-contig): generates*_contigs.tsvcalculating completeness per each contig for each module. That option makes sense to use only with--inputcontaining information about contigs. If you send a list of KOs as input that means you do not provide information about contigs and*_contigs.tsvand*_pathways.tsvwould be identical. Example.
This repository contains a set of pre-generated files. Modules information files can be found in pathways_data. The repository also contains pre-parsed module pathways into graphs format. In order to generate graphs all pathways were parsed with the NetworkX library.
modules information:
- list of KEGG modules in KOs notation (
-a/--definitions) (latest all_pathways.txt) - list of classes of KEGG modules (
-c/--classes) (latest all_pathways_class.txt) - list of names of KEGG modules (
-n/--names) (latest all_pathways_names.txt)
graphs:
- graphs constructed from each module (
-g/--graphs) (latest graphs.pkl))
Latest release has a plots archive with images and graphviz-files for all modules. The graph for every module is shown in .png format in png folder and contains corresponding graphviz file in graphs folder. Pathway and weights of each KO can be easily checked with the .png image.
In order to run a tool there is no need to re-generate those files.
All module data generation commands and graphs creation instructions are also available for updates and understanding a process.
NOTE: please make sure you have graphviz installed
You can also run the plotting script separately:
plot_modules_graphs.py -l tests/fixtures/plot_modules_graphs/modules_list.txt
plot_modules_graphs.py -i tests/outputs/give_completeness/test_kos_pathways.tsv
More examples for test data here.
KEGG provides a representation of each pathway as a specific expression of KOs.
Example A ((B,C) D,E) -- (A+F-G) where:
- A, B, C, D, E, F, G are KOs
- space == AND
- comma == OR
- plus == essential component
- minus == optional component
- minus minus == missing optional component (replaced into K00000 with 0 weight (example: KEGG, corresponding graph))
- new line == mediator (example: KEGG, corresponding graph)
There are some modules that have DEFINITION with line separated KOs. Those KOs are interpreted as mediators. Each line is connected with AND operator. It is considered that each line plays a crucial role into module that is why it influences weights assignment quite much.
All list of those modules presented in definition_separated.txt.
The question is how to use mediators is very difficult for current realisation and is under debate.
Each expression was converted into a directed graph using NetworkX. The first node is node 0 and the last one is node 1. Each edge corresponds to a KO.
In order to compute pathways completeness, each node in the graph is weighted. The default weight of each edge is 0.
Given a set of predicted KOs, if the KO is present in the pathway, the corresponding edge will have assigned weight = 1 (or 0 if edge is optional or another value if edge is connected by +). After that, this script searches the most relevant path by graph_weight from node 0 to node 1. max_graph_weight is then calculated under the assumption that all KOs are present.
completeness = graph_weight/max_graph_weight * 100%
