Release: v2.0.0
Lead authors: Ng and Krishnamurthy

This repository contains the data, analysis code, kinetic fitting routines, figure notebooks, and mechanistic simulations associated with the LUCas project. LUCas uses photo-cleavable interfering guide RNAs (PC-igRNAs) to control Cas13a activity with light.

Cas13a target recognition activates nonspecific reporter cleavage, producing a fluorescent diagnostic signal. In LUCas, a photo-cleavable interfering guide suppresses this activity before illumination and releases it after a selected light dose. The deposited experiments characterize light-dependent activation, guide and target-concentration effects, assay background and limit of detection, operation in plasma and after RPA amplification, fluorescence anisotropy, DNA fragment inputs, and sequential illumination for multiplexed/temporally barcoded readout. The accompanying ODE models test how caging efficiency, optical crosstalk, target abundance, and kinetic parameters affect recovery of one or more target concentrations. Raw plate-reader workbooks, processed tables, model fits, statistical summaries, and manuscript-ready figures are included so users can either reproduce figures directly or rerun the fitting workflows.

The code supports:

• fluorescence time-series fitting before and after illumination;
• suppression-factor and limit-of-detection (LOD) analysis;
• photo-uncaging/light-dose model fitting;
• plasma, RPA-coupled, and DNA-fragment experiments;
• full two-phase and three-phase ODE simulations; and
• multiplexed target-recovery simulations and parameter sweeps.

What is new in v2.0.0

Relative to the January 2026 Dryad/code release (lucas-paper-code-v2.0.zip), this version adds:

• a single-phase Michaelis–Menten-style photo-uncaging model in
  lucas_utils/lightdose.py;
• a command-line light-dose fitting workflow,
  scripts/lightdose-timeseries-data-fitting.py;
• notebooks/figure-1-lightdose-plots.ipynb for fitting and plotting the illumination-dose response;
• full ODE notebooks for two-phase activation and three-phase multiplexed readout in Lucas ODE/;
• a multiplexed ODE parameter-sweep notebook that tests target-recovery accuracy, spectral crosstalk, suppression factors, and conditioning;
• analysis and plotting workflows for plasma, RPA-coupled LUCas, and DNA fragments; and
• expanded LOD analysis for PC-igRNAs.

Repository map

lucas-paper-code/
├── configs/                  YAML analysis configurations
├── data/
│   ├── raw/                  source plate-reader and anisotropy workbooks
│   └── processed/            calibrated, fitted, and summarized tables
├── scripts/                  executable analysis workflows
├── lucas_utils/              reusable analysis package
├── notebooks/                manuscript-figure notebooks
├── Lucas ODE/                mechanistic models, reference data, and sweeps
├── tests/                    notebook-based validation workflows
├── results/                  generated figures and fit diagnostics - figures not included in Dryad upload
├── archived/                 superseded notebooks retained for provenance
├── requirements.txt          analysis-environment requirements
├── pyproject.toml            local-package metadata and dependencies
└── README.md                 dataset guide and data dictionary

Start with the section matching your goal:

Detailed deposit inventory

This section follows the directory tree so that it can be used alongside a file browser. Dates at the start of filenames are experiment dates in YYYYMMDD format. Files with a common suffix form one repeatable product class; those suffixes are defined under data/processed/ below.

Individual variables are listed and described in the Data Dictionary section below.

configs/

The 13 YAML files contain machine-readable inputs for the analysis scripts: dataset name and description, relative input/output paths, Excel header rows, multi-index names, guide subsets, fluorescence calibration settings, transient exclusion time, fit mode, and export switches.

• 19T-PC-cr4-targetsweep.yaml,
  19T-PC-cr4-cr6-cr7_target-conc-1e6cp_uL.yaml, and
  9T-PC-guides-target-1e6cp_ul.yaml configure the Figure 2 kinetic datasets.
• 19T-PC-cr4-LOD.yaml, 19T-PC-cr6-LOD.yaml, and
  19T-PC-cr7-LOD.yaml configure the three guide-specific LOD analyses.
