README.md

metadata

title: bartab
emoji: 🍹
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.50.0
app_file: app.py
pinned: true
short_description: Fitness from pooled competition experiments.
tags:
  - biology
  - sequencing
  - pooled-screen
  - fitness
  - gradio

🍹 bartab

Estimate strain fitness from sequencing-based pooled competition experiments.

bartab analyses pooled barcode sequencing experiments in which multiple strains, mutants, guides, or constructs are grown together and quantified by NGS over time. It estimates the relative fitness of each barcode compared with a reference strain, typically WT.

---

What this app does

Upload three tables:

1. Count table
   Read or UMI counts for each barcode in each sequencing sample.

2. Sample sheet
   Metadata describing each sample: sample ID, culture/replicate ID, timepoint, optional concentration, optional growth measurement, and optional sampled volume.

3. Barcode sheet
   Barcode or strain identifiers, plus optional strain-level metadata.

bartab then estimates how each barcode changes relative to a reference barcode as the culture expands.

---

Option 1: Spike-in normalisation

Use this when your experiment includes a non-growing spike-in barcode, such as a heat-killed strain, plasmid-only control, or other fitness-zero control.

If the spike-in does not grow, then changes in the spike-in:WT count ratio report how much WT has expanded.

For a non-growing spike-in:

$$\log \left(\frac{c_{spike}(t)}{c_{wt}(t)}\frac{c_{wt}(0)}{c_{spike}(0)}\right)=-\log \frac{n_{wt}(t)}{n_{wt}(0)}\backslash log\; \backslash left(\; \backslash frac\{c\_\{spike\}(t)\}\{c\_\{wt\}(t)\}\; \backslash frac\{c\_\{wt\}(0)\}\{c\_\{spike\}(0)\}\; \backslash right)\; =\; -\; \backslash log\; \backslash frac\{n\_\{wt\}(t)\}\{n\_\{wt\}(0)\}$$

Substituting this into the barcode model gives:

$$\log \left(\frac{c_i(t)}{c_{wt}(t)}\frac{c_{wt}(0)}{c_i(0)}\right)=(1-\frac{w_i}{w_{wt}})\log \left(\frac{c_{spike}(t)}{c_{wt}(t)}\frac{c_{wt}(0)}{c_{spike}(0)}\right)\backslash log\; \backslash left(\; \backslash frac\{c\_i(t)\}\{c\_\{wt\}(t)\}\; \backslash frac\{c\_\{wt\}(0)\}\{c\_i(0)\}\; \backslash right)\; =\; \backslash left(\; 1\; -\; \backslash frac\{w\_i\}\{w\_\{wt\}\}\; \backslash right)\; \backslash log\; \backslash left(\; \backslash frac\{c\_\{spike\}(t)\}\{c\_\{wt\}(t)\}\; \backslash frac\{c\_\{wt\}(0)\}\{c\_\{spike\}(0)\}\; \backslash right)$$

So, when using spike-in normalisation, bartab estimates relative fitness from the relationship between:

• the barcode:WT log-ratio change
• the spike-in:WT log-ratio change

---

Option 2: Growth-based normalisation

Use this when you have measured culture growth directly, for example:

• OD600
• CFU/mL
• estimated generations
• another density-like growth measurement

In this mode, bartab uses the supplied growth column as the culture expansion axis instead of estimating expansion from a spike-in barcode.

---

Analysis modes

👟 Fitness in a single condition

This is the standard mode for pooled competition assays.

bartab fits a weighted least-squares model to estimate relative fitness for each barcode.

Main outputs:

Column	Meaning
fitness	relative fitness compared with the reference barcode
fitness_low	lower confidence interval bound
fitness_high	upper confidence interval bound
slope_p	p-value for deviation from neutral fitness

Interpretation:

Fitness	Interpretation
1	grows like the reference
< 1	growth disadvantage
> 1	growth advantage

---

📉 Dose response

Use this when the sample sheet contains a concentration column.

bartab first estimates barcode fitness across concentrations, then fits a two-parameter Hill model to estimate dose-response parameters.

Main outputs:

Column	Meaning
log_ic50	log10 concentration giving 50% inhibition
log_ic50_p	p-value associated with the IC50 estimate

Lower IC50 values indicate greater sensitivity to the inducer or drug.

---

Required input tables

The app lets you select the relevant columns after upload.

Supported file formats:

• .csv
• .tsv
• .txt
• .xlsx

---

1. Count table

One row per barcode per sample.

Required columns:

Meaning	Example
barcode / strain identifier	strain_id
sample identifier	sample_id
read or UMI count	count

Example:

strain_id	sample_id	count
wt	sample_0	12034
mutant_A	sample_0	8312
spike	sample_0	5021
wt	sample_1	18420
mutant_A	sample_1	6420
spike	sample_1	2100

---

2. Barcode sheet

One row per barcode.

Required columns:

Meaning	Example
barcode / strain identifier	strain_id

Optional metadata columns are carried through to the output.

Example:

strain_id	gene	annotation
wt	WT	reference
mutant_A	geneA	deletion mutant
spike	spike	non-growing spike-in

---

3. Sample sheet

One row per sequencing sample.

Required columns:

Meaning	Example
sample identifier	sample_id
culture / biological replicate	replicate
timepoint	timepoint

Optional columns:

Meaning	Example	Used for
concentration	dose	dose-response analysis
growth measurement	growth	growth-based normalisation
sampled volume	volume	adaptive-volume sampling

Example:

sample_id	replicate	timepoint	dose	growth	volume
sample_0	rep1	0	0	0.05	1.0
sample_1	rep1	1	0	0.20	1.0
sample_2	rep1	2	0	0.80	1.0

---

Example datasets

The Space includes synthetic example datasets for:

• single-concentration analysis using spike-in normalisation
• single-concentration analysis using growth-based normalisation
• dose-response analysis using spike-in normalisation
• dose-response analysis using growth-based normalisation

Start with these examples if you want to see the expected table structure.

---

Outputs

After analysis, the app returns:

1. Fitted parameter table
   A CSV file containing estimated fitness or dose-response parameters.

2. Annotated .h5ad object
   A full AnnData object containing input data, metadata, transformations, fitted values, and model outputs.

3. Diagnostic plots

Depending on the analysis mode, plots include:

• time vs count
• expansion vs count
• time vs ratio
• expansion vs ratio
• predicted vs observed
• volcano plot
• dose-response curves

---

Practical guidance

• Use consistent barcode and sample identifiers across all three tables.
• If using spike-in normalisation, include the spike-in barcode in both the count table and barcode sheet.
• If using growth-based normalisation, include a numeric growth column in the sample sheet.
• For dose-response analysis, concentration values must be numeric.
• Low-count barcodes may give unstable estimates.
• Always inspect diagnostic plots before interpreting individual hits.

---

The model

Interactive tutorial on analysis principles

In a pooled growth experiment, strains compete in the same culture. Their absolute growth curves may be complex because the pool eventually approaches carrying capacity. However, if we compare every strain to a reference strain, the shared density-dependent term cancels. The reference strain’s expansion can then be used as the effective growth clock.

For strain $i$ relative to WT:

$$\log n_i(t)=\frac{w_i}{w_{wt}}\log \frac{n_{wt}(t)}{n_{wt}(0)}+\log n_i(0)\backslash log\; n\_i(t)\; =\; \backslash frac\{w\_i\}\{w\_\{wt\}\}\; \backslash log\; \backslash frac\{n\_\{wt\}(t)\}\{n\_\{wt\}(0)\}\; +\; \backslash log\; n\_i(0)$$

where:

• $n_i(t)$ is the abundance of strain $i$ at time $t$
• $w_i$ is the intrinsic growth rate of strain $i$
• $w_i / w_{wt}$ is the relative fitness

So the problem becomes: estimate how barcode abundance changes relative to WT as WT expands.

---

From cells to sequencing counts

In practice, we do not observe cell numbers directly. We observe read counts:

$$c_i(t)c\_i(t)$$

These are affected by sampling, library preparation, and sequencing depth. To remove sample-specific sequencing depth effects, bartab works with ratios of barcode counts to the reference barcode.

The key quantity is:

$$\log \left(\frac{c_i(t)}{c_{wt}(t)}\frac{c_{wt}(0)}{c_i(0)}\right)\backslash log\; \backslash left(\; \backslash frac\{c\_i(t)\}\{c\_\{wt\}(t)\}\; \backslash frac\{c\_\{wt\}(0)\}\{c\_i(0)\}\; \backslash right)$$

This is the log-change in the abundance of barcode $i$ relative to WT, normalised to the starting timepoint.

Under the model:

$$\log \left(\frac{c_i(t)}{c_{wt}(t)}\frac{c_{wt}(0)}{c_i(0)}\right)=(\frac{w_i}{w_{wt}}-1)\log \frac{n_{wt}(t)}{n_{wt}(0)}\backslash log\; \backslash left(\; \backslash frac\{c\_i(t)\}\{c\_\{wt\}(t)\}\; \backslash frac\{c\_\{wt\}(0)\}\{c\_i(0)\}\; \backslash right)\; =\; \backslash left(\; \backslash frac\{w\_i\}\{w\_\{wt\}\}\; -\; 1\; \backslash right)\; \backslash log\; \backslash frac\{n\_\{wt\}(t)\}\{n\_\{wt\}(0)\}$$

Thus, each barcode should follow an approximately straight line. The slope gives the barcode’s fitness relative to WT.

---

Estimating culture expansion

The remaining problem is that the true WT expansion,

$$\frac{n_{wt}(t)}{n_{wt}(0)}\backslash frac\{n\_\{wt\}(t)\}\{n\_\{wt\}(0)\}$$

is usually not directly observed. bartab supports two ways to estimate it.

---

When this model is appropriate

bartab is designed for pooled competition experiments where:

• barcodes identify strains, mutants, guides, or constructs
• all barcodes are grown together in shared cultures
• barcode abundance is quantified by sequencing
• one barcode can be treated as a reference
• expansion can be estimated from a spike-in or measured growth

It is especially useful for:

• bacterial pooled competition assays
• barcoded mutant libraries
• CRISPRi or guide-based growth assays
• chemical-genetic pooled fitness experiments
• inducer or drug dose-response screens

---

Limitations

bartab estimates relative fitness, not absolute growth rate.

Results may be unreliable when:

• the reference barcode is depleted or poorly counted
• the spike-in is not truly non-growing
• barcode counts are extremely low
• barcode identities are mismatched between tables
• bottlenecks dominate the experiment
• strong barcode-specific sequencing biases are present
• timepoints or concentrations are too sparse for model fitting

For dose-response fitting, IC50 estimates are most meaningful when the tested concentration range brackets the transition from weak to strong inhibition.

---

Local use

To run the app locally:

pip install -r requirements.txt
gradio app.py

For package and source code, see https://github.com/scbirlab/bartab