Metabolite Generation Logic Mapping

metabolite-generation-logic-mapping

Summary

Reverse-engineer and document the algorithmic workflow by which MAGMa generates candidate metabolites in silico, mapping chemical structure fragmentation rules, molecular property filters, and isomer enumeration into an executable flowchart or directed acyclic graph. This skill is essential for understanding, validating, and extending the chemo-informatics pipeline that underpins metabolite annotation.

When to use

When you have access to the MAGMa source code and need to understand or audit how in silico metabolite candidates are enumerated from parent structures. Specifically: you are extending the metabolite generation algorithm, troubleshooting why certain metabolites are or are not being generated, validating the chemical transformation rules applied, or documenting the pipeline for reproducibility in an integrative metabolomics workflow.

When NOT to use

• You only have access to the published MAGMa web application and no source code repository.
• Your goal is to run a single metabolite identification job, not to understand or modify the generation algorithm itself.
• The input structures are already pre-filtered or the candidate set has been manually curated outside the automated pipeline.

Inputs

• NLeSC/MAGMa GitHub repository (cloned source tree)
• Job subproject source files (Python modules implementing metabolite generation)
• Parent chemical structures (SMILES or MOL format)
• Generation rule definitions (transformation templates, bond cleavage patterns)

Outputs

• Directed acyclic graph (DAG) or flowchart JSON representation of metabolite generation pipeline
• Annotated algorithm documentation (function names, parameter definitions, transformation rules)
• Candidate metabolite enumeration trace (intermediate and final sets with property annotations)
• Validation report comparing mapped logic against execution logs or test cases

How to apply

Clone the NLeSC/MAGMa GitHub repository and locate the job subproject source files that implement metabolite generation. Perform static code analysis on those modules to identify function entry points, call chains, and data transformations—pay special attention to fragmentation logic, molecular property computation, and isomer enumeration routines. Extract and document parameter definitions, conditional branches, and transformation rules (e.g., bond cleavage patterns, functional group substitutions, ring transformations) that control candidate generation. Construct a directed acyclic graph or flowchart JSON representation annotated with function names, algorithm identifiers, and computational steps, showing inputs (parent structures, generation rules), intermediate computations (fragmentation sets, property filters), and outputs (ranked candidate metabolite sets). Validate by cross-referencing the mapped logic against actual job execution traces or unit tests.

Related tools

• MAGMa (Primary tool providing the in silico metabolite generation pipeline whose logic is being mapped and reverse-engineered.) — https://github.com/NLeSC/MAGMa
• job subproject (NLeSC/MAGMa) (Subproject containing the metabolite generation calculation modules that are analyzed via static code inspection.) — https://github.com/NLeSC/MAGMa

Evaluation signals

• The mapped DAG or flowchart correctly traces all function call chains from parent structure input to candidate metabolite output, with no missing branches or dead code.
• Parameter definitions extracted from source code (e.g., fragmentation thresholds, property filter cutoffs) match values documented in method sections or configuration files.
• Generated candidate metabolite sets produced by the mapped algorithm exactly match (or explain discrepancies with) the sets generated by running the actual job code on the same parent structures.
• All transformation rules (bond cleavages, functional group substitutions, isomer enumeration steps) are explicitly annotated in the flowchart with corresponding function or line references from the source.
• The documented pipeline is sufficient for an independent developer to implement a functionally equivalent metabolite generator from the flowchart alone.

Limitations

• No changelog documentation is available to track changes or deprecated algorithm versions over time.
• The mapping relies on static code analysis and may miss dynamic rule injection or runtime parameter configuration not visible in source inspection.
• Isomer enumeration and property filtering logic may be computationally expensive; the mapped flowchart does not quantify performance bottlenecks or scaling behavior.
• The skill does not validate chemical correctness of the transformation rules themselves—only their logical structure and implementation in code.

Evidence

• [other] Research question context: "What is the chemo-informatics workflow that MAGMa uses to generate candidate metabolites in silico?"
• [other] Workflow steps from task card: "Clone the NLeSC/MAGMa GitHub repository and locate the job subproject source files. Perform static code analysis on the metabolite generation modules to identify algorithm entry points, function call"
• [other] Pipeline artifacts and transformation mapping: "Map chemical structure fragmentation logic, molecular property computation, and in silico metabolite enumeration steps. Extract parameter definitions, conditional branches, and transformation rules"
• [other] Output representation specification: "Construct a directed acyclic graph or flowchart JSON representation showing inputs (parent structures, generation rules), intermediate computations (fragmentation, isomer enumeration, property"
• [readme] Project scope and tool definition: "MAGMa is a abbreviation for 'Ms Annotation based on in silico Generated Metabolites'."
• [readme] Integrative workflow context: "The project develops chemo-informatics based methods for metabolite identification and biochemical network reconstruction in an integrative metabolomics data analysis workflow."