DiagnosticReport

These are the main report functions for the library. The module includes both the standard single-dataset cross-sectional report and a multi-method comparison report, plus the longitudinal report.

CrossSectionalDiagnosticResult dataclass

Container for one method's diagnostics in a comparison report.

The comparison workflow fills this structure incrementally as each test succeeds or fails, then uses the collected fields to build the scorecard, summary advice, and per-method export files.

LongitudinalDiagnosticResult dataclass

Container for one method's longitudinal diagnostics in comparison mode.

covariate_to_numeric(covariates, covariate_types=None)

Convert categorical covariates to numeric codes for downstream analyses.

Parameters:

Name	Type	Description	Default
covariates	ndarray or DataFrame	Covariate matrix with categorical variables.	required

Returns:

Type	Description
ndarray | None	np.ndarray | None: Covariates converted to a numeric array, or None if
ndarray | None	no covariates were provided.

Notes

If covariates is a DataFrame, each categorical column is factorized independently. If covariates is a NumPy array, each categorical column is factorized independently. Numeric columns are left unchanged.

validate_comparison_datasets(datasets, batch, covariates=None, feature_names=None)

Validate and normalize the datasets used by the comparison report.

The function enforces a non-empty mapping of method name to 2D data array, checks that every method has the same shape, and validates that batch, covariate, and feature-name dimensions are compatible with the data.

summarise_method_performance(results, scoring_config=None)

Turn per-method diagnostics into a comparable scorecard.

The summary combines the extracted metrics into category-level scores for additive, multiplicative, linear-modelling, distributional, PCA, and biological-preservation behaviour. Optional scoring configuration can reweight the metrics or mark specific metrics as higher-is-better.

generate_comparison_advice(summary_df)

Generate a short natural-language recommendation from the scorecard.

The advice selects the best overall method, identifies the strongest method for each diagnostic theme, and adds a short note when the diagnostics favor different methods in different domains.

CrossSectionalReportMin(data, batch, covariates=None, covariate_names=None, save_data=True, save_data_name=None, save_dir=None, feature_names=None, report_name=None, SaveArtifacts=False, rep=None, show=False, timestamped_reports=True, covariate_types=None, ratio_type='rest', probability_distribution=False)

Create a minimal cross-sectional diagnostic report for quick checks.

This version keeps the report lightweight by running a reduced subset of diagnostics and visualizations. For a more comprehensive analysis, use CrossSectionalReport.

Parameters:

Name	Type	Description	Default
data	ndarray	Data matrix (samples x features).	required
batch	list or ndarray	Batch labels for each sample.	required
covariates	ndarray	Covariate matrix (samples x covariates).	None
covariate_names	list of str	Names of covariates.	None
save_data	bool	Whether to save input data and results.	True
save_data_name	str	Filename for saved data.	None
save_dir	str or PathLike	Directory to save report and data.	None
feature_names	list	Names of features.	None
report_name	str	Name of the report file.	None
SaveArtifacts	bool	Whether to save intermediate artifacts.	False
rep	StatsReporter	Existing report object to use.	None
show	bool	Whether to display plots interactively.	False
timestamped_reports	bool	Whether to append a timestamp to the report filename.	True
covariate_types	list	Types of covariates (e.g., 'categorical', 'numeric').	None
ratio_type	str	Variance-ratio comparison mode passed to Variance_Ratios.	'rest'

Returns:

Name	Type	Description
StatsReporter	StatsReporter	The report object containing the generated figures, text,
	StatsReporter	and saved artifact references.

CrossSectionalReport(data, batch, covariates=None, covariate_names=None, save_data=True, save_data_name=None, save_dir=None, feature_names=None, report_name=None, SaveArtifacts=False, rep=None, show=False, timestamped_reports=True, covariate_types=None, ratio_type='rest', UMAP_embedding=True, UMAP_tuning='auto', Random_state=None, probability_distribution=True, levene_center='median', FK_test=True, fontsize=10)

Create a full cross-sectional diagnostic report for batch effects.

