Help & Documentation
Disclaimer
mouseExperiment
is provided "as is" for research purposes only,
without warranty of any kind, express or implied. The authors and contributors
accept no liability for errors, inaccuracies, or any consequences — including
but not limited to incorrect results, data loss, or decisions made on the basis
of outputs from this software.
All results must be independently validated before use in publications, reports,
regulatory submissions, clinical decisions, or any other application.
Quick start
-
On the
Data
tab, under
Try Demo Data
, choose
All Features
and click
Load Demo Data
.
-
Below the column mapping, check
Study Design
: volume units mm³ and the
control group Vehicle.
-
Open
Tumor Growth
and click
Run Analysis
; the results open on the Summary tab.
-
Look through the other result tabs (Plots, Comparisons, Diagnostics), then save what you
need from
Download Results
. Every other analysis tab works the same way.
Basic Workflow
-
Data tab
— upload a CSV file and map your columns (ID, time, volume, treatment). Optional columns: cage, dose, body weight, survival/censor indicator. The Data check below the summary then lists likely errors in the file (duplicates, negative volumes, large jumps, missed days) with their line numbers.
-
Study Design
(on the Data tab) — declare the tumour volume units (mm³ or cm³), the control group, and, when a cage column is mapped, whether cage labels are unique across the study or numbered within each arm (C1 and C2 in every arm are then different cages) and whether individual animals or whole cages were randomised. With a removal-reason column mapped, say what each reason means (death, weight loss, the volume limit, a planned end); Survival and Toxicity use it. Every analysis tab uses these settings; none has its own reference selector.
-
Analysis tabs
— each tab activates once the required columns are mapped:
-
Tumor Growth
— always available after upload
-
Survival
— requires a survival/censor column (or use the volume-threshold derivation)
-
Toxicity
— requires a body weight column
-
Dose Response
— requires a dose column
-
Drug Synergy
— requires control, single-agent A, single-agent B, and combination groups
-
Power Analysis
— always available; no data upload needed for a priori modes
-
Select the statistical
method
in the sidebar, configure parameters, and click
Run Analysis
. The
beside an option explains it: hover over it, or click or tap it.
-
Explore results across sub-tabs (summary, plots, pairwise comparisons, model output). Each Diagnostics tab has a
How to read this plot
note under every plot.
-
Download one table or plot from the button beside it, or choose any mix of tables, plots, diagnostics and data from a tab's
Download Results
tab: one ZIP, with plots in PNG, PDF or SVG and a README listing every file, the settings of the run and the package versions. Every tab also offers an
R script
that repeats the run with the mouseExperiment package, from the analysed data that comes with it; tick
Include my original file
and it starts from the file you uploaded, replaying your exclusions, the study days, the volumes and the arm labels. Tumor Growth also offers an HTML report.
- Long analyses (Bayesian fits, randomisation tests, the power simulation, the body-weight model) run on a background worker, so the app stays usable. You can close the browser and come back: a banner at the top lets you resume or cancel.
-
To reuse the column mapping and settings with another file of the same layout, save them with
Save Preset
at the bottom of the Data tab and load them next time.
Data Format
Upload data in
long format
: one row per measurement per animal, as a CSV file (.csv) of up to 30 MB. Commas, semicolons or tabs can separate the columns (with a semicolon or tab, a decimal comma is read correctly), and the file can be UTF-8, Latin-1 or UTF-16.
Demo data
No data of your own? The Data tab ships four demo datasets:
-
Combo Treatment
— four arms with survival data, for the Drug Synergy tab.
-
Dose Levels
— graded doses with survival, for Dose Response.
-
Weight
— four arms with body weight, for Toxicity.
-
All Features
— the most complete, and the one that reaches every module:
six arms (vehicle, a three-dose series, a second drug and a combination), length/width/height,
body weight, dose, two cages per arm, necrosis flags, survival censoring and a removal-reason
column (tumour volume limit, weight loss, found dead, end of study).
Column auto-detection
The dashboard detects columns by name. Recognised patterns (case-insensitive):
| Role |
Recognised names |
Required? |
| Animal ID |
ID, Mouse_ID, Animal_ID, Subject, Tag, Ear Tag, Mouse Tag |
Yes |
| Time / Day |
Day, Time, Timepoint, Day_Number |
Yes ‡ |
| Date |
Date, Measurement_Date |
Yes ‡ |
| Tumor volume |
Volume, Tumor_Volume, TV |
Yes † |
| Tumor length |
Length, Tumor_Length |
Yes † |
| Tumor width |
Width, Tumor_Width |
Yes † |
| Tumor height |
mapped manually in Data Upload |
No |
| Treatment / Group |
Treatment, Group, Treatment_Group |
Yes |
| Cage |
Cage, Cage_ID |
No |
| Dose |
Dose, Dose_Level, Concentration, Conc |
No |
| Body weight |
Weight, Mass, Body_Weight, Body Mass, BW |
No |
| Sex |
Sex, Gender, M/F |
No |
| Necrotic flag |
Necrotic, Necrosis, Necr, Is_Necrotic, Necrotic_Flag |
No |
| Removal reason |
Removal_Reason, Reason, Cause_Of_Death, Fate |
No |
| Survival / Censor |
Survival_Censor, Censor, Event, Survival_Event |
No |
† Provide either a pre-calculated Volume column, or Length + Width columns.
When volume is calculated from calipers, six formulas are selectable in Data Upload:
ellipsoid (default,
π·L·W²/6
), modified ellipsoid (
L·W²/2
) — the common preclinical convention — plus 3-axis ellipsoid, cylinder,
sphere and box. The 3-axis and box formulas use a Height column if one is mapped; the others
approximate height by width. Volumes may be supplied in mm³ or cm³.
‡ Supply either a numeric Day column or a Date column; elapsed days are derived from the date and a reference start date.
Survival/Censor must be numeric:
1 = endpoint reached
(e.g. tumour exceeded IACUC volume limit),
0 = censored
(alive or study-end censored). If absent, use the volume-threshold derivation in the Survival tab sidebar. An animal's time to event is its last measurement day, or with the volume threshold, the first day its tumour reaches the limit; no separate time column is needed.
Key Concepts
Evaluable days
An arm is evaluable on a day when at least 50% of its enrolled animals, and at least 3 animals, are still on study (measured on that day or later).
Comparisons on one day, or over a window, use only days on which every arm compared is
evaluable. The AUC's window ends at the last such day. Dose Response and the therapeutic
window use the last evaluable day unless you choose another, and Drug Synergy offers every
evaluable day or one of them. Later than that, an arm is represented by too few animals,
and by the ones whose tumours grew slowest, for a fair comparison.
Glossary
- Reference group
-
The control arm chosen under Study Design. Comparisons are made against it, or between
all pairs of arms where a tab offers that.
- Geometric mean
-
The average taken on the log scale and converted back: the typical tumour volume. A few
very large tumours move it far less than they move the ordinary (arithmetic) mean.
Model-based estimates of tumour volume are geometric means.
- TGI (tumour growth inhibition)
-
(1 − treated volume / control volume) × 100 at the evaluation day, from each arm's
mean volume: the geometric mean under the model-based estimand, the arithmetic mean under
the observed ones. 100 % means no tumour left, 0 % the same as control, and a negative
value a larger tumour than control.
- Estimand
-
What a number is meant to estimate, decided before looking at the data. For example,
each arm's mean volume on day 21 had every animal stayed on study (model-based), or the
mean of the animals still present on day 21 (survivors). They differ when animals leave
early, and the Toxicity and Drug Synergy sidebars let you choose.
- Random effects (random slopes)
-
Each animal's own starting size and growth rate, around its arm's. They let a model use
repeated measurements of the same animal correctly, instead of treating them as
independent animals.
- Adjusted and unadjusted p-values
-
Comparing several arms with the control makes several tests, and some p-values will be
small by chance. An adjusted p-value (Dunnett, Tukey, Holm, Bonferroni or FDR) accounts
for the whole family of comparisons shown, and adjusted intervals do the same for
intervals. Report adjusted values when several arms are compared; an unadjusted value
suits only a single planned comparison.
- Confidence and credible intervals
-
A 95 % confidence interval (frequentist) comes from a procedure that covers the true
value in 95 % of repeated studies. A 95 % credible interval (Bayesian) contains the
value with 95 % probability, given the data, the model and its priors.
- Hazard ratio and time ratio
-
A hazard ratio below 1 means the endpoint is reached at a lower rate than in the
reference arm. A time ratio above 1 (Bayesian survival) means it takes longer to reach.
- Bliss difference
-
The combination's observed effect minus the effect expected if the two drugs acted
independently, in percentage points. Positive suggests synergy, negative antagonism;
its 95 % interval decides the verdict.
Analysis Modules
Tumor Growth
- LME4 (linear mixed-effects)
- Log-transforms tumor volume and fits a linear mixed model with a Treatment × Day interaction. Each animal has its own intercept and growth rate (random slopes), falling back to simpler structures only if the fit fails; the ANOVA reports F-tests with Satterthwaite degrees of freedom. Cage handling is chosen to match the housing design rather than applied uniformly — see the tab's Info panel. Pairwise contrasts via emmeans; the comparison family and its correction are two separate settings, defaulting to vs-reference with an exact Dunnett correction.
- AUC (area under the curve)
- The area under each arm's fitted growth curve over the window in which every arm is evaluable (at least 50 % of its enrolled animals, and at least 3, on study). Animals that die or are removed early count through all their measurements, so early deaths of large tumours do not pull the AUC down. Arms are compared by the ratio of their AUCs, with intervals and Wald p-values from the model and the selected correction. Each animal's own trapezoidal AUC is shown for description only: an animal removed early accumulates less area from being measured for less time.
- Bayesian LMM (brms)
- The LME4 model fitted via MCMC (Stan). Returns posterior distributions for treatment effects with credible intervals, plus convergence diagnostics (Rhat, ESS, trace and rank plots) and PSIS-LOO influence measures. Requires the brms package.
- Randomisation test (optional, any frequentist mode)
- Permutes treatment labels and refits, giving an exact p-value for the Treatment × Day interaction that assumes neither a denominator-df approximation nor normal random effects. The unit permuted, individual animals or whole cages, is the unit of randomisation declared under Study Design on the Data tab — the test is only valid if that matches how the experiment was actually run.
- Growth Delay
-
A per-animal endpoint from the data the run analysed, without the model: T − C,
the median time for an arm's tumours to reach a volume you set, minus the reference
arm's, with a bootstrap interval, a log-rank test against the reference, and the
specific growth delay (T − C in the reference arm's doubling times). A table
gives each animal's time.
Survival Analysis
- Kaplan-Meier
- Non-parametric survival estimates with 95% confidence bands. Log-rank test for group differences.
- Cox proportional hazards
- Semi-parametric Cox PH model. Hazard ratios with 95% CI for each treatment vs. reference. When whole cages were randomised (Study Design), each arm is instead compared with the reference by a cage-level permutation log-rank, and the hazard ratios have no interval. Firth's bias-reduced estimation is applied automatically when any arm has zero events, where the standard partial likelihood would return infinite coefficients. The proportional-hazards assumption is tested and reported — if it fails, the hazard ratio is an average over a period in which the true ratio changed, and should not be quoted as a single number.
- Accelerated failure time (AFT)
- A parametric model of the time to the endpoint (Weibull, log-normal or log-logistic, the best by AIC unless you choose). Each arm is compared with the reference as a time ratio: 1.8 means its animals take 1.8 times as long to reach the endpoint. It does not assume proportional hazards, so use it when the Cox model's check rejects them. Diagnostics compares the distributions and draws the fit against Kaplan-Meier.
- Bayesian AFT (brms)
- Accelerated failure time model with a Weibull or log-normal distribution. Returns time ratios and derived hazard ratios with credible intervals.
Toxicity (Body Weight)
- LME4 body weight model
- Linear mixed model of body weight over time, with each animal's own intercept and slope. Each arm's rate of weight change (per day) is compared with the reference arm's; weight at the mean study day is reported as well. Tumour mass can be subtracted from body weight first (on by default).
- Therapeutic window
- Sets each arm's tumor growth inhibition beside its mean worst weight loss (each animal's largest drop below its own first weighing), each with a 95% interval, and flags the weight loss as Tolerated, Not tolerated or Unclear against a threshold you set (default 20%). The two axes are read separately; a single efficacy-toxicity ratio was reported before version 26.09.005 and was withdrawn.
- Weight-loss time-to-event
- Kaplan-Meier for time to crossing a weight-loss threshold. With a removal-reason column mapped on Data Upload, removals for weight loss count as events, planned ends as censoring, and other removals (such as tumour burden) as competing events, with an Aalen-Johansen cumulative incidence estimate. Without one, an animal whose record ends early is censored, and the tab says so. A per-arm breakdown of how animals left is reported.
- Endpoint estimand
-
Shared by the therapeutic window and the Drug Synergy tab.
Model-based
(recommended) estimates each arm's geometric mean at the endpoint day from a mixed model of every observation, so animals removed earlier still count.
Each animal's last observation
uses every animal's final measurement, whatever day it was taken.
Survivors
uses only animals still present at the endpoint day; because the fastest-growing tumours leave first, it flatters the control arm and understates TGI, and is kept only to reproduce older figures.
Drug Synergy
- Bliss Independence
- The expected combined effect if the two drugs act independently: with FE = TGI / 100, Expected FE = FE_A + FE_B − FE_A × FE_B. The observed combination is compared with it at one day or across every evaluable day, and the difference is reported in percentage points. Positive = synergy; negative = antagonism.
- Why there is no Combination Index
-
Loewe additivity, which a Combination Index measures, is
dose-equivalence: it needs a dose-response curve for each agent,
which single-dose designs do not provide. The usual single-dose
stand-in is
response additivity
, which fails the sham-combination test: combining a drug with
itself it predicts twice the effect, so an agent at 50 % inhibition
should reach 100 %, and when it does not the method calls the drug
antagonistic with itself. Measured across the effect grid with the
combination set to exactly Bliss-additive, 42 % of cells were
labelled antagonistic and none synergistic.
- Interval on the verdict
- The synergy verdict comes from the 95 % interval for the Bliss excess: Synergy when it lies above zero, Antagonism when it lies below, and Additive (no departure from Bliss detected) when it contains zero. Without intervals the label says so.
Dose-Response
- One agent's dose series
- A curve describes one agent at several doses against the study's control. Choose the agent's arms in the sidebar; other agents, combinations, and arms sharing a dose cannot join the same curve.
- Hill / Emax
- Fits a four-parameter log-logistic (4PL) dose-response curve via nonlinear least squares; with six or more doses a five-parameter (asymmetric) curve is also tried and kept when AIC prefers it. The lower asymptote cannot fall below zero. Reports the EC50 (the dose giving half the fitted response range) with a 95% interval on log dose, the Hill slope, and the fitted curve; an EC50 outside the tested doses is flagged.
- Trend tests
- Alongside the curve fit, the tab reports linear and quadratic trend p-values and a two-sided Jonckheere-Terpstra test. The last is the one that respects dose ordering: it asks whether response is monotone in dose, which is the question a dose-response study is usually posing, rather than merely whether the groups differ.
Power Analysis
- Analytic (a priori)
- Classical power for each treated-vs-control comparison (two-sample t-test), with the alpha split across the comparisons a multi-arm study makes (Dunnett or Bonferroni) and an optional attrition allowance, across a range of effect sizes and sample sizes.
- Survival endpoint (a priori)
- Under the analytic mode, choose "Hazard ratio" to plan the time to an event, such as the tumour volume limit, compared by the log-rank test. Schoenfeld's approximation gives the events one comparison needs from the hazard ratio, and the animals per arm from the share of controls expected to have the event by the end. It is asymptotic, so with few events treat the N as a minimum.
- LMM simulation
- Simulates repeated-measures data under a linear mixed model and estimates power empirically across a grid of sample sizes. An optional euthanasia volume limit models attrition; leaving it blank assumes every animal is measured at every timepoint, which overstates power by roughly 6 points at 30 % attrition. Note that baseline SD and random-intercept SD do not affect the answer — the test is on growth rates, which are orthogonal to per-animal baselines. Random-slope SD is the parameter that matters.
Results
- Every run, kept
- Each analysis you run is listed on the Results tab, newest first, until the session ends. Open one to show it again in its tab, with its tables, plots and Download Results (the sidebar keeps its current settings). Select several to download them together: one folder each, with what the tab's Download Results offers, the plots drawn with the tab's current settings.
- No refit for the same fit
- A Bayesian fit with the same data and settings as one already run in the session is shown again rather than refitted; the seed is fixed, so a refit would give the same results.
Troubleshooting
- File won't upload
- Save it as CSV (.csv), up to 30 MB. If a row is reported with the wrong number of fields, a value probably contains the separator, such as a comma inside a treatment name: quote that value or remove the comma.
- Columns not auto-detected
- Use the column mapping dropdowns in the Data tab to assign columns manually.
- Analysis tab is greyed out
- Upload and configure data first. Survival requires a censor column (or enable volume-threshold derivation). Toxicity requires a body weight column. Dose Response requires a dose column. Drug Synergy requires at least four treatment groups.
- Analysis fails or produces no output
- Verify that the selected columns contain valid, non-missing data. Tumor volumes must be positive. Time points must be numeric. At least two groups must be present for any comparison.
- Bayesian model is slow to start
- The first fit of a model compiles it, which takes about two minutes on mouseexperiment.com and less on a fast computer; later fits with the same structure reuse it and usually take under a minute. On mouseexperiment.com compiled models are kept across restarts and updates of the server, so each structure is compiled once; on your own computer, see ?clear_compiled_model_cache to keep them between R sessions. Fits run one at a time on a background worker, so other users and tabs stay responsive, and yours may wait for one ahead of it.
- Plot download produces a blank file
- Run the analysis first, then click the download button. Download Results draws every plot of the run with the current settings (colours, titles, sizes), including plot types you have not opened.