Analysis

The analysis module provides downstream statistical tools for aligned peak matrices produced by the pipeline or batch_processing().

Quick Example

from mioXpektron import AnalysisConfig, AnalysisWorkflow

config = AnalysisConfig(
    outdir="analysis_outputs",
    group_a="Treatment",
    group_b="Control",
    run_ml_benchmark=True,
    run_ml_tuning=True,
)
results = AnalysisWorkflow(intensity_df.reset_index(), config=config).run()

Matrix Preparation

mioXpektron.analysis.prepare_matrix(df, *, label_col='Group', sample_col='SampleName', meta_cols=None, feature_cols=None, coerce_numeric=True, fill_na=0.0)

Build a sample-by-feature matrix and group labels from pipeline output.

Accepts either:

• A long table with SampleName / Group columns and m/z feature columns (typical exported CSV), or

• An aligned matrix from align_peaks() where SampleName and optionally Group are index levels.

Parameters:

• df (DataFrame) – Input table or aligned feature matrix.

• label_col (str) – Column or index level containing group labels.

• sample_col (str) – Column or index level containing sample identifiers.

• meta_cols (Sequence[str] | None) – Additional metadata columns to exclude from features. Defaults to SampleName and Group only.

• feature_cols (Sequence[str] | None) – Explicit feature column names. When omitted, all non-metadata columns are used.

• coerce_numeric (bool) – If True, coerce feature columns to numeric (invalid values become NaN).

• fill_na (float) – Value used to fill missing feature values after coercion.

Returns:

• X – Feature matrix (samples x m/z), index aligned with meta.

• y – Group labels indexed like X.

• meta – Metadata frame with at least sample_col and label_col.

Return type:

Tuple[DataFrame, Series, DataFrame]

mioXpektron.analysis.infer_feature_columns(df, *, meta_cols=('SampleName', 'Group'))

Return non-metadata columns, attempting to detect m/z-like headers.

Parameters:

• df (DataFrame)

• meta_cols (Sequence[str])

Return type:

List[str]

Univariate Statistics

mioXpektron.analysis.bh_fdr(pvals)

Benjamini–Hochberg FDR correction for a 1D array of p-values.

Parameters:

pvals (ndarray)

Return type:

ndarray

mioXpektron.analysis.compute_univariate_tests(X, y, *, group_a=None, group_b=None, reference_group=None, eps=1e-12)

Welch t-test per feature with log2 fold-change (group_a / group_b).

When group_a and group_b are omitted, the two largest groups by sample count are compared. reference_group sets the denominator for log2 fold-change and defaults to group_b.

Parameters:

• X (DataFrame)

• y (Series)

• group_a (str | None)

• group_b (str | None)

• reference_group (str | None)

• eps (float)

Return type:

DataFrame

Visualization

mioXpektron.analysis.plot_volcano(res, savepath, *, group_a=None, group_b=None, q_thresh=0.05, fc_thresh=1.0)

Volcano plot of log2 fold-change versus -log10(p-value).

Parameters:

• res (DataFrame)

• savepath (str)

• group_a (str | None)

• group_b (str | None)

• q_thresh (float)

• fc_thresh (float)

Return type:

None

mioXpektron.analysis.plot_pca(X_scaled, y, savepath, *, random_state=0)

PCA scatter plot coloured by group labels.

Parameters:

• X_scaled (ndarray)

• y (Series)

• savepath (str)

• random_state (int)

Return type:

Tuple[ndarray, ndarray]

mioXpektron.analysis.plot_umap(X_scaled, y, savepath, *, n_neighbors=15, min_dist=0.1, random_state=0)

UMAP embedding plot when umap-learn is installed.

Parameters:

• X_scaled (ndarray)

• y (Series)

• savepath (str)

• n_neighbors (int)

• min_dist (float)

• random_state (int)

Return type:

ndarray | None

mioXpektron.analysis.plot_tsne(X_scaled, y, savepath, *, perplexity=30.0, random_state=0)

t-SNE scatter plot coloured by group labels.

Parameters:

• X_scaled (ndarray)

• y (Series)

• savepath (str)

• perplexity (float)

• random_state (int)

Return type:

ndarray

mioXpektron.analysis.run_embeddings(X_scaled, y, outdir, *, methods=None, run_umap=False, run_tsne=False, random_state=0, umap_n_neighbors=15, umap_min_dist=0.1, tsne_perplexity=30.0)

Compute and save requested embeddings; return coordinate arrays.

Parameters:

• X_scaled (ndarray)

• y (Series)

• outdir (str)

• methods (Sequence[str] | None)

• run_umap (bool)

• run_tsne (bool)

• random_state (int)

