Docs: Metrics reference (formulas + sources) · Changelog · Tests:
Rscript tests/test_v28.R(52 checks),Rscript tests/test_metrics_parity.R(29 parity checks vs lysis-curve-app)Looking for the full analysis platform (Analysis tab, 30+ metrics, statistics, heatmaps, curve fitting, virulence metrics)? That's the companion app: mbaffour/lysis-curve-app. This repo is the lightweight plotter.
If you have R installed, you don't need the terminal:
| OS | Double-click |
|---|---|
| Windows | Run Lysis Curve Plotter.bat |
| macOS | Run Lysis Curve Plotter.command |
| Linux | ./run.sh |
The first run installs the required R packages (a few minutes); after that the app opens in your web browser instantly. You can also run it directly with Rscript run_app.R.
This is an interactive tool for visualizing Optical Density (OD) time-series data. You upload a CSV file containing your experimental measurements, and the app generates publication-quality plots with full control over colors, shapes, error bars, axis scales, labels, and more.
You can export your plots as PDF, PNG, JPEG, SVG, TIFF, PowerPoint, or animated GIF — and (new in v2.8) export the underlying summary statistics and curve metrics as CSV, or generate a complete single-file HTML or PDF analysis report containing the figure, statistics tables, metric definitions, data provenance, and session info.
Not sure where to start? Click "Load Demo Data" under the file picker to explore the app with a built-in example dataset (3 samples × 3 replicates).
You need two free programs. Install them in this order.
- Go to https://cloud.r-project.org
- Click the link for your operating system:
- Windows: Click "Download R for Windows" → "base" → "Download R-4.x.x for Windows". Run the installer and accept all defaults.
- Mac: Click "Download R for macOS". Choose the
.pkgfile that matches your Mac (Apple Silicon or Intel). Open the file and follow the prompts.
- You do not need to open R directly — RStudio will use it behind the scenes.
- Go to https://posit.co/download/rstudio-desktop/
- Click the big "Download RStudio" button. It should auto-detect your operating system.
- Run the installer and accept all defaults.
- Open RStudio (not R). You should see a window with several panels.
Packages are add-ons that the app depends on. You only need to do this once.
- Open RStudio.
- In the bottom-left panel (called the Console), you'll see a blinking cursor next to a
>symbol. - Copy and paste the following command into the Console, then press Enter:
install.packages(c(
"shiny", "tidyverse", "ggpubr", "scales",
"ggrepel", "ggprism", "svglite", "jsonlite",
"officer", "rvg", "gifski", "base64enc", "gridExtra"
))- Wait for the installation to finish. This may take several minutes. You'll see lots of text scrolling by — that's normal. When it's done, you'll see the
>cursor again.
If you see any errors mentioning a specific package, try installing that package individually:
install.packages("package_name_here")Note: The officer, rvg, gifski, base64enc, and gridExtra packages are optional. Without them, the PowerPoint, GIF, HTML-report, and PDF-report buttons (respectively) will be disabled, but everything else works fine.
- In RStudio, go to File → Open File and navigate to the
Lysis_Curve_App_v28.Rfile. - The file will open in the top-left editor panel.
- Click the "Run App" button at the top-right of the editor panel. It has a green play icon and the text "Run App".
- If you don't see "Run App", make sure the
.Rfile is the active tab in the editor.
- If you don't see "Run App", make sure the
- A new window will pop up with the app. If it opens in a small RStudio window, click "Open in Browser" at the top for a better experience.
To stop the app, click the red stop-sign icon in the RStudio Console, or press Esc in the Console.
The app accepts CSV files (.csv). Your data should be structured in one of two formats.
Each column is a different sample, and each row is a time point. The first column should be time.
| Time | Sample_A | Sample_B | Sample_C |
|---|---|---|---|
| 0 | 0.05 | 0.06 | 0.04 |
| 30 | 0.12 | 0.15 | 0.10 |
| 60 | 0.35 | 0.40 | 0.28 |
| 90 | 0.70 | 0.82 | 0.61 |
If you have replicates, give them the same column name. The app will automatically calculate the mean and standard deviation.
Accuracy note (fixed in v2.8): versions up to v2.7 silently used only the first column of each repeated name, so means were based on a single replicate and error bars disappeared. v2.8 pools all replicate columns correctly. After loading a file, check the green data summary box under the file picker — it shows exactly how many replicate columns were detected per sample, so you can confirm the app read your data the way you intended.
| Time | WT | WT | WT | Mutant | Mutant | Mutant |
|---|---|---|---|---|---|---|
| 0 | 0.05 | 0.06 | 0.04 | 0.05 | 0.04 | 0.06 |
| 30 | 0.12 | 0.15 | 0.10 | 0.08 | 0.09 | 0.07 |
Three columns: time, a grouping column (e.g., "Sample" or "Condition"), and a value column.
| Time | Sample | OD |
|---|---|---|
| 0 | WT | 0.05 |
| 0 | WT | 0.06 |
| 0 | Mutant | 0.04 |
| 30 | WT | 0.12 |
| 30 | Mutant | 0.08 |
The app auto-detects which format you're using.
Click "Browse..." next to "Choose CSV File" and select your file. The plot will appear automatically on the right side.
Under Variable Styling → Sample Selection, use the dropdown to check or uncheck which samples appear on the plot.
All settings are in the left sidebar, organized into collapsible sections. Click on any section header to expand it.
Axis Settings — Change between linear, logarithmic, square root, or reverse axis scales. Customize tick marks, axis labels, fonts, and gridlines. The default Y-axis is logarithmic (common for OD data).
Time Point Filtering — Restrict the displayed time range or exclude specific time points (e.g., removing an outlier at time 0).
Region Highlighting — Add colored rectangular regions to highlight specific areas of the plot (e.g., a growth phase).
Time Point Markers — Add vertical lines at specific time points (e.g., when a treatment was added).
Color Palettes — Choose from preset palettes (Viridis, Colorblind-friendly, Publication, etc.) or use custom colors per sample.
Line & Point Settings — Control line thickness and point appearance. Toggle points on/off and adjust their size.
Label Options — Add labels at the end of each line to identify samples without needing the legend.
Error Bars / Shadow — Display variability as error bars (T-shaped or lines) or as a shaded ribbon around each line. Choose between SD, SEM, or 95% CI. If you only have one replicate per sample per time point, error bars will simply not appear (there's no variability to show).
Variable Styling — Fine-tune each sample individually: set its color (from presets, HEX code, or RGB sliders), point shape (circle, square, triangle, etc.), line type (solid, dashed, dotted, etc.), and legend label.
Under Save / Load Settings, you can:
- Save Settings — Downloads a
.jsonfile containing all your visual settings (colors, shapes, line types, axis options, etc.). Does not save your data. - Load Settings — Upload a previously saved
.jsonfile to restore your settings. If the sample names in the settings file match your current data, their colors/shapes/linetypes are applied automatically. - Clear & Reset — Restores everything to default values.
This is useful when you want to apply the same visual style to different datasets.
Expand the Plot Dimensions & Export section.
- Set the canvas size (width/height in pixels) to control how the plot looks on screen.
- Set the export dimensions (width/height in inches) and DPI for the saved file.
- Choose a format: PDF (best for publications), PNG (best for presentations), JPEG, SVG (scalable), or TIFF.
- Click "Download Image".
Recommended settings for publications: PDF format, 10×8 inches, 300 DPI.
Click "Download PowerPoint (.pptx)". This creates a slide deck where each slide adds one more sample to the plot (a "cumulative build"), which is great for presentations where you want to walk through each sample one at a time. The final slide shows all samples together.
Set the frames per second and GIF dimensions, then click "Download Animated GIF". Like the PowerPoint, each frame adds one more sample. The GIF loops automatically.
Expand the Stats & Reports section in the sidebar. Everything here reflects the current sample selection and time filtering — exactly what the plot shows.
- Summary Statistics (CSV) — per sample and time point: mean, SD, n, SEM, and the 95% CI half-width (computed as t₀.₉₇₅,ₙ₋₁ × SEM).
ncounts only non-missing replicate values. - Curve Metrics (CSV) — 27 per-sample growth & lysis metrics using the same engine as the lysis-paper companion app (verified to reproduce its numbers by an automated parity suite): initial/max/min/final OD and their times, AUC (trapezoidal), μmax (centered rolling-window regression on ln OD; window adjustable, default 5 points), doubling time, lag phase (first time the rolling slope reaches 10% of μmax), stationary-phase duration, lysis onset (first post-peak decline > 5% of peak), lysis rate (regression slope peak→trough), OD drop, residual OD, recovery slope, lysis efficiency, recovery ratio, fold change, % drop from max, time to half-max after peak, and steepest point-to-point decline. Metrics that don't apply (e.g. doubling time for a curve that never grows) are reported as
NA, never fabricated. - Infection metrics — pick your uninfected control in Reference sample to add the five reference-normalized metrics: relative growth (AUC ratio), infection strength (1 − AUC ratio), relative μmax, relative max OD, and lysis-onset Δ from lag. (Note: the reference implementation in the companion app has an
ifelse()recycling bug that assigns the first sample's relative values to every sample; this app computes each sample's own ratio correctly.)
The Experiment Notebook sidebar section (modeled on the companion app's Experiment Notes tab) records the full experimental context: experiment ID, date, experimenter, project, lab; experiment type, host strain(s), phage/plasmid, MOI, replicate/batch; medium, temperature, time of infection, inducer; observations, issues, next steps, tags; plus three free key–value custom fields. Every non-empty field is embedded in the HTML and PDF reports automatically, so the report doubles as a complete lab-notebook record.
Fill in an optional title, author, and notes, then click:
- HTML Report — one self-contained
.htmlfile (openable in any browser, easily shared or printed to PDF) containing: the figure at export settings, the experiment notebook record, the summary statistics table, the curve metrics table with the definition of every metric, data provenance (file name, detected format, time column, filters applied, error settings), key visual settings, and the R/package versions used — everything needed to reproduce or defend the analysis. - PDF Report — the same content as a multi-page PDF (title/provenance page, notebook page, figure page, paginated tables). No LaTeX or pandoc required.
- Report base font size — scales all report text and tables in both formats.
All of this is live: change the Y-axis label (Axis Settings → Labels & Formatting), rename any legend entry (Variable Styling → Legend Label), switch fonts and sizes (title, axis labels, axis text, and legend each have their own size control), recolor any sample, then re-download the figure or regenerate the report — the outputs always reflect the current state of the plot.
"Error: could not find function..." — You're missing a package. Go back to Step 2 and install the missing package.
The app opens but the plot is blank. — Make sure you've uploaded a CSV file and that at least one sample is selected in the Sample Selection dropdown.
The plot shows an error message in red text. — This usually means something is wrong with the data or a setting combination. Try resetting settings with the "Clear & Reset" button. Check that your CSV has numeric values in the data columns and a proper time column.
Error bars / shadow ribbon doesn't show. — If you have only one replicate per sample per time point, the standard deviation is zero, so there's nothing to display. This is expected behavior. You need multiple replicates for error bars to be meaningful.
The app is slow or laggy. — If you have a very large number of samples, the app may take a moment to update. The app debounces inputs (waits 400ms after you stop adjusting before redrawing), so slight delays are intentional.
"Run App" button doesn't appear. — Make sure the .R file is open and is the active tab in the editor. Also confirm that the shiny package is installed.
I want to use this on another computer. — Copy the .R file and repeat Steps 1 and 2 on the new computer. Your saved settings .json files are portable and can be shared with collaborators.
- Install R from https://cloud.r-project.org
- Install RStudio from https://posit.co/download/rstudio-desktop/
- Open RStudio, paste the
install.packages(...)command into the Console, press Enter - Open the
.Rfile in RStudio → click "Run App" - Upload your CSV → adjust settings → export your plot
Lysis Curve OD Visualization App v2.8 — Michael Baffour Awuah / Ramsey Lab