mioXpektron.analysis

Downstream statistical analysis for aligned peak matrices.

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.analysis_capabilities()

Report which extended analysis features are available.

Return type:

Dict[str, bool]

mioXpektron.analysis.bh_fdr(pvals)

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

Parameters:

pvals (ndarray)

Return type:

ndarray

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.categorize_model(model_name)

Assign a model name to a coarse family label.

Parameters:

model_name (str)

Return type:

str

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.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.compute_pca(X_scaled, y, savepath, *, random_state=0)

PCA embedding with variance ratio metadata.

Parameters:

• X_scaled (ndarray)

• y (Series)

• savepath (str)

• random_state (int)

Return type:

Tuple[ndarray, ndarray]

mioXpektron.analysis.compute_tsne(X_scaled, y, savepath, *, perplexity=30.0, learning_rate='auto', random_state=0)

t-SNE embedding via scikit-learn.

Parameters:

• X_scaled (ndarray)

• y (Series)

• savepath (str)

• perplexity (float)

• learning_rate (str | float)

• random_state (int)

Return type:

ndarray

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

UMAP embedding 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.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

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

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.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

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.get_class_names(*, data_dict=None, label_encoder=None, class_names=None, n_classes=None)

Resolve human-readable class names for encoded labels.

Parameters:

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

• label_encoder (Any | None)

• class_names (Sequence[str] | None)

• n_classes (int | None)

Return type:

List[str]

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

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]

mioXpektron.analysis.missing_packages()

Map unavailable features to pip install hints.

Return type:

Dict[str, str]

mioXpektron.analysis.model_needs_scaling(model)

Return True when a classifier benefits from feature scaling.

Parameters:

model (Any)

Return type:

bool

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

mioXpektron.analysis.plot_dataset_model_comparison(comparison_df, savepath, *, dataset_a='dataset_a', dataset_b='dataset_b', top_n=15)

Side-by-side accuracy bars for two datasets.

Parameters:

• comparison_df (DataFrame)

• savepath (str)

• dataset_a (str)

• dataset_b (str)

• top_n (int)

Return type:

None

mioXpektron.analysis.plot_family_comparison(results_df, savepath, *, dataset_name='dataset')

Plot best and mean accuracy per model family.

Parameters:

• results_df (DataFrame)

• savepath (str)

• dataset_name (str)

Return type:

None

mioXpektron.analysis.plot_feature_importance(model, feature_names, savepath, *, title, top_n=15)

Plot absolute LR coefficients or RF feature importances.

Parameters:

• model (Any)

• feature_names (List[str])

• savepath (str)

• title (str)

• top_n (int)

Return type:

None

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

mioXpektron.analysis.plot_model_comparison(results_df, savepath, *, dataset_name='dataset', top_n=10)

Bar chart of top model accuracies.

Parameters:

• results_df (DataFrame)

• savepath (str)

• dataset_name (str)

• top_n (int)

Return type:

None

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.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_roc_curves(results_df, data_dict, models, savepath, *, top_n=2)

Plot ROC curves for the top-performing probabilistic models.

Parameters:

• results_df (DataFrame)

• data_dict (Mapping[str, Any])

• models (Mapping[str, Any])

• savepath (str)

• top_n (int)

Return type:

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.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_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.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.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.resolve_embedding_methods(*, embedding_methods=None, run_umap=False, run_tsne=False)

Resolve the list of embedding methods to compute.

Parameters:

• embedding_methods (Sequence[str] | None)

• run_umap (bool)

• run_tsne (bool)

Return type:

List[str]

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]

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.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.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.save_consensus_heatmap(consensus, labels, savepath, *, label_col='Group')

Plot a consensus matrix ordered by group labels.

Parameters:

• consensus (ndarray)

• labels (Series)

• savepath (str)

• label_col (str)

Return type:

None

mioXpektron.analysis.save_factor_bars(H, feature_names, outdir, *, topm=15)

Save per-factor top m/z contributors as CSV and bar plots.

Parameters:

• H (ndarray)

• feature_names (List[str])

• outdir (str)

• topm (int)

Return type:

None

mioXpektron.analysis.select_best_tuned_model(tuning_df)

Return the name and estimator of the best tuned model.

Parameters:

tuning_df (DataFrame)

Return type:

Tuple[str | None, Any | None]

mioXpektron.analysis.summarize_model_families(results_df)

Aggregate benchmark metrics by model family.

Parameters:

results_df (DataFrame)

Return type:

DataFrame

mioXpektron.analysis.transform_features(X, *, method='log1p')

Apply a variance-stabilising transform before embedding or ML.

Parameters:

• X (ndarray)

• method (str)

Return type:

ndarray

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

Modules

cnmf	Consensus non-negative matrix factorisation for sample clustering.
compare	Cross-dataset and model-family comparison utilities.
embeddings	Nonlinear and linear sample embeddings for exploratory analysis.
metrics	Classification metrics and diagnostic plots.
ml	Machine-learning benchmarking for aligned m/z feature matrices.
optional	Optional analysis dependency detection.
plots	Visualization helpers for downstream statistical analysis.
prepare	Prepare feature matrices from pipeline or tabular outputs.
stats	Univariate statistics for aligned feature matrices.
tuning	Hyperparameter tuning for top benchmark models.
workflow	End-to-end analysis workflow for aligned peak matrices.