• 19T-PC-cr4-background.yaml and cr4-background.yaml configure caged and uncaged guide background-rate measurements over RNP concentration.
• LUCas_lightdose_19TC-pc-igRNA.yaml configures the Figure 1 illumination-dose fit, including the measured energy per second used to convert exposure time to light dose.
• LUCas_plasma_20260310.yaml, LUCas_RPA_20260525.yaml, and
  LUCas_RPA_20260612.yaml configure the plasma and RPA-coupled experiments.
• 20260307_20T_DNA_Fragments.yaml records the DNA-fragment workflow. Its original raw-workbook path points to a manuscript supplementary-material directory outside this code deposit; the derived CSV tables needed for figure reproduction are included in data/processed/figure-6-DNA-fragments/.

data/raw/

Raw .xlsx files contain plate-reader observations in wide format. The first three to six rows form a hierarchical header describing the condition shared by each block of replicate wells; the first column contains elapsed time. Numeric measurement cells are unmodified instrument fluorescence/intensity values unless the filename explicitly says otherwise.

See section Data Dictionary for variable descriptions.

• figure-1-lucas-demo/: two demonstration experiments. 20240409 UV different dosages.xlsx varies illumination exposure time; 20250717 19TCPC second run demo.xlsx is a second PC-igRNA demonstration time course.
• figure-2-lucas-kinetics/: a 19T-PC-cr4 target-concentration sweep, a
  cr4/cr6/cr7 comparison at 1e6 cp/uL, and a 9T-PC guide comparison at 1e6 cp/uL.
• figure-3-background-kinetics-lod/: cr4, cr6, and cr7 LOD dilution series, plus caged and uncaged cr4 background kinetics over RNP concentration.
• figure-4-clinically relevant/: PC-igRNA measurements in plasma versus water, an RNase-inhibitor control, and two RPA-coupled LUCas experiments.
• figure-5-anisotropy/: parallel/perpendicular fluorescence-intensity and
  total-fluorescence workbooks for pulsed and single illumination, plus the 9T/19T guide anisotropy comparison. These files distinguish RNP, free-guide, and blank conditions.
• figure-6-temporal-barcoding/: multiplexed time courses with varied cr4:cr2
  target ratios and with SARS-CoV-2/Flu A target combinations.

data/processed/

Processed files preserve the experiment grouping used under data/raw/. Modern fitting outputs follow these suffix patterns:

• *_processed.csv: calibrated long-form observations with one row per time point, condition, and well.
• *_fit_data.csv: observations plus the corresponding model-predicted fit value.
• *_fit_param_data.csv: one row per fitted well and phase, containing fitted parameters and goodness-of-fit metrics.
• *_reaction_rate_data.csv: rates and uncertainties summarized by guide, concentration, and phase.
• *_suppression_factors.csv: post/pre rate ratios with propagated uncertainty.
• *_lod_summary.csv: mean LOD signal and standard error by concentration.

The contents by subdirectory are:

• figure-1-lucas-demo/: converted reporter concentrations, a legacy linear regression table, long-form light-dose data, single-phase fits, fitted parameters, and rate summaries.
• figure-2-lucas-kinetics/: fit traces, fit parameters, rate summaries, and suppression factors for each of the three Figure 2 raw workbooks.
• figure-3-background-kinetics-lod/: per-guide processed LOD observations and LOD summaries for cr4/cr6/cr7, plus background processed observations, rate summaries, and suppression factors.
• figure-4-clinically relevant/: fit traces, fit parameters, and rate summaries for the plasma/RNase-inhibitor and RPA experiments.
• figure-5-anisotropy/: anisotropy, blank-subtraction, and instantaneous-slope calculation workbooks. These processed .xlsx files intentionally retain formulas so every derived value can be traced to measured intensity or fluorescence cells.
• figure-6-DNA-fragments/: fit traces, fitted parameters, and rate summaries for the 20T DNA-fragment concentration sweep.
• figure-6-temporal-barcoding/: converted and baseline-corrected multiplexed time courses, pre/post illumination slopes, normalized rate changes, and linear-regression summaries for target-ratio and whole-virus experiments.

scripts/

