CLI & API¶

The package installs a single console entry point, cli, defined in pyproject.toml as cli = "cli.main_cli:app". It is built with Typer, so --help works at every level.

cli --help
cli run --help
cli run train --help

Command groups¶

Group	Purpose
`data`	Download benchmark datasets
`preprocess`	Build the four input matrices, labels, distances
`generate`	Create and batch experiment configurations
`run`	Train, evaluate, compute MRRE
`analysis`	Inspect matchings and embeddings
`export`	Extract images and scripts from notebooks

data¶

cli data download [--type {pbmc|maxfuse|all}]

Option	Default	Meaning
`--type`	`all`	Which dataset collection to fetch

preprocess¶

cli preprocess data      DATASET-ID [--out PATH]
cli preprocess info      DATASET-ID [--out PATH]
cli preprocess labels    DATASET-ID [--out PATH]
cli preprocess distances DATASET-ID [--out PATH] [--verbose]

DATASET-ID is one of cite_seq_and_pbmc or tonsils.

Command	Produces
`data`	The active and shared matrices for both modalities
`info`	A report of the resulting shapes
`labels`	Ground-truth labels for supervised evaluation
`distances`	Precomputed distances used by the evaluation metrics

generate¶

cli generate count SRC              [--reps N]
cli generate new   CONFIG_FILE OUT  [--reps N]
cli generate batch SRC_DIR OUT_DIR  BATCH_SIZE

Command	Purpose
`count`	How many configurations a master file will expand to
`new`	Expand a master file into per-run configurations
`batch`	Split generated configurations into fixed-size batches for cluster submission

Always run count before new: a master file with several parameter lists expands combinatorially.

run¶

`run train`¶

cli run train RUN_TYPE CONFIGURATION-PATH \
    [--id STR] [--out PATH] [--preprocessed-dir PATH] [--evaluate] [--verbose]

Argument / option	Default	Meaning
`RUN_TYPE`	required	`original`, `regular`, `distributed`, or `federated`
`CONFIGURATION-PATH`	required	Path to the run configuration JSON
`--id`	`''`	Unique run identifier; combined with the scheduler ID for traceability
`--out`, `-o`	`DEFAULT_OUT_DIR_PATH`	Output directory
`--preprocessed-dir`, `-p`	`None`	Where preprocessed data lives
`--evaluate`, `--eval`, `-e`	`False`	Evaluate immediately after training
`--verbose`, `-v`	`False`	Verbose output

`run evaluation`¶

cli run evaluation DATASET_ID OUT-DATA-PATH \
    [--preprocessed-dir PATH] [--config-path PATH] [--algorithm-type TYPE] [--verbose]

Computes supervised and unsupervised metrics against a completed run's outputs.

`run mrre`¶

cli run mrre DATASET_ID OUT-DATA-PATH \
    [--preprocessed-dir PATH] [--config-path PATH] [--algorithm-type TYPE] [--verbose]

Mean Relative Rank Error is separated because it is the most memory-intensive metric: it needs full distance-rank matrices. See Metrics.

analysis¶

cli analysis matching   PATH [--summary]
cli analysis embeddings PATH [--summary]

Inspect the properties of matching and embedding files produced by a run. --summary / -s prints an aggregated view rather than per-file detail.

export¶

cli export images SRC [--output-dir PATH] [--prefix STR]
cli export script SRC [--output-file PATH]

Utilities for extracting figures and executable scripts from the analysis notebooks.

Python API¶

The CLI is a thin wrapper. The underlying package can be imported directly:

from fed_maxfuse.models.federated.model import MaxFuseFederatedModelNode
from fed_maxfuse.models.federated import server_functions
from fed_maxfuse.correlation_utils.cca.distributed.pls_w2a_node import PLSw2aNode

Module	Role
`models.federated.model`	Node-side algorithm — see Core Engine
`models.federated.server_functions`	Server-side matching — see Matching
`models.regular` / `models.distributed` / `models.original`	Alternative run types
`correlation_utils.cca`	Centralized and distributed CCA — see CCA Module
`evaluation.metrics`	Supervised and unsupervised metrics
`data`	Preprocessing, graphs, SVD

See the API section for module-level detail.

Typical workflows¶

Single experiment

cli data download --type maxfuse
cli preprocess data cite_seq_and_pbmc -o ./data/preprocessed
cli run train federated config.json --id run-001 -o ./out -p ./data/preprocessed -e
cli analysis matching ./out/federated_cite_seq_pbmc_params_run-001 -s

Parameter sweep on a cluster

cli generate count master.json --reps 25
cli generate new master.json ./configs --reps 25
cli generate batch ./configs ./batches 50
# submit each batch as a SLURM array job, then:
cli run evaluation cite_seq_and_pbmc ./out/... -at federated