API reference¶

Every symbol exported by structboost, grouped by the task it belongs to. This page is kept in sync with structboost.__all__ by tests/test_public_api.py.

For prose explaining when and why to use each of these, see the user guide.

The model¶

The Boosting Autoencoder itself and its configuration. BAE carries the whole fitting and inference surface: fit, transform, reconstruct, stability_selection, from_reference, save and load are all methods on it.

`structboost.BAE`(n_genes[, config])	Boosting Autoencoder for interpretable dimensionality reduction.
`structboost.BAEConfig`([latent_dim, ...])	Configuration for Boosting Autoencoder.
`structboost.TrainingReport`(iteration, ...)	Per-iteration training diagnostics collected by `BAE.fit`.

Gene selection and reliability¶

How reproducible is the gene list? Getting a gene list you can trust explains what stability selection measures and what it does not give you.

Note that stability_selection below is the standalone allboost-level function, which resamples cells and has its own defaults. The method structboost.BAE.stability_selection() is the one you want for a fitted model.

`structboost.stability_selection`(sourcemat, ...)	Run stability selection over subsamples of `allboost`.
`structboost.StabilitySelectionResult`(...[, ...])	Result of `structboost.stability_selection()`.

Reconstruction quality¶

A reconstruction MSE is uninterpretable on its own. linear_ceiling gives it a reference. See Reading reconstruction quality.

structboost.linear_ceiling(adata, ...[, layer])

Variance explainable by the best n_components-dimensional linear model.

Covariates and batch integration¶

The encoding machinery behind batch_key. Most users never call these directly, since fit does, but they are public so a design matrix can be inspected or reused. See Batches and unwanted covariates.

`structboost.encode_obs_covariates`(adata, ...)	Encode obs covariates as a standardized numeric matrix.
`structboost.transform_obs_covariates`(adata, ...)	Apply a stored obs covariate encoding to new data.
`structboost.ObsCovariateEncoding`(encoded, ...)	Stores encoding parameters for obs covariates.

Transfer and encoder weight files¶

An encoder weight matrix is the transferable product of a fit. These read and write it as a standalone file so it can be carried to another dataset with structboost.BAE.from_reference(). Parquet is the recommended format: spreadsheet round-trips silently rewrite gene symbols such as SEPT2 and MARCH1 as dates. See Transferring a model to a new dataset.

`structboost.read_encoder_weights`(path, *[, ...])	Read an encoder weight matrix written by `structboost.write_encoder_weights()`.
`structboost.write_encoder_weights`(weights, ...)	Write an encoder weight matrix with its gene identifiers.
`structboost.looks_like_ensembl`(identifiers, *)	Whether a set of gene identifiers is predominantly Ensembl accessions.

Interpretation¶

Turning a fitted encoder into something a biologist can read. See Interpreting latent dimensions.

`structboost.extract_gene_rankings`(adata_path)	Extract ranked gene lists (pos/neg) per latent dimension from .h5ad.
`structboost.write_annotations_to_h5ad`(...)	Write functional annotations into adata.uns of a .h5ad file.
`structboost.DimensionAnnotation`(dimension, ...)	Functional annotation for a single latent dimension.
`structboost.DimensionGeneRanking`(dimension, ...)	Ranked gene lists (positive and negative) for a single latent dimension.
`structboost.GeneRanking`(gene_names, weights)	Ranked gene list with weights.
`structboost.export_interactive_html`(adata, ...)	Export interactive HTML explorer for BAE results.

Plotting¶

Require the [plot] extra.

`structboost.plot_training_diagnostics`(report, *)	Plot a `TrainingReport` as a six-panel diagnostic figure.
`structboost.plot_boosting_coefficient_paths`(...)	Plot coefficient trajectories across boosting steps (per target).
`structboost.plot_top_boosting_coefficients`(...)	Plot per-target dot/lollipop charts of top boosting coefficients.

Boosting¶

Componentwise L2 boosting on its own: sparse supervised learning with no autoencoder involved, and the routine that fits the BAE encoder. See Sparse supervised boosting.

`structboost.allboost`(...)	Componentwise L2 boosting for multivariate regression.
`structboost.column_norms_sq`(sourcemat)	Squared column norms `\|\|x_j\|\|^2` of the boosting design matrix.
`structboost.AllboostHistory`(selection, beta_path)	Trace information returned by allboost(..., return_history=True).
`structboost.compute_covariance_cache`(...[, out])	Compute the predictor covariance matrix used by allboost.

Simulation¶

Synthetic data with known marker genes, for scoring a method against ground truth. See Simulating data with known truth.

`structboost.sim_scrnaseq_data`(*[, n, ...])	Simulate negative-binomial scRNA-seq counts with block/stage structure.
`structboost.sim_scrnaseq_anndata`(*[, n, ...])	Simulate scRNA-seq counts and package them as an AnnData object.
`structboost.SimulationResult`(counts, ...[, ...])	Simulated counts together with the ground truth used to generate them.