Project AKTAmercy - "CHROMER"

[] | [] | []

CHROMER is a Python automaton that post-processes chromatographic data from AKTA Pure HPLC systems running UNICORN (7.0+). It compiles .UFol and .Result files into annotated JPG chromatograms locally.

Features

• PyCORN-powered Parsing: Parses proprietary .UFol (UNICORNS) archives from UNICORN Evaluation software, using a PyCORN-inspired parser by Yasar L. Ahmed
• Chromatogram Recognition: Parses sample name, purification method, and run date from UNICORN exports. Optionally enriches titles with construct metadata via a local index (brain.json)
• Peak Detection: Detects chromatogram peaks and emits conservative, method-aware pool, verification, or signal-only annotations
• Local Output: Writes compiled chromatograms to timestamped folders under ./data/DONE/

Known Issues and Limitations

• Sample metadata: Sample_ID, method, and date are read from the UNICORN run log. Without brain.json, CHROMER runs in generic mode and titles chromatograms as {METHOD}_{SAMPLE}. With brain.json, indexed mode adds construct names to titles when the sample matches the index; unmatched samples still render with a generic title.
• Duplicate Logging: Even without multiprocessing, the log generates duplicate lines for each sample. chromer parse-log summarizes warnings when looking for deviants.
• Pooling Fractions: Pooling annotations are intentionally conservative. Protein A and lectin runs can receive candidate pool labels for a single clear peak; IMAC peaks require fraction verification; SEC and unrecognized methods are treated as signal detection rather than biological pool recommendations.
• Plotting: Revisions to the plotting are likely, to include more information and to make the plots more readable.

Please report any issues you encounter here, and feel free to contribute to the project by submitting a pull request.

Usage

Requires Python 3.11+.

git clone https://github.com/alxdolphin/AKTAmercy.git
cd AKTAmercy

python -m venv .venv
source .venv/bin/activate
pip install -e .

mkdir -p ./data/DROP-OFF
MPLBACKEND=Agg chromer process

CHROMER processes all .UFol and .Result files in ./data/DROP-OFF/ and writes compiled chromatograms to ./data/DONE/<timestamp>/, organized by purification method.

CLI commands

chromer process [--config config.json]   # batch process DROP-OFF exports
chromer inspect FILE [--config config.json]   # print parsed metadata as JSON
chromer parse-log LOG_FILE               # extract and summarize WARNING lines

Paths in config.json resolve relative to the config file location.

Construct Index (brain.json, optional)

CHROMER works without brain.json. When the file is present at ./brain.json (or the path in config.json), CHROMER runs in indexed mode and maps batch numbers to construct metadata. When absent, generic mode still parses exports and renders chromatograms.

Each index entry uses the batch number (uppercase) as the key:

{
    "BATCH01": {
        "ConstructID": "MyConstruct_pVax",
        "Ext/1000": "210",
        "MW/1000": "150.00"
    }
}

Field	Description
ConstructID	Construct name used in chromatogram titles
Ext/1000	Extinction coefficient (×1000)
MW/1000	Molecular weight (×1000)
TargetClass	Optional. When set to IgG or Fc, Protein A runs use stronger capture-pool wording. When set to glycoprotein, Lectin runs use glycoprotein-pool wording. Omit to keep cautious candidate-fraction labels.

Maintain brain.json manually or export from your lab's tracking system. CHROMER loads this file at startup when present and does not fetch remote updates. Samples not found in the index still produce chromatograms with generic titles.

Chromatogram Annotations

CHROMER separates UV280 signal detection from biological interpretation on each plot:

1. Signal — peak volume/absorbance markers and, for Protein A / Lectin runs, candidate elution fraction ranges derived from peak width.
2. Interpretation — a method-specific summary line in the top-right corner.

Default summary labels are cautious and do not assume target identity unless metadata supports it:

Method	Summary label (typical)
Protein A	Candidate Protein A elution fraction: A1-A2
Lectin	Candidate lectin-binding fraction: A1-A2
IMAC	IMAC UV280 peak detected: verify target-containing fractions
SEC	SEC UV280 peak detected: signal only; verify identity/oligomeric state separately
No peak	No clear UV280 elution peak

Multiple peaks on Protein A / Lectin runs are labeled MULTI — with all candidate fraction ranges listed. Protein A runs may upgrade to IgG/Fc capture wording when TargetClass is set or when the construct name matches high-confidence IgG/Fc patterns.

Configuration

config.json controls local paths and plotting parameters:

{
    "paths": {
        "unicorns": "./data/DROP-OFF/",
        "run_folder_base": "./data/DONE/",
        "brain": "./brain.json"
    },
    "plotting": { "params": { ... } }
}

Development

pip install -e .
MPLBACKEND=Agg python -m unittest discover -s tests -v

State of the Art - UNICORN vs CHROMER

v1.0.0-rc1

	UNICORN	CHROMAUTOGRAM
Lectin

The X values are slightly off in the CHROMAUTOGRAM, but the plot is otherwise identical to the UNICORN plot, with the peak falling within the same fraction range and reaching the same height.

	UNICORN	CHROMAUTOGRAM
SEC

Features like peak area shading, an overview plot, and more are planned in future releases.

Resources and Acknowledgements

Category	Libraries/APIs
Data Handling	PyCORN
Python Standard Library	datetime, io, json, logging, os, re, struct, tarfile, xml.etree.ElementTree, collections.OrderedDict, zipfile
Data Visualization	numpy, matplotlib, mpl_toolkits, seaborn, scipy.signal