• umap_n_neighbors (int)

• umap_min_dist (float)

• tsne_perplexity (float)

Return type:

Dict[str, ndarray]

mioXpektron.analysis.plot_heatmap_top_features(X, y, res, savepath, *, top_n=25, label_col='Group')

Heatmap of top differential features (z-scored), samples ordered by group.

Parameters:

• X (DataFrame)

• y (Series)

• res (DataFrame)

• savepath (str)

• top_n (int)

• label_col (str)

Return type:

None

Optional Dependencies

Extended analysis features mirror the xpectrass stack. Install with:

pip install mioXpektron[analysis]

This adds umap-learn, xgboost, and shap. t-SNE and cNMF use scikit-learn and are always available.

mioXpektron.analysis.analysis_capabilities()

Report which extended analysis features are available.

Return type:

Dict[str, bool]

mioXpektron.analysis.missing_packages()

Map unavailable features to pip install hints.

Return type:

Dict[str, str]

Machine Learning

mioXpektron.analysis.prepare_ml_data(data, *, label_col='Group', sample_col='SampleName', test_size=0.2, random_state=42, transform='log1p', scale_features=True, handle_missing='zero')

Prepare an aligned matrix for supervised classification benchmarks.

Parameters:

• data (DataFrame | Tuple[DataFrame, Series]) – Either a table with metadata columns or a (X, y) tuple from prepare_matrix().

• label_col (str)

• sample_col (str)

• test_size (float)

• random_state (int)

• transform (str)

• scale_features (bool)

• handle_missing (str)

Return type:

Dict[str, Any]

mioXpektron.analysis.get_benchmark_models(*, random_state=42, include_boosting=True)

Return a compact set of classifiers suitable for m/z matrices.

Parameters:

• random_state (int)

• include_boosting (bool)

Return type:

Dict[str, Any]

mioXpektron.analysis.evaluate_model(name, model, data_dict, *, cv_folds=5, max_train_time_for_cv=30.0)

Fit one classifier and return hold-out and CV metrics.

Parameters:

• name (str)

• model (Any)

• data_dict (Mapping[str, Any])

• cv_folds (int)

• max_train_time_for_cv (float)

Return type:

Tuple[Dict[str, Any], Any]

mioXpektron.analysis.evaluate_all_models(models, data_dict, *, dataset_name='dataset')

Benchmark a mapping of classifiers and return a sorted results table.

Parameters:

• models (Mapping[str, Any])

• data_dict (Mapping[str, Any])

• dataset_name (str)

Return type:

DataFrame

Classification Metrics

mioXpektron.analysis.calculate_multiclass_metrics(y_true, y_pred, *, y_proba=None, class_names=None, data_dict=None)

Compute overall and per-class classification metrics.

Parameters:

• y_true (ndarray)

• y_pred (ndarray)

• y_proba (ndarray | None)

• class_names (Sequence[str] | None)

• data_dict (Mapping[str, Any] | None)

Return type:

Dict[str, Any]

mioXpektron.analysis.plot_confusion_matrix(y_true, y_pred, savepath, *, class_names=None, data_dict=None, normalize=False, title='Confusion matrix')

Plot and save a confusion matrix heatmap.

Parameters:

• y_true (ndarray)

• y_pred (ndarray)

• savepath (str)

• class_names (Sequence[str] | None)

• data_dict (Mapping[str, Any] | None)

• normalize (bool)

• title (str)

Return type:

ndarray

Hyperparameter Tuning

mioXpektron.analysis.tune_top_models(data_dict, results_df, *, top_n=3, cv_folds=5, random_state=42, verbose=0)

Grid-search hyperparameters for the top-performing models.

Parameters:

• data_dict (Mapping[str, Any])

• results_df (DataFrame)

• top_n (int)

• cv_folds (int)

• random_state (int)

• verbose (int)

Return type:

DataFrame

mioXpektron.analysis.get_tuning_grid(model_name)

Return a parameter grid for supported model names.

Parameters:

model_name (str)

Return type:

Dict[str, list] | None

Multi-Dataset Comparison

mioXpektron.analysis.compare_model_results(results_a, results_b, *, dataset_a='dataset_a', dataset_b='dataset_b')

Merge two benchmark tables and compute accuracy deltas.

Parameters:

• results_a (DataFrame)

• results_b (DataFrame)

• dataset_a (str)

• dataset_b (str)

Return type:

DataFrame

mioXpektron.analysis.run_multi_dataset_comparison(datasets, *, outdir='comparison_outputs', config=None, run_ml_benchmark=True)

Run analysis workflows on multiple datasets and compare ML benchmarks.

Parameters:

• datasets (Mapping[str, DataFrame | str])

• outdir (str)

• config (Any | None)

• run_ml_benchmark (bool)

Return type:

Dict[str, Any]

mioXpektron.analysis.summarize_model_families(results_df)

Aggregate benchmark metrics by model family.

Parameters:

results_df (DataFrame)

Return type:

DataFrame

Consensus NMF

mioXpektron.analysis.run_cnmf(X_pos, k_list, *, R=30, max_iter=1000, beta='frobenius', random_seeds=None, outdir=None)

Run consensus NMF across multiple rank values.

Parameters:

• X_pos (ndarray)

• k_list (List[int])

• R (int)

• max_iter (int)

• beta (str)

• random_seeds (List[int] | None)

• outdir (str | None)

Return type:

Dict[int, Dict[str, object]]

mioXpektron.analysis.choose_k_by_pac(results)

Select the rank with the lowest PAC score.

Parameters:

results (Dict[int, Dict[str, object]])

Return type:

int

mioXpektron.analysis.plot_pac_vs_k(results, savepath)

Plot PAC stability scores across candidate rank values.

Parameters:

• results (Dict[int, Dict[str, object]])

• savepath (str)

Return type:

None

mioXpektron.analysis.explain_with_shap(model, data_dict, savepath, *, max_samples=100, max_background=200)

SHAP beeswarm and bar plots when shap is installed.

Parameters:

• model (Any)

• data_dict (Mapping[str, Any])

• savepath (str)

• max_samples (int)

• max_background (int)

Return type:

ndarray | None

Workflow

class mioXpektron.analysis.AnalysisConfig(outdir='analysis_outputs', label_col='Group', sample_col='SampleName', group_a=None, group_b=None, reference_group=None, top_n_features=25, transform='log1p', random_state=0, embedding_methods=None, run_umap=False, run_tsne=False, umap_n_neighbors=15, umap_min_dist=0.1, tsne_perplexity=30.0, run_ml_benchmark=False, include_xgboost=True, ml_top_n_plot=10, run_ml_tuning=False, ml_tune_top_n=3, run_shap=False, run_cnmf=False, cnmf_k_list=None, cnmf_reps=30, cnmf_beta='frobenius', cnmf_top_features=15)

Bases: object

Configuration for AnalysisWorkflow.

Parameters:

• outdir (str)

• label_col (str)

• sample_col (str)

• group_a (str | None)

• group_b (str | None)

• reference_group (str | None)

• top_n_features (int)

• transform (str)

• random_state (int)

• embedding_methods (List[str] | None)

• run_umap (bool)

• run_tsne (bool)

• umap_n_neighbors (int)

• umap_min_dist (float)

• tsne_perplexity (float)

• run_ml_benchmark (bool)

• include_xgboost (bool)

• ml_top_n_plot (int)

• run_ml_tuning (bool)

• ml_tune_top_n (int)

• run_shap (bool)

• run_cnmf (bool)

• cnmf_k_list (List[int] | None)

• cnmf_reps (int)

• cnmf_beta (str)

• cnmf_top_features (int)

outdir: str = 'analysis_outputs'

label_col: str = 'Group'

sample_col: str = 'SampleName'

group_a: str | None = None

group_b: str | None = None

reference_group: str | None = None

top_n_features: int = 25

transform: str = 'log1p'

random_state: int = 0

embedding_methods: List[str] | None = None

run_umap: bool = False

run_tsne: bool = False

umap_n_neighbors: int = 15

umap_min_dist: float = 0.1

tsne_perplexity: float = 30.0

run_ml_benchmark: bool = False

include_xgboost: bool = True

ml_top_n_plot: int = 10

run_ml_tuning: bool = False

ml_tune_top_n: int = 3

run_shap: bool = False

run_cnmf: bool = False

cnmf_k_list: List[int] | None = None

cnmf_reps: int = 30

cnmf_beta: str = 'frobenius'

cnmf_top_features: int = 15

class mioXpektron.analysis.AnalysisWorkflow(data, config=None, *, models=None)

Bases: object

Orchestrate univariate stats, embeddings, ML, and optional cNMF.

Parameters:

• data (pd.DataFrame)

• config (Optional[AnalysisConfig])

• models (Optional[Mapping[str, Any]])

results: Dict[str, Any]

run()

Execute the configured analysis pipeline and write outputs.

Return type:

Dict[str, Any]

mioXpektron.analysis.run_analysis(data, *, config=None, **kwargs)

Convenience wrapper around AnalysisWorkflow.

Parameters:

• data (DataFrame | str)

• config (AnalysisConfig | None)

• kwargs (Any)

Return type:

Dict[str, Any]