The report combines summary text, statistical tests, and visualizations for mean, variance, covariance, clustering, and distributional differences across batches.

Parameters:

Name	Type	Description	Default
data	ndarray	Data matrix (samples x features).	required
batch	list or ndarray	Batch labels for each sample.	required
covariates	ndarray	Covariate matrix (samples x covariates).	None
covariate_names	list of str	Names of covariates.	None
save_data	bool	Whether to save input data and results.	True
save_data_name	str	Filename for saved data.	None
save_dir	str or PathLike	Directory to save report and data.	None
feature_names	list	Names of features.	None
report_name	str	Name of the report file.	None
SaveArtifacts	bool	Whether to save intermediate artifacts.	False
rep	StatsReporter	Existing report object to use.	None
show	bool	Whether to display plots interactively.	False
timestamped_reports	bool	Whether to append a timestamp to the report filename.	True
covariate_types	list	Types of covariates used by the report's numeric and categorical workflows.	None
ratio_type	str	Variance-ratio comparison mode passed to Variance_Ratios.	'rest'

Returns:

Name	Type	Description
StatsReporter	StatsReporter	The report object containing the generated narrative,
	StatsReporter	figures, and saved outputs.

Notes

covariate_types should align with covariate_names so the report can decide when to factorize categorical covariates and when to keep numeric covariates unchanged. If covariate_types is not provided, the function infers categorical versus numeric handling from the supplied data.

CrossSectionalComparisonReport(datasets, batch, covariates=None, covariate_names=None, save_data=True, save_data_name=None, feature_names=None, save_dir=None, report_name=None, include_raw=True, raw_name='Raw', scoring_config=None, rep=None, SaveArtifacts=False, show=False, timestamped_reports=True, covariate_types=None, ratio_type='rest', UMAP_embedding=True, UMAP_tuning='auto', plot_covariate_embeddings=True, allow_many_covariate_embeddings=False, probability_distribution=True, base_cmap='tab10', shared_y=False, fontsize=None, max_cols_in_plotting_grid=3)

Create a comparative diagnostic report for multiple harmonisation methods.

The comparison report runs the same diagnostic suite on each candidate dataset, then aggregates the resulting metrics into a method scorecard and a short recommendation summary. It is intended for side-by-side evaluation of raw and harmonised outputs that share the same sample order, batch labels, and optional covariates.

The report reuses the same per-method diagnostic pipeline as the single cross-sectional workflow through the following helpers:

• validate_comparison_datasets: checks that all methods are compatible.
• _run_single_method_diagnostics: runs the full diagnostic suite.
• summarise_method_performance: builds the comparison scorecard.
• generate_comparison_advice: turns the scorecard into a recommendation.
• _save_comparison_results: exports per-method CSV artifacts.

Parameters:

Name	Type	Description	Default
datasets	dict[str, ndarray]	Mapping of method name to data matrix (n_samples, n_features).	required
batch		Batch vector of length n_samples.	required
covariates		Optional covariate matrix (n_samples, n_covariates).	None
covariate_names		Optional covariate names.	None
save_data	bool	Whether to save per-method per-test CSV outputs.	True
save_data_name	str | None	Optional prefix to include in per-method saved CSV names.	None
feature_names		Optional feature names.	None
save_dir	str | PathLike | None	Directory for report and CSV outputs.	None
report_name	str | None	HTML report name.	None
scoring_config	dict | None	Optional scoring configuration.	None
rep		Optional existing StatsReporter instance.	None
SaveArtifacts	bool	Whether to save report artifacts.	False
show	bool	Whether to show plots interactively.	False
timestamped_reports	bool	Whether to timestamp the report filename.	True
covariate_types		Optional covariate type codes.	None
ratio_type	str	Variance-ratio mode.	'rest'
shared_y	bool	Whether feature-wise Cohen's d and variance-ratio plots use a shared y-axis limit across all methods. By default, each panel uses Matplotlib's automatic y-axis limits.	False
fontsize	int | float | None	Optional font size for plots. If None, the default Matplotlib font size is used.	None

Returns:

