spacr.sim¶

Workflow inputs and outputs¶

Pooled-screen simulation sweep¶

Use the Python sweep API to explore stated screen-design assumptions. It expands combinations, runs simulations in a process pool and writes synthetic summary statistics; it returns None. Set a small explicit max_workers value and a bounded parameter grid before running. The output does not replace measurements or barcode counts for experimental Regression. Use the findings as planning evidence, with their assumptions recorded. Review the synthetic summaries when choosing planning assumptions; transfer those assumptions manually into Power / Design or Experiment Design. Neither tool imports this simulation database, and neither exports the simulation settings grid.

Use from Python: spacr.sim.run_multiple_simulations(). This API-only workflow has no Home tile or menu entry.

Inputs and outputs below include conditional alternatives. The guidance and handoff notes say which route applies.

Inputs

Pooled-screen simulation assumptions — Python settings dictionary: iterable sweep values for screen size, occupancy, classifier accuracy and sequencing assumptions, plus replicates, src, name, variable, plot and max_workers. generate_parameters expands their Cartesian product; begin with a small sweep and an explicit worker bound.

Outputs

Synthetic screen simulation summaries — src/<YYMMDD>/<name>/simulations.db; the sweep appends summary rows to simulations and optionally writes plots. These are synthetic performance estimates, not measured experimental hits. Relevant tables, depending on the route: simulations.

API reference.

Pooled-screen simulation, evaluation, and visualisation utilities.

Functions¶

`append_database`(src, table, table_name)	Append a DataFrame to `<src>/simulations.db` under `table_name`.
`calculate_permutation_importance`(df[, target, ...])	Fit a RandomForest and plot permutation-based feature importances for the sweep columns.
`cell_level_roc_auc`(cell_scores)	Compute cell-level ROC/PR metrics and confusion matrix at the F1-optimal threshold.
`classifier`(positive_mean, positive_variance, ...)	Simulate a noisy binary classifier by drawing per-cell scores from two Beta distributions.
`compute_precision_recall`(cell_scores)	Return precision/recall/F1/PR-AUC arrays for a DataFrame of `is_active`/`score` rows.
`compute_roc_auc`(cell_scores)	Return ROC-curve arrays and AUC for a DataFrame of `is_active`/`score` rows.
`create_database`(db_path)	Ensure a SQLite database file exists at `db_path`.
`dist_gen`(mean, sd, df)	Draw a length-`len(df)` Poisson sample with gamma-distributed rates.
`generate_floats`(start, stop, step)	Return floats from `start` through `stop` with `step` spacing.
`generate_gene_list`(number_of_genes, number_of_all_genes)	Return `number_of_genes` randomly-drawn gene indices without replacement.
`generate_gene_weights`(positive_mean, positive_variance, df)	Draw `len(df)` gene weights from a Beta distribution matched to the given moments.
`generate_integers`(start, stop, step)	Return `list(range(start, stop + 1, step))` (inclusive upper bound).
`generate_parameters`(settings)	Expand a sweep-settings dict into one settings dict per (Cartesian) simulation.
`generate_plate_map`(nr_plates)	Return a 384-well plate map DataFrame spanning `nr_plates` plates.
`generate_power_law_distribution`(num_elements, coeff)	Return a normalized power-law probability vector of length `num_elements`.
`generate_shap_summary_plot`(df[, target, clean, dst])	Fit a RandomForest and render a SHAP summary plot over the standard sweep features.
`generate_well_score`(cell_scores)	Aggregate cell-level scores into per-well summary rows.
`get_optimum_threshold`(cell_pr_dict)	Return the classification threshold that maximises F1 in a PR result dict.
`gini`(x)	Return the Gini coefficient of `x` via the ranked-sum formulation.
`gini_coefficient`(x)	Return the Gini coefficient of `x` via the pairwise absolute difference formula.
`gini_gene_well`(x)	Return the Gini coefficient of `x` using a memory-cheap upper-triangle sum.
`normalize_array`(arr)	Return `arr` min-max scaled into `[0, 1]`.
`plot_confusion_matrix`(data, ax, title)	Render a 2x2 confusion matrix as an annotated Seaborn heatmap.
`plot_correlation_matrix`(df[, annot, cmap, clean, dst])	Render a lower-triangular correlation heatmap of the standard sweep + metric columns.
`plot_feature_importance`(df[, target, exclude, clean, dst])	Train a RandomForestRegressor on sweep variables and plot the resulting importances.
`plot_histogram`(data, x_label, ax, color, title[, ...])	Draw a Seaborn density histogram on `ax` for the given column.
`plot_partial_dependences`(df[, target, clean, dst])	Fit a GradientBoostingRegressor and plot partial dependences for every sweep feature.
`plot_roc_pr`(data, ax, title, x_label, y_label)	Plot a ROC or PR curve with a diagonal random-classifier reference line.
`plot_simulations`(df, variable[, x_rotation, legend, ...])	Grid-plot PR-AUC vs `variable` for every unique combination of the other sweep dimensions.
`power_law_dist_gen`(df, avg, well_ineq_coeff)	Return `len(df)` per-well values sampled from an average-scaled power-law.
`read_simulations_table`(db_path)	Return the `simulations` table from `db_path` as a DataFrame.
`regression_roc_auc`(results_df, active_gene_list, ...)	Score regression hits against ground truth and compute ROC/PR metrics.
`remove_columns_with_single_value`(df)	Return `df` without columns whose values are constant across rows.
`remove_constant_columns`(df)	Return `df` limited to columns that contain more than one unique value.
`run_and_save`(i, settings, time_ls, total_sims)	Worker that runs one simulation, saves outputs, and appends its runtime.
`run_experiment`(plate_map, number_of_genes, ...)	Simulate one cell-level screening experiment and return per-cell + summary tables.
`run_multiple_simulations`(settings)	Fan out the sweep from `generate_parameters()` across a process pool.
`run_simulation`(settings)	Run one end-to-end pooled-screen simulation and return every intermediate table.
`save_data`(src, output, settings[, save_all, i, variable])	Persist one simulation's output tables to a SQLite database under `src`.
`save_plot`(fig, src, variable, i)	Save a Matplotlib figure to `<src>/<variable>/<i>_figure`.
`save_shap_plot`(fig, src, variable, i)	Save a SHAP figure to `<src>/<variable>/<i>_figure`.
`sequence_plates`(well_score, number_of_genes, ...[, ...])	Simulate sequencing of every well and return per-well gene fraction and metadata.
`update_scores_and_get_cm`(cell_scores, optimum)	Add a per-threshold predicted-label column and return the confusion matrix.
`validate_and_adjust_beta_params`(sim_params)	Clamp per-run Beta variances so the requested mean/variance is feasible.
`vis_dists`(dists, src, v, i)	Save side-by-side histograms of the six per-run distributions in `dists`.
`visualize_all`(output)	Render the full 13-panel diagnostic figure for one simulation output.

