The ctsApp package provides a graphical user interface (Shiny app) for the cts (Contraceptives DDI Trial Simulation Platform) package. It offers an intuitive web-based interface to design and simulate drug-drug interactions (DDI) involving contraceptive drugs using physiologically based pharmacokinetic (PBPK) models.
This guide explains how to use the application. A second document, the Audit Manual, explains what the application does behind the interface: which inputs are fixed, which values it fills in automatically, and every calculation it performs itself. Read it before quoting any number from the app in a report. Both manuals are linked from the About tab.
You can install the development version of ctsApp from GitHub:
# install.packages("pak")
pak::pak("esqLABS/ctsApp")To start the application, run:
ctsApp::run_app()This will open the application in your default web browser.
The ctsApp interface consists of two main areas.
The main area contains three tabs, plus links in the navigation bar:
| Tab | Description |
|---|---|
| Experiment Design | Summary of all configured parameters with demographic visualizations |
| Results | Simulation results with PK profiles, DDI analysis, and PK-PD analysis |
| About | Application description, links to both manuals, and version numbers |
The Results tab is already populated when the application starts, using results saved from an earlier run that ship with the package. Those results do not necessarily correspond to the settings shown in the sidebar. Press Run Simulation before reading or reporting any number. The Audit Manual documents this behaviour in detail.
In the Object accordion panel:
Only the protocols and formulations that belong to the selected compound are offered. To use a dose that is not in the predefined list, use “Create New Protocol”.
Model Ethinylestradiol (EE) effects is ticked by default. Most combined oral contraceptives pair the progestin with ethinylestradiol, and EE is itself a CYP/UGT and transporter substrate, so its own exposure can shift under a precipitant. When the box is ticked, an Ethinylestradiol Settings block appears with its own protocol and formulation selectors.
EE is co-administered in both simulated scenarios, with and without the precipitant, because it travels with the contraceptive. The baseline is therefore “object plus EE”, not the object alone.
Model Midazolam (CYP3A) reference is also ticked by default. Midazolam is the standard sensitive CYP3A index substrate, and the overlay lets you read the object’s exposure change against a well-characterised probe rather than in isolation. Its protocol defaults to the object’s schedule so that its later doses fall inside the induction window.
This reference is display only. It adds a curve you can switch on in the concentration-time plots, and it never affects the value boxes, the DDI ratios, or the PK-PD endpoints. It does cost extra simulation time, so untick it if you do not need it.
In the Precipitant accordion panel:
Select Compound: Choose the precipitant compound:
Select Protocol: Choose or create a dosing protocol
Select Formulation: Choose or create a formulation
In the Population accordion panel:
Select Population: Choose from the available population presets (e.g., “Healthy Women”, “Overweight Women”, “Class I Obese Women”, “Class II Obese Women”)
Number of Individuals: Set the number of virtual individuals (1-100, default 10). Note that higher numbers require more memory and increase simulation time.
Age Range: Define the age range for the population (default 20-60 years). The range resets to the default whenever you change the population preset.
Physical Parameters: Depending on the preset, configure either:
SHBG: The sex hormone binding globulin distribution (geometric mean and geometric standard deviation) is pre-filled from the selected preset and can be adjusted.
All populations are entirely female by construction, and the population sampling uses a fixed random seed, so identical settings always produce the same virtual individuals.
In the Simulation Parameters accordion panel:
Duration: Set the simulation duration and unit (seconds through months)
Resolution: Set the number of time points per hour (default 1)
The duration is set automatically. Whenever a protocol changes, the app rewrites the Duration and Unit fields to match the longest administration window of the object and precipitant protocols, choosing a sensible unit and rounding to a whole number. This keeps the simulation on-treatment, because the PK-PD endpoints are read from the last dosing interval. If you type your own duration and then change a protocol, your value will be replaced. A warning appears on the PK-PD tab if the simulation runs past the end of contraceptive administration.
Once all parameters are configured:
The Run Simulation button becomes enabled (it remains disabled until all required inputs are valid)
Click Run Simulation to execute the DDI simulation
The simulation creates two scenarios:
With the midazolam reference enabled, two further display-only simulations are run: midazolam alone and midazolam plus the precipitant.
After the simulation completes, navigate to the Results tab to view:
All concentrations and exposure metrics are total plasma concentrations (bound plus unbound) in peripheral venous blood, which is what clinical pharmacokinetic studies usually report.
Translates the simulated object exposure into two contraceptive efficacy endpoints:
Each panel compares the object alone against the DDI scenario. Markers show the population median and the bars span the 5th to 95th percentile across individuals.
This tab is only available when:
The percentile bars reflect the spread of exposure across individuals only. They do not include uncertainty in the underlying exposure-response parameters. See the Audit Manual before interpreting them.
For the precipitant compound, you can upload custom compound models:
Uploaded compounds are added to the current session only; the packaged model file is never modified. Because an uploaded compound has no predefined protocol or formulation list, all protocols and formulations in the session are offered for it, including ones meant for other compounds.
When “Create New Protocol” is selected:
| Parameter | Description |
|---|---|
| Dose | Dose amount and unit (mg, g) |
| Type | Oral, Intravenous Bolus, or Intravenous |
| Interval | Single dose, once/twice/thrice/four times daily |
| Start Time | When dosing begins |
| End Time | When dosing ends |
For oral administration: - Water Volume/Body Weight: Volume of water co-administered
For IV administration: - Infusion Time: Duration of infusion
When “Create New Formulation” is selected, choose from:
| Type | Description |
|---|---|
| Dissolved | Immediate release, fully dissolved |
| Weibull | Weibull dissolution kinetics |
| Lint80 | Linear dissolution to 80% |
| Particle | Particle-based dissolution (mono/polydisperse) |
| Table | Custom dissolution profile via time-fraction table |
| Zero Order | Constant release rate |
| First Order | Exponential release kinetics |
Each formulation type has specific parameters to configure.
Click Export Snapshot to download a JSON file containing:
This snapshot can be: - Imported into PK-Sim for further analysis - Shared with collaborators - Used as a starting point for future simulations
The export captures the inputs, not the results. Record the version numbers shown on the About tab alongside it.
Pearl Index and Ovulation Rate are available for Drospirenone and Levonorgestrel only, and require a repeated-dose object protocol. With a single-dose protocol the tab explains this; with any other object compound it renders empty.
That is expected: the duration is recalculated from the protocol administration window whenever a protocol changes. Set the protocols first, then adjust the duration if you need to.
The application ships saved results and shows them at startup. Press Run Simulation to replace them with results that match your settings.