adata_science_tools

Documentation

• Published docs: gitbenlewis.github.io/adata_science_tools
• Source docs: docs/README.md
• Plotting gallery: deterministic renderer examples
• Statistical inference: paired ratios and right-censored survival, with synthetic CSV examples.
• Start with simulation helpers and correlation dotplots.

Data-science tools that operate on AnnData objects.

Setup

Clone the repository

git clone https://github.com/gitbenlewis/adata_science_tools.git
cd adata_science_tools

Create the conda environment

conda env create -f config/env_not_base.yaml -n not_base
conda activate not_base

If not_base already exists, update it in place instead of deleting it:

conda env update -f config/env_not_base.yaml -n not_base

Standalone Python dependencies

Use config/env_not_base.yaml for the complete scientific environment. Core plotting uses AnnData, NumPy, pandas, SciPy, Matplotlib, and seaborn (AnnData also depends on h5py). Modeling dependencies are loaded when used:

• statsmodels and patsy: OLS and mixed-effects fitting; statsmodels also supplies multiple-testing correction for differential tests.
• patsy: expectation-model design matrices and prediction.
• PyYAML: reading or writing model-specification YAML files; in-memory modeling and plotting do not require it.
• scikit-learn: feature-standardization utilities.

For the complete modeling functionality:

python -m pip install statsmodels patsy PyYAML scikit-learn

Importing ADTL and using unrelated plots does not require these modeling packages.

matplotlib-venn is optional: package import, unrelated plots, and overlap-table calls with show_plot=False work without it. Rendering any Venn diagram requires:

python -m pip install matplotlib-venn

A missing Venn dependency produces installation guidance when rendering is requested. Flask is needed only for the web app; its dependencies are listed in config/requirements-web.txt. The container includes matplotlib-venn already.

Run the self-contained plotting gallery

bash scripts/000_generate_plotting_gallery.bash

This regenerates the deterministic PNG catalog in docs/assets/plotting_gallery and writes its run log under scripts/logs/.

Code-free analysis in your browser

The optional Flask app loads .h5ad files or three CSVs (adata.X.csv, adata.obs.csv, adata.var.csv) and provides forms for plotting, group comparisons, linear/mixed models, and downloadable results.

After activating the scientific environment, run from this repository:

python -m pip install -r config/requirements-web.txt
python scripts/run_web.py

Open http://127.0.0.1:5000 and select Open demo dataset or upload your own data. One command starts both the local app and its analysis worker. Optional username/password login is available:

python scripts/run_web.py --create-user scientist
python scripts/run_web.py --require-login

See the web app guide for supported analyses, input formats, privacy/retention behavior, configuration, and the future public deployment path for adata-science-tools.com. The local app is not publicly exposed.

Alternatively, install Docker with Compose and run:

docker compose up --build

Open http://127.0.0.1:5000. Docker supplies the Python dependencies and starts the same app and worker. The native Python commands above remain fully supported; Docker is optional. See the Docker instructions for ports, persistent storage, and optional login.

Simulated data example

The repo includes a small config-driven simulated-data workflow in example_simulated_data/. Its config.yaml uses repository-relative output paths, so the commands below are portable when run from the repository root. Outputs resolve under example_simulated_data/results/.

conda activate not_base
python example_simulated_data/scripts/simulate_1_var_covar_age.py
python example_simulated_data/scripts/plot_dotplot_simulate_1_var_covar_age.py

The default parameters simulate one feature, simulated_feature, from Age and case_control, add residual y variance so the points are not constrained to exact fit lines, and write both a baseline AnnData bundle and a dotplot.

The main example knobs are beta or beta_age, beta_case_control, case_control_prob, and residual_stdev.

See docs/_simulate_data.md for the simulation API and config details, and docs/_corr_dotplots.md for the plotting API.

Committed output snapshots: baseline.h5ad and baseline.png.

Paired datapoints examples

adtl.paired_datapoints() can add a third x-axis position for either the signed post-baseline difference or log2(post / baseline). The secondary y-axis is symmetric around zero in both modes.

Raw post-baseline difference

Opt-in legend metrics can summarize the finite post-filter values at baseline, post, and the raw pairwise post - baseline position.

Post-over-baseline log2 fold change

The log2FC summary uses valid pairwise log2(post / baseline) values rather than a fold change calculated from the endpoint means.

Example plots from example_PMID_33969320

These are committed output snapshots from a dataset-specific workflow, not a fresh-clone runnable example. The workflow expects external study data and a code_library checkout that are not included in this repository.

Column plot

API: adtl.datapoints_effect_panels_column() (source)

View plot file

Volcano plot

API: adtl.volcano_plot_generic()

View plot file