The md_harmonize Tutorial

The md_harmonize is intended to harmonize compounds and reactions across public metabolic databases. It provides functionalities to:

  • Update a local copy of the KEGG metabolic databases.

  • Curate compound molfile representations.

  • Construct compound/reaction entities.

  • To detect aromatic substructures in a compound.

  • Parse KEGG RClass representations to generate atom mappings between compounds.

  • Harmonize compounds/reactions across databases.

In this document, each usage will be explained in details.

The md_harmonize API tutorial

Data preparation

The raw KEGG, MetaCyc, and HMDB is available on zenodo https://doi.org/10.5281/zenodo.7384576. Please download the data first and keep the hierarchy of directory. The following data is included in the directory:

  • KEGG compound molfiles, compound kcf’s, rclasses, and reactions.

  • MetaCyc compound molfiles, atom-mapping and reactions.

  • HMDB compound molfiles.

Using md_harmonize to download KEGG databases

Updates the KEGG metabolic databases, including compound kcf/molfile, reaction, and rclass.

md_harmonize download KEGG <working_directory>

Using md_harmonize to curate compound molfile representation

Curates molfile representations, eg: add H.

md_harmonize standardize <database_names> <working_directory>

Note: Multiple database names can be provided with comma separation, eg: KEGG,MetaCyc.

Using md_harmonize to construct compound/reaction entity

Constructs compound/reaction entities.

Compound construction:

md_harmonize initialize_compound <database_names> <working_directory> <aromatic_manager_file> [--parse_kegg_atom]

Options

–parse-kegg-atom: The parse-kegg-atom option is used for parsing KEGG atom mapping between compounds based on KEGG RClass definitions.

Reaction construction:

md_harmonize initialize_reaction <database_names> <working_directory>

Using md_harmonize to extract aromatic substructures from compounds

Extracts aromatic substructures from compounds using either Indigo or BASS to construct aromatic manager that can be used to detect aromatic substructures in the compound.

md_harmonize aromatize <database_names> <working_directory> <save_file> [--aromatic_manager=<aromatic_manager_file>]

Options

–aromatic_manager option to indicate a pre-constructed aromatic manager is provided and newly discovered aromatic substructures will be added to aromatic manager.

Using md_harmonize to harmonize compounds/reactions across databases

Harmonizes compounds/reactions across metabolic databases.

md_harmonize harmonize_compound <database_names> <working_directory>
md_harmonize harmonize_reaction <database_names> <working_directory>