Module Contents¶

spacr.sim.append_database(src, table, table_name)[source]¶

Append a DataFrame to <src>/simulations.db under table_name.

Parameters:

src – Directory containing (or that should contain) simulations.db.
table – DataFrame written with if_exists='append'.
table_name – Target table name in the SQLite database.

Returns:

None.

spacr.sim.calculate_permutation_importance(df, target='prauc', exclude=None, n_repeats=10, clean=True, dst=None)[source]¶

Fit a RandomForest and plot permutation-based feature importances for the sweep columns.

Parameters:

df – DataFrame with sweep columns and target.
target – Column predicted by the regressor. Default 'prauc'.
exclude – Column name or list of columns to remove from the feature set.
n_repeats – Number of permutations per feature. Default 10.
clean – When True, drop constant columns before fitting.

Returns:

The generated Matplotlib figure.

spacr.sim.cell_level_roc_auc(cell_scores)[source]¶

Compute cell-level ROC/PR metrics and confusion matrix at the F1-optimal threshold.

Parameters:: cell_scores – DataFrame with columns is_active and score.
Returns:: Tuple (cell_roc_dict_df, cell_pr_dict_df, cell_scores, cell_cm).

spacr.sim.classifier(positive_mean, positive_variance, negative_mean, negative_variance, classifier_accuracy, df)[source]¶

Simulate a noisy binary classifier by drawing per-cell scores from two Beta distributions.

Used inside the spacr screen simulator to model an imperfect phenotype classifier: rows with is_active == 1 should score high and rows with is_active == 0 should score low, but with probability 1 - classifier_accuracy a row is drawn from the wrong Beta (simulating classifier error). The result is a score column on the input DataFrame ready to be fed to compute_roc_auc() / compute_precision_recall().

Parameters:

positive_mean – Mean of the Beta distribution for active cells; must be in (0, 1).
positive_variance – Variance of the Beta for active cells; must satisfy 0 < var < mean * (1 - mean).
negative_mean – Mean of the Beta for inactive cells.
negative_variance – Variance of the Beta for inactive cells.
classifier_accuracy – Probability in [0, 1] that a row is drawn from the Beta matching its true is_active label.
df – DataFrame containing an is_active column (0 / 1).

Returns:

The input DataFrame with a new score column in [0, 1].

Raises:

ValueError – if either mean is outside (0, 1) or either variance is outside (0, mean * (1 - mean)).

Example

from spacr.sim import classifier
df = classifier(
    positive_mean=0.8, positive_variance=0.02,
    negative_mean=0.2, negative_variance=0.02,
    classifier_accuracy=0.9, df=cells,
)

Nested helpers¶

_commit_simulation_packet.dispatch(operation)¶

Write one captured simulation frame through the normal table writer.

spacr/sim.py:1034

_simulation_unit_bytes._largest(key, default)¶

The largest value swept for key.

spacr/sim.py:1073

classifier.calc_alpha_beta(mean, variance)¶

Return (alpha, beta) for a Beta with the given mean and variance.

spacr/sim.py:315

classifier.get_score(is_active)¶

Return a Beta sample from the correct or incorrect class distribution.

spacr/sim.py:327