Name	Type	Description
StatsReporter	StatsReporter	Report object containing method-wise diagnostics,
	StatsReporter	side-by-side plots, scorecard, and advice.

LongitudinalReport(data, batch, subject_ids, timepoints=None, covariates=None, covariate_names=None, features=None, save_data=False, save_data_name=None, save_dir=None, report_name=None, SaveArtifacts=False, rep=None, show=False, timestamped_reports=True)

Generate a diagnostic report for longitudinal data, evaluating batch effects, subject-level stability, between-subject variability, and preservation of biological covariate associations.

The function is intended for repeated-measures data where measurements are available for the same subjects at multiple timepoints. It is designed for test-retest/travelling-subject style analyses where a systematic longitudinal trend is not the primary effect of interest.

Parameters:

Name	Type	Description	Default
data	ndarray	Two-dimensional numeric data matrix with shape (n_samples, n_features). Rows correspond to individual observations/measures and columns correspond to features/IDPs. The input is passed directly to the longitudinal diagnostic functions and is therefore expected to already be in matrix form.	required
batch	array - like	One-dimensional batch/site label vector with one entry per sample. The number of entries must correspond to data.shape[0].	required
subject_ids	array - like	One-dimensional subject identifier vector with one entry per sample. Repeated subject identifiers are expected for longitudinal data.	required
timepoints	array - like	One-dimensional timepoint/visit identifier vector with one entry per sample. Repeated measurements for a subject should be represented by multiple entries in this vector.	None
covariates	dict	Dictionary mapping covariate names to one-dimensional sequences, with one value per sample. Covariates are used as biological/fixed effects in the mixed-effects analyses. Note: In the current implementation, providing covariates in another format is not supported reliably because the function accesses covariates.keys(). When covariates are supplied, a dictionary is therefore expected.	None
covariate_names	list of str	Names of the covariates. In the current implementation these are inferred from covariates.keys() when covariates is provided.	None
features	sequence of str	Feature/IDP names corresponding to the columns of data. The current implementation uses features directly when constructing the raw-data DataFrame and when calling the diagnostic and plotting functions, and also calls len(features). A valid sequence of feature names matching the number of columns in data is therefore required.	None
save_data	bool, optional, default=False	Whether to save the input data and diagnostic results.	False
save_data_name	str	Filename/name prefix used for saved input data.	None
save_dir	str or PathLike	Directory in which the report and saved outputs are written. Defaults to the current working directory.	None
report_name	str	Name of the HTML report. The ".html" extension is added if it is not already present.	None
SaveArtifacts	bool, optional, default=False	Whether intermediate diagnostic artifacts/plots are saved.	False
rep	StatsReporter	Existing StatsReporter instance to use. If omitted, a new reporter is created internally.	None
show	bool, optional, default=False	Whether plots should be displayed interactively. The current report runner passes False to the plotting functions.	False
timestamped_reports	bool, optional, default=True	Whether to append a timestamp to the generated report filename.	True

Returns:

Name	Type	Description
StatsReporter		The report object containing the generated longitudinal diagnostic report and associated results.

Notes

This report evaluates repeated-measures stability and batch effects. It is not intended to test for an expected longitudinal biological trend over time.

validate_longitudinal_comparison_datasets(datasets, batch, subject_ids, timepoints, covariates=None, covariate_names=None, feature_names=None)

Validate and normalize inputs for longitudinal comparison reporting.

summarise_longitudinal_method_performance(results, scoring_config=None)

Create a subject-priority longitudinal method scorecard.

generate_longitudinal_comparison_advice(summary_df)

Generate a compact recommendation summary from longitudinal scorecard.

LongitudinalComparisonReport(datasets, batch, subject_ids, timepoints=None, covariates=None, covariate_names=None, features=None, save_data=True, save_data_name=None, save_dir=None, report_name=None, include_raw=True, raw_name='Raw', scoring_config=None, rep=None, SaveArtifacts=False, show=False, timestamped_reports=True, max_cols_in_plotting_grid=2)

Run and compare longitudinal diagnostics across multiple methods.