Quick Start#

This page walks through a complete simulate-and-analyze run using the bundled example in examples/simulate-and-analyze/. By the end you will have simulated a synthetic high-throughput TF-library screen, fitted the hierarchical Bayesian model, and produced a full set of diagnostic plots and statistics.

The example uses a small library (~600 genotypes across three sub-libraries) so the full pipeline finishes in roughly 20–60 minutes on a laptop CPU or a few minutes on a GPU.

Prerequisites#

Install tfscreen and verify the entry points are on your PATH:

git clone https://github.com/harmslab/tfscreen
cd tfscreen
pip install -e .
tfs-simulate --help   # should print usage

The example requires JAX and Numpyro, which are installed as dependencies. On Apple Silicon you may need to install the Metal-accelerated jax-metal package separately; on a Linux cluster with a GPU, install the appropriate jaxlib wheel for your CUDA version.

Getting the example#

Copy the example directory to a working location:

cp -r examples/simulate-and-analyze/ ~/tfscreen-example
cd ~/tfscreen-example

The directory contains:

  • simulate_config.yaml — simulation parameters (library genetics, growth conditions, binding data).

  • hill_params.csv — per-genotype Hill binding parameters that set the ground-truth θ values used during simulation.

  • run.sh — the pipeline script.

Running the pipeline#

bash run.sh simulate_config.yaml out/ 1

The three positional arguments are:

  1. The simulation config file.

  2. The output directory (created automatically).

  3. The random seed (1 reproduces the documented example outputs).

On a local machine the script uses JAX’s CPU parallelism (XLA_FLAGS="--xla_force_host_platform_device_count=8"). On a cluster, comment that line out and uncomment module load cuda/... instead.

The script runs nine steps in sequence, printing a >>> header before each one:

Step

Command

What it does

1

tfs-simulate

Builds the genotype library, draws per-genotype θ from the Hill model, converts θ to growth rates, and writes simulated sequencing data.

2

tfs-configure-model

Validates inputs, selects model components, writes tfs_configure_config.yaml.

3

tfs-prefit-calibration

Fast MAP fit to calibrate the growth-linking-function priors.

4

tfs-fit-model

Main SVI inference; writes tfs_fit_model_checkpoint.pkl.

5

tfs-sample-posterior

Draws posterior samples; writes tfs_posterior.h5 (~5 GB).

6

tfs-extract-params

Summarises the posterior into per-parameter CSV files.

7

tfs-predict-theta

Predicts θ at every (genotype, titrant concentration) in the training data.

8

tfs-predict-growth

Predicts ln(CFU) with posterior quantiles for all training observations.

9

tfs-summarize-fit

Computes fit statistics and writes diagnostic plots and CSVs to out/summary/.

Expected outputs#

After the run completes, out/ will contain:

File / directory

Contents

tfs_sim_library.csv

All genotypes in the simulated library.

tfs_sim_growth.csv

Simulated ln(CFU) data (same format as tfs-process-counts output).

tfs_sim_binding.csv

Simulated binding curve observations.

tfs_sim_parameters.csv

Ground-truth per-genotype parameters (θ, dk_geno, etc.).

tfs_configure_config.yaml

Model configuration read by all downstream steps.

tfs_fit_model_checkpoint.pkl

Fitted model checkpoint.

tfs_posterior.h5

Posterior samples (~5 GB; not committed to the repo).

tfs_params_*.csv

Posterior summaries (quantiles) for each parameter group.

tfs_pred_theta.csv

Predicted θ with posterior quantiles.

tfs_pred_growth.csv

Predicted ln(CFU) with posterior quantiles.

summary/

Diagnostic plots and statistics from tfs-summarize-fit.

Next steps#

  • Understand each analysis step — see Analysis for the full CLI reference covering every tfs-* command in the pipeline.

  • Interpret the diagnostic outputs — see tfs-summarize-fit for a guided walkthrough of every plot and statistic in out/summary/.

  • Simulate a parameter sweep — see Grid Setup and Summarisation for how to run a Cartesian grid of configurations.

  • Use real data — see Processing Raw Data for converting FASTQ reads into the growth.csv format that tfs-configure-model accepts.