CLI Reference#

MaldiAMRKit ships a command-line interface built on Typer. Three subcommands cover the most common batch-processing workflows: preprocessing spectra into feature matrices, generating quality reports, and building standardised dataset directories.

Command Reference#

maldiamrkit Usage: maldiamrkit [OPTIONS] COMMAND [ARGS]... MaldiAMRKit: MALDI-TOF preprocessing toolkit for AMR prediction. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ───────────────────────────────────────────────────────────────────╮ │preprocessBatch preprocess and bin spectra to a CSV feature matrix.       │ │quality   Compute quality metrics (SNR, TIC, peak count, etc.) for all    │ │spectra.                                                        │ │build     Build a standardised dataset directory from raw spectra and     │ │metadata.                                                       │ ╰──────────────────────────────────────────────────────────────────────────────╯
preprocess Usage: maldiamrkit preprocess [OPTIONS] Batch preprocess and bin spectra to a CSV feature matrix. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │*--input-dir-iPATH                 Directory containing  │ │.txt spectrum files.  │ │[required]            │ │*--output-oPATH                 Output CSV file for   │ │the feature matrix.   │ │[required]            │ │--bin-width-bINTEGER              Bin width in Daltons.│ │[default: 3]         │ │--method[uniform|proportionalBinning method.   │ │|adaptive|custom][default: uniform]│ │--pipeline-pPATH                 JSON/YAML pipeline    │ │config.               │ │--save-spectra-dirPATH                 Directory to save     │ │preprocessed spectra  │ │as TXT.               │ │--helpShow this message and │ │exit.                 │ ╰──────────────────────────────────────────────────────────────────────────────╯
quality Usage: maldiamrkit quality [OPTIONS] Compute quality metrics (SNR, TIC, peak count, etc.) for all spectra. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │*--input-dir-iPATHDirectory containing .txt spectrum files.│ │[required]                               │ │*--output-oPATHOutput CSV file for the quality report.│ │[required]                             │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯
build Usage: maldiamrkit build [OPTIONS] Build a standardised dataset directory from raw spectra and metadata. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │*--spectra-dir-sPATH            Directory       │ │containing raw  │ │spectrum files. │ │[required]      │ │*--metadata-mPATH            Metadata CSV    │ │file.           │ │[required]      │ │*--output-dir-oPATH            Output directory│ │for the         │ │standardised    │ │dataset.        │ │[required]      │ │--layout-l[flat|bruker]Input layout    │ │type.           │ │[default: flat] │ │--name-nTEXT            Dataset name    │ │(for metadata   │ │filename).      │ │Defaults to     │ │output dir name.│ │--id-columnTEXT            Column name for │ │spectrum IDs.   │ │Defaults to 'ID'│ │(flat) or       │ │'Identifier'    │ │(bruker).       │ │--year-columnTEXT            Metadata column │ │to extract year │ │from for        │ │year-based      │ │subfolders.     │ │--bin-width-bINTEGER         Bin width in    │ │Daltons.        │ │[default: 3]    │ │--pipeline-pPATH            JSON/YAML       │ │pipeline config.│ │--extra-handlersPATH            JSON/YAML config│ │file defining   │ │extra processing│ │handlers.       │ │--n-jobs-jINTEGER         Parallel jobs   │ │(-1 = all       │ │cores).         │ │[default: -1]   │ │--path-columnTEXT            Metadata column │ │with path to    │ │Bruker directory│ │(bruker layout  │ │only).          │ │[default: Path] │ │--target-positi…TEXT            Metadata column │ │for plate target│ │position (bruker│ │layout only).   │ │[default:       │ │target_position]│ │--duplicate-str…[first|last|dropStrategy for    │ │|keep_all|averaghandling        │ │e]duplicate       │ │spectrum        │ │identifiers     │ │(bruker layout  │ │only).          │ │[default: first]│ │--validate--no-validateSkip empty      │ │spectra and warn│ │on duplicates   │ │(bruker layout  │ │only).          │ │[default:       │ │validate]       │ │--helpShow this       │ │message and     │ │exit.           │ ╰──────────────────────────────────────────────────────────────────────────────╯

Usage Examples#

Preprocess#

Build a CSV feature matrix from a directory of .txt spectra:

maldiamrkit preprocess -i data/ -o features.csv -b 3

Save individual preprocessed spectra alongside the feature matrix:

maldiamrkit preprocess -i data/ -o features.csv --save-spectra-dir processed/

Use a custom preprocessing pipeline defined in YAML:

maldiamrkit preprocess -i data/ -o features.csv -p config.yaml

Quality#

Generate a per-spectrum quality report (SNR, TIC, peak count, etc.):

maldiamrkit quality -i data/ -o quality_report.csv

Build#

Build a DRIAMS-like dataset directory from flat .txt spectra (default layout):

maldiamrkit build -s data/ -m meta.csv -o output/

Build from a Bruker binary tree:

maldiamrkit build -s data/ -m meta.csv -o output/ -l bruker

Customise Bruker-specific column names:

maldiamrkit build -s data/ -m meta.csv -o output/ -l bruker \
  --path-column SpectrumPath --target-position-column Position

Organise output into year-based subfolders:

maldiamrkit build -s data/ -m meta.csv -o output/ --year-column acquisition_date

Add extra processing handlers from a YAML config:

maldiamrkit build -s data/ -m meta.csv -o output/ --extra-handlers handlers.yaml

Pipeline Configuration#

The --pipeline option accepts a JSON or YAML file describing the preprocessing steps. When omitted, the default pipeline is used (see default()).

steps:
  - name: clip
  - name: sqrt
  - name: savgol
    params: {window_length: 11, polyorder: 3}
  - name: snip
    params: {n_iters: 20}
  - name: trim
    params: {mz_min: 2000, mz_max: 20000}
  - name: tic

See the Quickstart Guide for a full walkthrough of building and customising preprocessing pipelines.