• fl-timeseries-data-fitting.py takes a YAML configuration and its raw Excel workbook, reshapes and calibrates fluorescence data, detects the illumination interval, fits each well before/after illumination, and writes processed, fitted, parameter, rate, and diagnostic files.
• background-fl-timeseries-data-fitting.py takes a background-kinetics YAML and workbook, applies calibration and phase-aware linear fitting, and writes processed observations and scaled background-rate summaries.
• compute-suppression-factors.py takes a generated reaction-rate CSV and writes the post/pre suppression-factor CSV with propagated uncertainty.
• lod-timeseries-data-fitting.py takes an LOD YAML and workbook, performs robust joint slope analysis, and writes per-guide processed and LOD-summary CSVs plus diagnostic figures.
• lightdose-timeseries-data-fitting.py takes the light-dose YAML and converted time series, fits the single-phase uncaging model, and writes long-form, fitted, parameter, rate-summary, and diagnostic outputs.

lucas_utils/ and lucas_utils.egg-info/

• models.py: linear/exponential phase models and rate extraction.
• data_processing.py: workbook reshaping, fluorescence calibration, normalization, phase labeling, and rate/concentration helpers.
• lightdose.py: single-phase photo-uncaging model, fitting, summaries, and diagnostics.
• lod_models.py: robust covariance, bootstrap, and LOD models.
• plotting.py and plot_style.py: shared manuscript plotting functions and styles.
• stat_tests.py: Mann–Whitney tests and multiple-comparison correction.
• parameters.py: phase names, filename suffixes, calibration constants, and guide display labels.
• utils.py: concentration/unit conversion and general helpers.
• io.py: reserved I/O helper module; it currently contains no analysis logic.
• __init__.py: package exports.

lucas_utils.egg-info/ is generated installation metadata (PKG-INFO, source list, requirements, dependency links, and top-level package name), and lucas_utils/__pycache__/ is generated bytecode. Neither contains primary or derived research observations; both may be omitted from a clean deposit.

notebooks/

The six current notebooks read processed data and create manuscript panels:

• figure-1-lightdose-plots.ipynb: illumination dose, initial rate, and uncaging-timescale fits.
• figure-2-plots.ipynb: kinetics and suppression-factor panels.
• figure-3-plots.ipynb: background kinetics, LOD summaries, and sigmoid LOD fits.
• figure-4-plasma.ipynb: plasma/water time courses and rates.
• figure-4.ipynb: RPA-coupled time courses, rates, target/NTC tests, and ratios.
• figure-6-DNA-fragments-plots.ipynb: DNA-fragment fits and concentration response.

Lucas ODE/

• two_phase_activation_ode.ipynb, three_phase_multiplexed_ode.ipynb, and
  multiplexed_lucas_parameter_sweep.ipynb contain the single-target, three-target, and parameter-sweep models described later in this README.
