Initial commit

.github/workflows/hf-sync.yml

@@ -0,0 +1,20 @@
+name: Sync to Hugging Face hub
+on:
+  push:
+    branches: [main]
+
+  # to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  sync-to-hub:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          lfs: true
+      - name: Push to hub
+        env:
+            HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: git push https://HF_USERNAME:[email protected]/spaces/scbirlab/tutorial-seq-fitness main

.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+.venv/
+.gradio/

README.md

@@ -0,0 +1,180 @@
+---
+title: Tutorial - Fitness estimation from pooled growth and NGS
+emoji: 🧮
+colorFrom: green
+colorTo: blue
+sdk: gradio
+sdk_version: 5.22.0
+app_file: app.py
+pinned: false
+license: mit
+short_description: How do strains grow when competing with each other? And how can we infer their fitness from next-generation sequencing data?
+tags:
+    - biology
+    - sequencing
+---
+
+# Tutorial – Fitness estimation from pooled growth
+
+[![Open in Spaces](https://huggingface.co/datasets/huggingface/badges/resolve/main/open-in-hf-spaces-md-dark.svg)](https://huggingface.co/spaces/scbirlab/tutorial-seq-fitness)
+
+This is the repository for the interactive tutorial, acccessed [here](https://huggingface.co/spaces/scbirlab/tutorial-seq-fitness). Non-interactive text from the tutorial is below.
+
+## Multiplex growth curves
+
+How do strains grow when competing with each other?
+
+That's given by the [Lotka–Volterra competition model](https://en.wikipedia.org/wiki/Competitive_Lotka%E2%80%93Volterra_equations). 
+For two strains:
+
+$$
+\frac{dn_{wt}}{dt} = w_{wt} n_{wt} \left( 1 - \frac{n_{wt} + n_{1}}{K} \right)
+$$
+
+$$
+\frac{dn_1}{dt} = w_{1} n_1 \left( 1 - \frac{n_{wt} + n_{1}}{K} \right)
+$$
+
+
+- $n_i(t)$: abundance of species (or strain) $i$ at time $t$.
+- $w_i$: intrinsic (exponential) growth rate of species $i$.
+- $K$: carrying capacity.
+
+We can generalize to many strains. For each one:
+
+$$
+\frac{dn_i}{dt} = w_{i} n_i \left( 1 - \frac{\Sigma_j n_j}{K} \right)
+$$
+
+It's not possible to algebraically integrate these equations, since they are
+circularly dependent on each other. But we can numerically integrate, to simulate 
+multiplexed growth curves.
+
+### Removing time dependence
+
+It can be difficult to get absolute fitness out of these curves, because 
+when the pool approaches the carrying capacity, all the strains growth rates 
+mutually affect each other. 
+
+However, if we're only interested in the relative fitness of multiplexed strains relative
+to a reference (e.g. wild-type) strain, then we can make this simplification:
+
+$$
+\frac{dn_{i}}{dt} / \frac{dn_{wt}}{dt} = \frac{dn_{i}}{dn_{wt}} = \frac{w_{i} n_i}{w_{wt} n_{wt}}
+$$
+
+The interdependency term cancels out, and time is removed, with the reference strain's
+growth acting as the clock. Unlike the time-dependent Lotka-Volterra equations, this
+has a closed-form integral:
+
+$$
+\log n_i(t) = \frac{w_i}{w_{wt}} \log \frac{n_{wt}(t)}{n_{wt}(0)} + \log{n_i(0)}
+$$
+
+So now the log of the number of cells of a mutant at any moment ($n_1(t)$) is dependent only
+on its inoculum ($n_1(0)$), how much the reference strain has grown (i.e. fold-expansion, 
+$\frac{n_{wt}(t)}{n_{wt}(0)}$), and the ratio of fitness between the mutant and the 
+reference ($\frac{n_{wt}(t)}{n_{wt}(0)}$).
+
+## Read counts from next-generation sequencing
+
+But we don't actually measure the number of cells directly. Instead, we're measuring the
+number of reads (or UMIs) which represent a random sampling of the population followed by
+molecular biology handling and uneven sequencing per lane which decouples the relative
+abundances for each timepoint. 
+
+Below, you can simulate read counts for technical replicates of the growth curves above.
+The simulation:
+
+1. Randomly samples a defined fraction of the cell population (without replacement, i.e.
+the [Hypergeometric distribution](https://en.wikipedia.org/wiki/Hypergeometric_distribution)).
+Smaller samples from smaller populations are noisier.
+2. Calculates the resulting proportional representation of every strain in every sample.
+3. Multiplies that proportion by read depth.
+4. Randomly samples sequencing read counts resulting from variations in library construction
+and other stochasticity, according to the 
+[Negative Binomial distribution](https://en.wikipedia.org/wiki/Negative_binomial_distribution), 
+an established noise model for sequencing counts.
+
+### Accounting for sequencing subsampling per sample
+
+Each sequencing sample $s$ could be over- or under-sampling the population relative to the first
+timepoint by some factor $\phi_s$.
+
+$$\log \frac{c_i(t)}{c_i(0)} = \log \phi_s\frac{n_i(t)}{n_i(0)} = \log \phi_s + \frac{w_i}{w_{wt}} \log \frac{n_{wt}(t)}{n_{wt}(0)}$$
+
+Variables:
+- $c_i(t)$: Read (or UMI) count of strain $i$ at time $t$
+- $\phi_s$: The ratio of sampling depth at time $t$ to that at time $0$ for sample $s$
+
+The factor $\phi_s$ is the ratio of _the ratio of read counts between samples_ 
+and _the ratio of cell counts between samples_ for any strain (assuming each strain
+is sampled without bias):
+
+$$\log \phi_s = \log \frac{c_i(t)}{c_i(0)} - \log \frac{n_i(0)}{n_i(0)}$$
+
+We can get rid of the nuisance parameter $\phi_s$ (which is difficult to measure becuase
+we don't know the true number of cells for each strain and sample) using the following trick.
+
+We have the equation for read counts for mutant $i$ (same as above):
+
+$$
+\log \frac{c_i(t)}{c_i(0)} = \log \phi_s + \frac{w_i}{w_{wt}} \log \frac{n_{wt}(t)}{n_{wt}(0)}
+$$
+
+And for the reference strain (relative fitness is 1):
+
+$$
+\log \frac{c_{wt}(t)}{c_{wt}(0)} = \log \phi_s + \log \frac{n_{wt}(t)}{n_{wt}(0)}
+$$
+
+We can make $\phi_s$ disappear by taking the difference:
+
+$$
+\log \frac{c_i(t)}{c_i(0)} - \log \frac{c_{wt}(t)}{c_{wt}(0)} = \frac{w_i}{w_{wt}} \log \frac{n_{wt}(t)}{n_{wt}(0)} - \log \frac{n_{wt}(t)}{n_{wt}(0)}
+$$
+
+This is equivalent to:
+
+$$
+\log \left( \frac{c_i(t)}{c_{wt}(t)}\frac{c_{wt}(0)}{c_i(0)} \right) = \left(\frac{w_i}{w_{wt}} - 1 \right) \log \frac{n_{wt}(t)}{n_{wt}(0)}
+$$
+
+So the ratio of _the count ratio of a strain to the reference strain at time t_ to 
+_the count ratio of a strain to the reference strain at time 0_ is
+dependent only on the relative fitness and the true fold-expansion of the reference strain.
+
+Plotting the ratio of _the count ratio of a strain to the reference strain at time t_ to 
+_the count ratio of a strain to the reference strain at time 0_ 
+should give a straight line (on a log-log) plot, with intercept 0 and gradient equal to the relative fitness minus 1.
+
+### Using spike-in counts
+
+But we don't actually know the true fold-expansion of the reference strain, since 
+it's not directly observed. However, a non-growing fitness-zero control can help,
+such as a heat-killed strain or a spike-in plasmid.
+
+We start with the equation before,
+
+$$
+\log \left( \frac{c_i(t)}{c_{wt}(t)}\frac{c_{wt}(0)}{c_i(0)} \right) = \left(\frac{w_i}{w_{wt}} - 1 \right) \log \frac{n_{wt}(t)}{n_{wt}(0)}
+$$
+
+But for the fitness-zero control, $w_{spike} = 0$, so:
+
+$$
+\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)}
+$$
+
+This means that, although we don't know how the reference strain grows directly, its
+growth is given from the ratio of the spike counts to the reference counts, normalized
+to the same ratio at time 0.
+
+This leaves us with the overall equation:
+
+$$
+\log \left( \frac{c_i(t)}{c_{wt}(t)}\frac{c_{wt}(0)}{c_i(0)} \right) = \left(1 - \frac{w_i}{w_{wt}} \right) \log \left( \frac{c_{spike}(t)}{c_{wt}(t)}\frac{c_{wt}(0)}{c_{spike}(0)} \right)
+$$
+
+If we plot the left hand side against the right, we should get a straight line for 
+each strain with intercept zero and gradient $1 - \frac{w_i}{w_{wt}}$.

app.py

@@ -0,0 +1,333 @@
+
+from functools import partial
+import os
+
+from carabiner.mpl import add_legend, grid, colorblind_palette
+import gradio as gr
+import numpy as np
+import matplotlib as mpl
+import matplotlib.pyplot as plt
+from scipy.integrate import solve_ivp
+from scipy.stats import multivariate_hypergeom, nbinom
+
+# Set the default color cycle
+mpl.rcParams['axes.prop_cycle'] = mpl.cycler(
+    color=("lightgrey", "dimgrey") + colorblind_palette()[1:],
+) 
+
+SEED: int = 42
+MAX_TIME: float = 5.
+SOURCES_DIR: str = "sources"
+
+
+def inject_markdown(filename):
+    with open(os.path.join(SOURCES_DIR, filename), 'r') as f:
+        md = f.read()
+    return gr.Markdown(
+        md,
+        latex_delimiters=[
+            {"left": "$$", "right": "$$", "display": True},
+            {"left": "$", "right": "$", "display": False},
+        ],
+    )
+
+
+def lotka_volterra(t, y, w, K):
+    remaining_capacity = np.sum(y) / K
+    dy = w * y.flatten() * (1. - remaining_capacity)
+    return dy
+
+
+def grow(t, n0, w, K=None):
+    """Deterministic population size at time t.
+
+    n0 : initial cells
+    w  : growth rate
+    t  : time (arbitrary units)
+    K  : carrying capacity  (None → pure exponential)
+
+    """
+    if K is None:
+        return n0 * np.exp(w[None] * t[:,None])
+    # logistic with shared K
+    else:
+        ode_solution = solve_ivp(
+            lotka_volterra,
+            t_span=sorted(set([0, max(t)])),
+            t_eval=sorted(t),
+            y0=n0,
+            vectorized=True,
+            args=(w, K),
+        )
+        # print(ode_solution)
+        return ode_solution.y
+
+
+def plotter_t(x, growths, scatter=False, **kwargs):
+    fig, axes = grid(aspect_ratio=1.5)
+    plotter_f = partial(axes.scatter, s=5.) if scatter else axes.plot
+    for i, y in enumerate(growths):
+        plotter_f(
+            x.flatten(), y.flatten(), 
+            label=f"Mutant {i-1}" if i > 1 else "_none",
+        )
+    axes.set(
+        xlabel="Time",
+        yscale="log",
+        **kwargs,
+    )
+    add_legend(axes)
+    return fig
+
+
+def plotter_ref(x, growths, scatter=False, fitlines=None, text=None, **kwargs):
+    fig, axes = grid(aspect_ratio=1.5 if text is None else 1.7)
+    plotter_f = partial(axes.scatter, s=5.) if scatter else axes.plot
+    for i, y in enumerate(growths):
+        plotter_f(
+            x.flatten(), y.flatten(), 
+            label=f"Mutant {i-1}" if i > 1 else "_none",
+        )
+    if fitlines is not None:
+        fit_x, fit_y = fitlines
+        for i, b in enumerate(fit_y.flatten()):
+            y = np.exp(np.log(fit_x) @ b[None])
+            print(fit_x.shape, y.shape, b)
+            axes.plot(
+                fit_x.flatten(), y.flatten(),
+                label="_none",
+            )
+    if text is not None:
+        axes.text(
+            1.05, .1, 
+            text, 
+            fontsize=10,
+            transform=axes.transAxes,
+        )
+    axes.set(
+        xscale="log",
+        yscale="log",
+        **kwargs,
+    )
+    add_legend(axes)
+    return fig
+
+
+def calculate_growth_curves(inoculum, inoculum_var, carrying_capacity, fitness, n_timepoints=100):
+    inoculum_var = inoculum + inoculum_var * np.square(inoculum)
+    p = inoculum / inoculum_var
+    n = (inoculum ** 2.) / (inoculum_var - inoculum)
+    w = [1., 0.] + list(fitness)
+    n0 = nbinom.rvs(n, p, size=len(w), random_state=SEED)
+    t = np.linspace(0., MAX_TIME, num=int(n_timepoints))
+    growths = grow(t, n0, w, inoculum * carrying_capacity)
+    ref_expansion = growths[0] / n0[0]
+    return t, ref_expansion, growths
+
+    
+def growth_plotter(inoculum, inoculum_var, carrying_capacity, *fitness):
+    t, ref_expansion, growths = calculate_growth_curves(inoculum, inoculum_var, carrying_capacity, fitness, n_timepoints=100)
+    return [
+        plotter_t(
+            t, 
+            growths, 
+            ylabel="Number of cells per strain",
+        ),
+        plotter_ref(
+            ref_expansion, 
+            growths, 
+            xlabel="Fold-expansion of wild-type",
+            ylabel="Number of cells per strain",
+        ),
+    ]
+
+
+def reads_sampler(population, sample_frac, seq_depth, reps, variance):
+    samples = []
+    for i, timepoint_pop in enumerate(np.split(population.astype(int), population.shape[-1], axis=-1)):
+        sample_size = np.floor(timepoint_pop.sum() * sample_frac).astype(int)
+        samples.append(
+            multivariate_hypergeom.rvs(
+                m=timepoint_pop.flatten(), 
+                n=sample_size, 
+                size=reps, 
+                random_state=SEED + i,
+            ).T
+        )
+    samples = np.stack(samples, axis=-2)
+    read_means = np.floor(seq_depth * samples.shape[0] * samples / samples.sum(axis=0, keepdims=True))
+    variance = read_means + variance * np.square(read_means)
+    p = read_means / variance
+    n = (read_means ** 2.) / (variance - read_means)
+    return np.stack([
+        nbinom.rvs(n[...,i], p[...,i], random_state=SEED + i) 
+        for i in range(reps)
+    ], axis=-1)
+
+
+def fitness_fitter(read_counts, ref_expansion):
+    
+    read_count_expansion = read_counts / np.mean(read_counts[:,:1], axis=-1, keepdims=True)
+    read_count_expansion_ref = read_count_expansion[:1]
+    log_read_count_correction = np.log(read_count_expansion) - np.log(read_count_expansion_ref)
+
+    ref_expansion = np.tile(
+        np.log(ref_expansion)[:,None], 
+        (1, log_read_count_correction.shape[-1]),
+    ).reshape((-1, 1))
+    betas = []
+    for i, log_strain_counts_corrected in enumerate(log_read_count_correction):
+        ols_fit = np.linalg.lstsq(a=ref_expansion, b=log_strain_counts_corrected.flatten())
+        betas.append(ols_fit[0])
+
+    return log_read_count_correction, np.asarray(betas)
+
+
+def fitness_fitter_spike(log_read_count_corrected):
+    log_spike_count_corrected = log_read_count_corrected[1,...].flatten()[...,None]
+    betas = []
+    for i, log_strain_counts_corrected in enumerate(log_read_count_corrected):
+        ols_fit = np.linalg.lstsq(
+            a=log_spike_count_corrected, 
+            b=log_strain_counts_corrected.flatten(),
+        )
+        betas.append(ols_fit[0])
+
+    return log_spike_count_corrected, np.asarray(betas)
+
+
+def reads_plotter(
+    sample_frac, seq_reps, seq_depth, read_var,
+    inoculum, inoculum_var, carrying_capacity, *fitness
+):
+    t, ref_expansion, growths = calculate_growth_curves(inoculum, inoculum_var, carrying_capacity, fitness, n_timepoints=10)
+    read_counts = reads_sampler(growths, sample_frac, seq_depth, seq_reps, read_var)
+    log_read_count_correction, betas = fitness_fitter(read_counts, ref_expansion)
+    plot_text = "\n".join(
+        f"Mutant {i-1}: $w_{i-1}/w_{'{wt}'}={1. + b:.2f}$"
+        for i, b in enumerate(betas.flatten()) if i > 1
+    )
+    log_spike_count_corrected, spike_betas = fitness_fitter_spike(log_read_count_correction)
+    plot_text_spike = "\n".join(
+        f"Mutant {i-1}: $w_{i-1}/w_{'{wt}'}={1. - b:.2f}$"
+        for i, b in enumerate(spike_betas.flatten()) if i > 1
+    )
+    read_count_correction = np.exp(log_read_count_correction)
+    return growth_plotter(inoculum, inoculum_var, carrying_capacity, *fitness) + [
+        plotter_t(
+            np.tile(t[:,None], (1, seq_reps)), 
+            read_counts, 
+            scatter=True, 
+            ylabel="Read counts per strain",
+        ),
+        plotter_ref(
+            np.tile(ref_expansion[:,None], (1, seq_reps)), 
+            read_count_correction, 
+            scatter=True, 
+            fitlines=(ref_expansion[:,None], betas),
+            text=plot_text,
+            xlabel="Fold-expansion of wild-type",
+            ylabel="$\\frac{c_1(t)}{c_{wt}(t)} / \\frac{c_1(0)}{c_{wt}(0)}$",
+        ),
+        plotter_ref(
+            read_count_correction[1:2,...], 
+            read_count_correction, 
+            scatter=True, 
+            fitlines=(read_count_correction[1:2,...].flatten()[...,None], spike_betas),
+            text=plot_text_spike,
+            xlabel="$\\frac{c_{spike}(t)}{c_{wt}(t)} / \\frac{c_{spike}(0)}{c_{wt}(0)}$",
+            ylabel="$\\frac{c_1(t)}{c_{wt}(t)} / \\frac{c_1(0)}{c_{wt}(0)}$",
+        ),
+    ]
+
+with gr.Blocks() as demo:
+    inject_markdown("header.md")
+    # Growth curves
+    inject_markdown("growth-curve-intro.md")
+    mut_fitness_defaults = [.5, 2., .2]
+    with gr.Row():
+        relative_fitness = [
+            gr.Slider(0., 3., step=.1, value=w, label=f"Relative fitness, mutant {i + 1}")
+            for i, w in enumerate(mut_fitness_defaults)
+        ]
+    with gr.Row():
+        n_mutants = len(mut_fitness_defaults) 
+        inoculum = gr.Slider(
+            10, 1_000_000, 
+            step=10, 
+            value=1000, 
+            label="Average inoculum per strain",
+        )
+        inoculum_var = gr.Slider(
+            .001, 1., 
+            step=.001, 
+            value=.001, 
+            label="Inoculum variance between strains",
+        )
+        carrying_capacity = gr.Slider(
+            len(mut_fitness_defaults) + 1, 10_000, 
+            step=1, value=10, 
+            label="Total carrying capacity ($\times$ inoculum)",
+        )
+    plot_growth = gr.Button("Plot growth curves")
+    growth_curves_t = gr.Plot(label="Growth vs time", format="png")
+
+    inject_markdown("growth-curve-t-independent.md")
+    growth_curves_ref = gr.Plot(label="Growth vs WT expansion", format="png")
+    growth_curves = [growth_curves_t, growth_curves_ref]
+
+    # Read counts
+    inject_markdown("read-counts-intro.md")
+    with gr.Row():
+        sample_frac = gr.Slider(
+            .001, 1., step=.001, 
+            value=.1, 
+            label="Fraction of population per sample",
+        )
+        seq_reps = gr.Slider(
+            1, 10, 
+            step=1, 
+            value=3, 
+            label="Technical replicates",
+        )
+    with gr.Row():
+        seq_depth = gr.Slider(
+            10, 10_000, 
+            step=10, 
+            value=10_000, 
+            label="Average reads per strain per sample",
+        )
+        read_var = gr.Slider(
+            .001, 1., 
+            step=.001, 
+            value=.001, 
+            label="Sequencing variance",
+        )
+    plot_reads = gr.Button("Plot read counts")
+    read_curves_t = gr.Plot(label="Read counts vs time", format="png")
+
+    inject_markdown("read-counts-expansion.md")
+    read_curves_ref = gr.Plot(label="Read count diff vs WT expansion", format="png")
+
+    inject_markdown("read-counts-spike.md")
+    read_curves_t2 = gr.Plot(label="Read count diff vs spike count diff", format="png")
+
+    read_curves = [
+        read_curves_t, 
+        read_curves_ref,
+        read_curves_t2,
+    ]
+
+    # Events
+    plot_growth.click(
+        fn=growth_plotter,
+        inputs=[inoculum, inoculum_var, carrying_capacity, *relative_fitness],
+        outputs=growth_curves,
+    )
+    plot_reads.click(
+        fn=reads_plotter,
+        inputs=[sample_frac, seq_reps, seq_depth, read_var] + [inoculum, inoculum_var, carrying_capacity, *relative_fitness],
+        outputs=growth_curves + read_curves,
+    )
+
+demo.launch(share=True)

requirements.txt

@@ -0,0 +1,4 @@
+carabiner-tools[pd,mpl]>=0.0.4
+numpy<2
+gradio==5.23.3
+scipy

sources/growth-curve-intro.md

@@ -0,0 +1,29 @@
+## Multiplex growth curves
+
+How do strains grow when competing with each other?
+
+That's given by the [Lotka–Volterra competition model](https://en.wikipedia.org/wiki/Competitive_Lotka%E2%80%93Volterra_equations). 
+For two strains:
+
+$$
+\frac{dn_{wt}}{dt} = w_{wt} n_{wt} \left( 1 - \frac{n_{wt} + n_{1}}{K} \right)
+$$
+
+$$
+\frac{dn_1}{dt} = w_{1} n_1 \left( 1 - \frac{n_{wt} + n_{1}}{K} \right)
+$$
+
+
+- $n_i(t)$: abundance of species (or strain) $i$ at time $t$.
+- $w_i$: intrinsic (exponential) growth rate of species $i$.
+- $K$: carrying capacity.
+
+We can generalize to many strains. For each one:
+
+$$
+\frac{dn_i}{dt} = w_{i} n_i \left( 1 - \frac{\Sigma_j n_j}{K} \right)
+$$
+
+It's not possible to algebraically integrate these equations, since they are
+circularly dependent on each other. But we can numerically integrate, to simulate 
+multiplexed growth curves.

sources/growth-curve-t-independent.md

@@ -0,0 +1,30 @@
+### Removing time dependence
+
+It can be difficult to get absolute fitness out of these curves, because 
+when the pool approaches the carrying capacity, all the strains growth rates 
+mutually affect each other. 
+
+However, if we're only interested in the relative fitness of multiplexed strains relative
+to a reference (e.g. wild-type) strain, then we can make this simplification:
+
+$$
+\frac{dn_{i}}{dt} / \frac{dn_{wt}}{dt} = \frac{dn_{i}}{dn_{wt}} = \frac{w_{i} n_i}{w_{wt} n_{wt}}
+$$
+
+The interdependency term cancels out, and time is removed, with the reference strain's
+growth acting as the clock. Unlike the time-dependent Lotka-Volterra equations, this
+has a closed-form integral:
+
+$$
+\log n_i(t) = \frac{w_i}{w_{wt}} \log \frac{n_{wt}(t)}{n_{wt}(0)} + \log{n_i(0)}
+$$
+
+So now the log of the number of cells of a mutant at any moment ($n_1(t)$) is dependent only
+on its inoculum ($n_1(0)$), how much the reference strain has grown (i.e. fold-expansion, 
+$\frac{n_{wt}(t)}{n_{wt}(0)}$), and the ratio of fitness between the mutant and the 
+reference ($\frac{n_{wt}(t)}{n_{wt}(0)}$).
+
+Plotting the number of cells of a mutant against the reference fold-expansion gives 
+a straight line (on log scales), with intercept being the mutant inoculum and gradient
+being its relative fitness with respect to the reference strain's fitness.
+

sources/header.md

@@ -0,0 +1 @@
+# Fitness estimation from pooled growth

sources/read-counts-expansion.md

@@ -0,0 +1,51 @@
+### Accounting for sequencing subsampling per sample
+
+Each sequencing sample $s$ could be over- or under-sampling the population relative to the first
+timepoint by some factor $\phi_s$.
+
+$$\log \frac{c_i(t)}{c_i(0)} = \log \phi_s\frac{n_i(t)}{n_i(0)} = \log \phi_s + \frac{w_i}{w_{wt}} \log \frac{n_{wt}(t)}{n_{wt}(0)}$$
+
+Variables:
+- $c_i(t)$: Read (or UMI) count of strain $i$ at time $t$
+- $\phi_s$: The ratio of sampling depth at time $t$ to that at time $0$ for sample $s$
+
+The factor $\phi_s$ is the ratio of _the ratio of read counts between samples_ 
+and _the ratio of cell counts between samples_ for any strain (assuming each strain
+is sampled without bias):
+
+$$\log \phi_s = \log \frac{c_i(t)}{c_i(0)} - \log \frac{n_i(0)}{n_i(0)}$$
+
+We can get rid of the nuisance parameter $\phi_s$ (which is difficult to measure becuase
+we don't know the true number of cells for each strain and sample) using the following trick.
+
+We have the equation for read counts for mutant $i$ (same as above):
+
+$$
+\log \frac{c_i(t)}{c_i(0)} = \log \phi_s + \frac{w_i}{w_{wt}} \log \frac{n_{wt}(t)}{n_{wt}(0)}
+$$
+
+And for the reference strain (relative fitness is 1):
+
+$$
+\log \frac{c_{wt}(t)}{c_{wt}(0)} = \log \phi_s + \log \frac{n_{wt}(t)}{n_{wt}(0)}
+$$
+
+We can make $\phi_s$ disappear by taking the difference:
+
+$$
+\log \frac{c_i(t)}{c_i(0)} - \log \frac{c_{wt}(t)}{c_{wt}(0)} = \frac{w_i}{w_{wt}} \log \frac{n_{wt}(t)}{n_{wt}(0)} - \log \frac{n_{wt}(t)}{n_{wt}(0)}
+$$
+
+This is equivalent to:
+
+$$
+\log \left( \frac{c_i(t)}{c_{wt}(t)}\frac{c_{wt}(0)}{c_i(0)} \right) = \left(\frac{w_i}{w_{wt}} - 1 \right) \log \frac{n_{wt}(t)}{n_{wt}(0)}
+$$
+
+So the ratio of _the count ratio of a strain to the reference strain at time t_ to 
+_the count ratio of a strain to the reference strain at time 0_ is
+dependent only on the relative fitness and the true fold-expansion of the reference strain.
+
+Plotting the ratio of _the count ratio of a strain to the reference strain at time t_ to 
+_the count ratio of a strain to the reference strain at time 0_ 
+should give a straight line (on a log-log) plot, with intercept 0 and gradient equal to the relative fitness minus 1.

sources/read-counts-intro.md

@@ -0,0 +1,19 @@
+## Read counts from next-generation sequencing
+
+But we don't actually measure the number of cells directly. Instead, we're measuring the
+number of reads (or UMIs) which represent a random sampling of the population followed by
+molecular biology handling and uneven sequencing per lane which decouples the relative
+abundances for each timepoint. 
+
+Below, you can simulate read counts for technical replicates of the growth curves above.
+The simulation:
+
+1. Randomly samples a defined fraction of the cell population (without replacement, i.e.
+the [Hypergeometric distribution](https://en.wikipedia.org/wiki/Hypergeometric_distribution)).
+Smaller samples from smaller populations are noisier.
+2. Calculates the resulting proportional representation of every strain in every sample.
+3. Multiplies that proportion by read depth.
+4. Randomly samples sequencing read counts resulting from variations in library construction
+and other stochasticity, according to the 
+[Negative Binomial distribution](https://en.wikipedia.org/wiki/Negative_binomial_distribution), 
+an established noise model for sequencing counts.

sources/read-counts-spike.md

@@ -0,0 +1,30 @@
+### Using spike-in counts
+
+But we don't actually know the true fold-expansion of the reference strain, since 
+it's not directly observed. However, a non-growing fitness-zero control can help,
+such as a heat-killed strain or a spike-in plasmid.
+
+We start with the equation before,
+
+$$
+\log \left( \frac{c_i(t)}{c_{wt}(t)}\frac{c_{wt}(0)}{c_i(0)} \right) = \left(\frac{w_i}{w_{wt}} - 1 \right) \log \frac{n_{wt}(t)}{n_{wt}(0)}
+$$
+
+But for the fitness-zero control, $w_{spike} = 0$, so:
+
+$$
+\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)}
+$$
+
+This means that, although we don't know how the reference strain grows directly, its
+growth is given from the ratio of the spike counts to the reference counts, normalized
+to the same ratio at time 0.
+
+This leaves us with the overall equation:
+
+$$
+\log \left( \frac{c_i(t)}{c_{wt}(t)}\frac{c_{wt}(0)}{c_i(0)} \right) = \left(1 - \frac{w_i}{w_{wt}} \right) \log \left( \frac{c_{spike}(t)}{c_{wt}(t)}\frac{c_{wt}(0)}{c_{spike}(0)} \right)
+$$
+
+If we plot the left hand side against the right, we should get a straight line for 
+each strain with intercept zero and gradient $1 - \frac{w_i}{w_{wt}}$.

sources/read-counts-stationary.md

@@ -0,0 +1,65 @@
+But we don't actually know the true fold-expansion of the reference strain, since 
+it's not directly observed. 
+
+But we _do_ know some things about it. For example, when the pool is far from carrying 
+capacity, the fold-expansion will be close to exponential:
+
+$$
+\log \frac{n_{wt}(t)}{n_{wt}(0)} = w_{wt} t
+$$
+
+And at the carrying capacity, the fold-expansion stops changing with time, arrested
+at the carrying capacity minus the other cells in the pool:
+
+$$
+\log \frac{n_{wt}(t)}{n_{wt}(0)} = \log \frac{K - \Sigma_j n_j}{n_{wt}(0)}
+$$
+
+So at very early timepoints, long before carrying capacity is reached,
+
+$$
+\log \left( \frac{c_i(t)}{c_{wt}(t)}\frac{c_{wt}(0)}{c_i(0)} \right) = \left(\frac{w_i}{w_{wt}} - 1 \right) w_{wt} t
+$$
+
+or equivalently,
+
+$$
+\log \frac{c_i(t)}{c_{wt}(t)} = \log \frac{c_i(0)}{c_{wt}(0)} + (w_i - w_{wt}) t
+$$
+
+So at early timepoints, the log-ratio of a strain's counts to reference counts increases linearly 
+over time with the fitness difference between the strain and the reference. The fitness difference 
+is useful, but the ratio would be better. (Alternatively, we could use a known value of the reference 
+fitness measured separately).
+
+And after carrying capacity is reached,
+
+$$
+\log \frac{c_i(t)}{c_{wt}(t)} = \log \frac{c_i(0)}{c_{wt}(0)} + \left(\frac{w_i}{w_{wt}} - 1 \right) \log \frac{K - \Sigma_j n_j}{n_{wt}(0)}
+$$
+
+So in this regime, the log-ratio of a strain's counts to reference counts is fixed. 
+Subtracting the log-ratio of a strain's counts to reference counts in the input leaves:
+
+$$
+\log \frac{c_i(t)}{c_{wt}(t)} - \log \frac{c_i(0)}{c_{wt}(0)} = \left(\frac{w_i}{w_{wt}} - 1 \right) \log \frac{K - \Sigma_j n_j}{n_{wt}(0)}
+$$
+
+But we still can't get the relative finess without dividing by the constant
+
+$$
+\log \frac{K - \Sigma_j n_j}{n_{wt}(0)}
+$$
+
+which we don't know directly. However, the final trick is to use a non-growing control, so that 
+
+$$\frac{w_i}{w_{wt}} = 0$$
+
+That means that for this control, 
+
+$$
+\log \frac{c_i(t)}{c_{wt}(t)} - \log \frac{c_i(0)}{c_{wt}(0)} = - \log \frac{K - \Sigma_j n_j}{n_{wt}(0)}
+$$
+
+We can then get the relative fitness ratio for the other strains directly.
+