• Ramachandran_etal_MM_fit.ipynb compares the reduced analytical reporter model with a published numerical model.
• Ramachandran_etal_data/AnalyticalModel.csv and NumericalModel.csv contain normalized time, cleaved-reporter fraction, and categorical data type (Analytical or Numerical). The JPEG in that folder is the source reference image used for the comparison.
• qc_fits/*.png are condition-specific parameter-sweep fit diagnostics; filenames encode condition number, replicate, target concentrations, crosstalk, and suppression settings. qc_smoke_fit.png is the minimal end-to-end check.

results/

Images are not included in the Dryad deposit for licensing reasons. The scripts output PNG and SVG files into results/figures/.

PNG files are raster previews and SVG files are editable vector equivalents. They are all derived outputs, grouped as follows: Figure 1 light-dose fits; Figure 2 kinetics; Figure 3 background/LOD; Figure 4 plasma/RPA; Figure 5 anisotropy; Figure 6 DNA-fragment and temporal-barcoding plots; and figure-lucas-model/ ODE trajectories, target-recovery heatmaps/scatter plots, and per-condition QC fits. ODE result filenames encode the simulated target, suppression, photoactivation, or crosstalk condition. These groups are outputs, not additional input data.

tests/, archived/, and root files

• tests/test_*.py is the automated pytest suite. It uses synthetic data to check fluorescence fitting, the pre/post fit-to-rate pipeline, uncertainty and rate extraction, and logistic LOD fitting/bootstrap behavior; conftest.py provides shared deterministic fixtures.
• tests/test_lod_pipeline.ipynb and tests/test_relative_change_pipeline.ipynb are interactive synthetic-data checks of the LOD and relative-change/bootstrap workflows.
• The eight notebooks under archived/ are superseded kinetics, background, LOD, and kcat/KM analysis/plotting workflows retained only for provenance. Use scripts/ and notebooks/ for current reproduction.
• requirements.txt lists the analysis dependencies; pyproject.toml defines the installable lucas_utils package; root __init__.py is a package marker; .gitignore contains version-control exclusions; and .github/copilot-instructions.md contains development guidance rather than scientific content.

Installation

Python 3.10 or later is recommended. From the repository root:

python -m venv .venv
source .venv/bin/activate       # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install -e .

The editable install makes lucas_utils importable from scripts and notebooks.
The analysis uses NumPy, pandas, SciPy, Matplotlib, seaborn, lmfit, scikit-learn, statsmodels, PyYAML, and openpyxl. See requirements.txt and pyproject.toml for the declared dependencies.

Launch notebooks from the repository root so that relative paths resolve consistently:

jupyter lab

Portable paths

Current scripts and ODE model cells resolve their included inputs and outputs relative to the repository root. In particular, the light-dose config reads
data/raw/figure-1-lucas-demo/20240409 UV different dosages.xlsx, and the ODE notebooks save figures below results/figures/figure-lucas-model/.

One exception is configs/20260307_20T_DNA_Fragments.yaml: it records the original raw-workbook location outside this code deposit. The processed DNA fragment tables required by the supplied Figure 6 notebook are included. To rerun that raw-data fit, place the supplementary workbook in the location named by data_path or update data_path to the workbook's location after download.

The ODE notebooks determine repo_root when launched from either the repository root or the Lucas ODE/ directory. For all other figure notebooks, launching JupyterLab from the repository root is recommended. Stored notebook output may display paths from the computer on which a notebook was last executed; these display-only outputs do not control where files are read or written on a new run.

Reproducing the experimental analyses

Analysis scripts read one YAML file from configs/, write tables under data/processed/, and write diagnostics under results/figures/. Run all commands below from the repository root.

1. Fit pre- and post-stimulation fluorescence data

python scripts/fl-timeseries-data-fitting.py LUCas_RPA_20260612.yaml

Replace the YAML filename with the experiment of interest. This script:

1. loads the raw Excel workbook;
2. converts fluorescence units to cleaved-reporter concentration when required;
3. separates pre- and post-stimulation phases;
4. fits each well with the configured linear or exponential model; and
5. saves fitted traces, parameters, and reaction-rate tables.

For scripts that do not yet accept a command-line config argument, set CONFIG_FILE near the top of the script before running it.

2. Compute suppression factors

Set CONFIG_FILE in scripts/compute-suppression-factors.py, then run:

python scripts/compute-suppression-factors.py

The script compares post-illumination and pre-illumination reaction rates, propagates fit uncertainty, and performs the configured statistical comparisons.

3. Fit background kinetics

Set CONFIG_FILE in scripts/background-fl-timeseries-data-fitting.py, then run:

python scripts/background-fl-timeseries-data-fitting.py

4. Calculate limits of detection

Set CONFIG_FILE in scripts/lod-timeseries-data-fitting.py to one of:

• 19T-PC-cr4-LOD.yaml
• 19T-PC-cr6-LOD.yaml
• 19T-PC-cr7-LOD.yaml

Then run:

python scripts/lod-timeseries-data-fitting.py

The LOD workflow uses joint linear fits, selects HC3 or HAC robust covariance according to residual autocorrelation, and uses bootstrap confidence intervals for the relative-change analysis.

5. Fit the light-dose/photo-uncaging experiment

python scripts/lightdose-timeseries-data-fitting.py \
  --config configs/LUCas_lightdose_19TC-pc-igRNA.yaml

This workflow:

1. imports the converted reporter-concentration time series;
2. baseline-corrects each trace;
3. fits each light-dose condition with
   (C(t)=C_\infty-(C_\infty-C_0)e^{-t/\tau});
4. calculates the initial rate
   (v_0=(C_\infty-C_0)/\tau);
5. summarizes replicate rates and standard errors; and
6. writes long-form data, fitted traces, parameter tables, reaction-rate summaries, and a diagnostic plot.

The main options are in the YAML file:

• data_path, processed_path, and figures_path;
• Excel header and multi-index layout under import_settings;
• fixed (C_\infty), minimum point count, and column names under fit_settings; and
• which tables and diagnostics to save under export_settings.

Use notebooks/figure-1-lightdose-plots.ipynb to fit the dose-response curve and generate the light-dose and uncaging-timescale plots from these outputs.

ODE simulations

The notebooks in Lucas ODE/ are exploratory, executable model documents.
Run their cells in order; parameters and initial conditions are defined near the top of each notebook.

Two-phase activation

two_phase_activation_ode.ipynb models one guide-target species with caged and uncaged RNP pools. It integrates the pre-illumination phase, applies an illumination update to the molecular pools, and continues the integration after activation. It also includes target-concentration sweeps and reduced-model fitting.

Use this notebook to:

• inspect the full state trajectories around one illumination event;
• change kinetic constants, suppression, or uncaging efficiency;
• compare numerical reporter cleavage with a reduced analytical fit; and
• test recovery of a single target concentration.

Multiplexed parameter sweep

multiplexed_lucas_parameter_sweep.ipynb generates synthetic observations with the full multiplexed ODE model, fits them with a reduced global model, and measures target-recovery accuracy over parameter grids. It examines:

• target concentrations;
• guide suppression factors;
• photoactivation efficiency and spectral crosstalk;
• weakest-signal and orthogonality metrics; and
• numerical conditioning of the multiplexed inverse problem.

Sweep tables, heatmaps, scatter plots, and selected fit diagnostics are written below results/figures/figure-lucas-model/. Large sweeps can take substantially longer than the other notebooks; first run the included smoke/QC condition before expanding the grid.

Reference comparison

Ramachandran_etal_MM_fit.ipynb compares analytical and numerical reporter cleavage behavior and uses lucas_utils.lightdose.single_phase_mm. It provides context for the reduced reporter-cleavage model used in the fitting workflows.

Figure notebooks

The current figure notebooks are:

Figure notebooks generally read from data/processed/ and save SVG output to
results/figures/. They are organized by manuscript panel. Run cells in order,
especially the data-loading and output-directory cells at the beginning.

Configuration files and data products

Each YAML config records the source workbook, experiment description, Excel header layout, guide and concentration fields, calibration/fitting choices, and output directories. To analyze a new dataset:

1. place its workbook under data/raw/;
2. copy the nearest matching YAML file in configs/;
3. update its paths, column layout, and fitting options; and
4. pass the YAML filename to a script, or set that script's CONFIG_FILE.

Common output filenames are:

• *_fit_data.csv: observed and fitted time-series values;
• *_fit_param_data.csv: per-well fitted parameters and fit metrics;
• *_reaction_rate_data.csv: per-well or summarized reaction rates; and
• *_suppression_factors.csv: pre/post rate ratios and statistics.

Existing processed tables are included so that users interested only in figure reproduction do not need to rerun every fit.

CSV and Excel data structure

Why merged cells are retained in Excel files

The raw and anisotropy Excel workbooks intentionally use merged cells in their multi-row headers. A merged header spans the replicate well columns to which one experimental attribute applies—for example one guide, target concentration, sample type, RNP concentration, illumination exposure, or molecular state. The merge therefore encodes the grouping relationship between condition metadata and replicate measurements and is required by the current import configurations (header and multiindex in configs/*.yaml). Removing these merges without first repeating every group label in every replicate column would make the raw layout ambiguous and break direct reproduction with the supplied scripts.

The processed anisotropy workbooks also retain formulas. These are essential, not decorative: they expose blank subtraction, anisotropy calculations, time conversion, and instantaneous-slope calculations. There are no charts, filters, comments, or frozen panes required for analysis in these workbooks. Cell color or highlighting is not used as a scientific variable.

For programmatic use:

• modern processed CSVs have a single header row and can be read normally;
• raw Excel files should be read with the header-row list and multi-index names specified in the matching YAML configuration;
• legacy wide CSVs beginning with Guide, Guides, or Exposure Time use four metadata/header rows before numeric observations;
• baseline-corrected wide CSVs use one header row, with repeated condition names representing replicate wells; and
• regression-summary CSVs are report-shaped tables: experimental conditions are columns and statistic names such as Slope are rows. They are not tidy observation tables.

This structure is retained to preserve compatibility with the original analysis and the experimental grouping. Users who require a fully rectangular table can forward-fill the metadata header rows horizontally, combine the header levels, and pivot the replicate columns to long format with one row per time point and well. The supplied scripts perform this reshaping for the current workflows.

Data dictionary

The same variables recur across files, so each is defined once below. Names are case-sensitive as written in the files. NA/blank means not applicable or not estimated. Unless a file states otherwise, concentrations are nonnegative and time/rate variables are continuous numeric values.

Experimental identifiers and raw-workbook headers

Guide nomenclature

Legacy identifiers in raw and processed files are converted to
publication-facing guide names using GUIDE_NAMES_MAP in
lucas_utils/parameters.py:

The number after gRNA or igRNA is the manuscript guide number; 9T and 19T identify the interfering-guide architecture. Underscores in legacy names are storage-safe separators and are not additional biological attributes. Newer RPA files already use display-form labels such as crRNA 4 and pc-igRNA 4; these labels are retained directly and are not translated through GUIDE_NAMES_MAP.

Measured and transformed signals

Kinetic-fit parameter tables

Rate, suppression, and LOD summary tables

ODE reference-data columns

Analysis conventions

• Experiments with illumination phases use pre-stimulation and
  post-stimulation labels.
• The stimulation boundary is inferred from the largest gap in the recorded
  time series.
• Post-stimulation fitting skips the transient interval specified by
  TRANSIENT_TIME (60 s by default).
• conc_label is the display value, while conc_numeric is used for numeric
  filtering and sorting.
• Fluorescence calibration is gain- and experiment-dependent; calibration
  constants are stored in lucas_utils/parameters.py or encoded in the relevant
  workflow.
• Statistical comparisons use Mann–Whitney U tests with Holm correction where
  indicated.

Core modules

• lucas_utils/models.py: pre/post-stimulation linear and exponential fits.
• lucas_utils/lightdose.py: light-dose loading, baseline correction, single-phase fitting, rate summaries, and diagnostics.
• lucas_utils/data_processing.py: calibration, reshaping, normalization, and phase splitting.
• lucas_utils/lod_models.py: robust joint fits and bootstrap LOD analysis.
• lucas_utils/stat_tests.py: hypothesis tests and multiple-comparison correction.
• lucas_utils/plotting.py and plot_style.py: shared plotting conventions.
• lucas_utils/io.py: file-loading and output helpers.
• lucas_utils/parameters.py: global constants, guide labels, and calibrations.

Validation and troubleshooting

The tests/ directory contains automated unit/integration tests and two interactive validation notebooks. To run the automated suite:

python -m pip install -e ".[test]"
python -m pytest

The tests use deterministic synthetic data and do not modify experimental files. The notebooks are:

• test_lod_pipeline.ipynb
• test_relative_change_pipeline.ipynb

Run their cells sequentially in JupyterLab for an inspectable validation of the same LOD and relative-change calculations.

If a workflow fails:

1. confirm that the YAML data_path exists on your computer;
2. check that the workbook's multi-level headers match header and
   multiindex;
3. confirm that guide names and concentration labels match the workbook;
4. launch Jupyter from the repository root;
5. ensure that python -m pip install -e . completed in the active environment;
   and
6. check the per-well diagnostic plots before interpreting summary parameters.

Re-running a fitting script may overwrite files with the same output names.
Keep the archived Dryad download unchanged if you need an immutable copy of the published outputs.

Citation and attribution

*Lead Authors:* Ng & Krishnamurthy

C. F. Ng, D. Krishnamurthy, A. A. Dextre, A. Chorlay, M. Ott, and D. A. Fletcher. “LUCas: Light-Uncaged Cas13a using photo-cleavable interfering guide RNAs.”

This dataset and analysis pipeline were developed for the LUCas project at the Fletcher Lab, University of California, Berkeley.

*Project:* LUCas: Light-Uncaged Cas13a using photocleavable interfering guide RNAs

When using this archive, cite both the associated article and the Dryad dataset version/DOI shown on the dataset landing page.