Package 'osp.snapshots'

Description

Add one or more Compound objects to a Snapshot.

Usage

add_compound(snapshot, compound)

Arguments

Value

The updated Snapshot object, returned invisibly.

Examples

## Not run: 
snapshot <- load_snapshot("Midazolam") |>
  add_compound(create_compound(name = "Drug X"))

snapshot <- load_snapshot("Midazolam") |>
  add_compound(list(
    create_compound(name = "Drug X"),
    create_compound(name = "Drug Y")
  ))

## End(Not run)

Description

Add one or more Event objects to a Snapshot.

Usage

add_event(snapshot, event)

Arguments

Value

The updated Snapshot object, returned invisibly.

Examples

## Not run: 
evt <- create_event(
  name = "Breakfast",
  template = "Meal: Standard (Human)"
)
snapshot <- load_snapshot("Midazolam") |>
  add_event(evt)

snapshot <- load_snapshot("Midazolam") |>
  add_event(list(evt, evt))

## End(Not run)

Description

Add one or more ExpressionProfile objects to a Snapshot.

Usage

add_expression_profile(snapshot, expression_profile)

Arguments

Value

The updated Snapshot object, returned invisibly.

Examples

## Not run: 
# Load a snapshot
snapshot <- load_snapshot("Midazolam")

# Create a new expression profile
profile_data <- list(
  Type = "Enzyme",
  Species = "Human",
  Molecule = "CYP3A4",
  Category = "Healthy",
  Parameters = list()
)
profile <- ExpressionProfile$new(profile_data)

# Add a single expression profile
snapshot <- add_expression_profile(snapshot, profile)

# Add several at once
snapshot <- add_expression_profile(snapshot, list(profile, profile))

## End(Not run)

Description

Add one or more Formulation objects to a Snapshot.

Usage

add_formulation(snapshot, formulation)

Arguments

Value

The updated Snapshot object, returned invisibly.

Examples

## Not run: 
# Load a snapshot
snapshot <- load_snapshot("Midazolam")

# Add a single formulation
form <- create_formulation(name = "Tablet", type = "Weibull")
snapshot <- add_formulation(snapshot, form)

# Add several at once
forms <- list(
  create_formulation("Tablet", type = "Weibull"),
  create_formulation("Oral solution", type = "First Order")
)
snapshot <- add_formulation(snapshot, forms)

## End(Not run)

Description

Add one or more Individual objects to a Snapshot.

Usage

add_individual(snapshot, individual)

Arguments

Value

The updated Snapshot object, returned invisibly.

Examples

## Not run: 
# Load a snapshot
snapshot <- load_snapshot("Midazolam")

# Add a single individual
ind <- create_individual(name = "New Patient", age = 35, weight = 70)
snapshot <- add_individual(snapshot, ind)

# Add several at once
patients <- list(
  create_individual("Patient_A", age = 25),
  create_individual("Patient_B", age = 45)
)
snapshot <- add_individual(snapshot, patients)

## End(Not run)

Description

Add one or more ospsuite::DataSet (observed data) objects to a Snapshot.

Usage

add_observed_data(snapshot, observed_data)

Arguments

Value

The updated Snapshot object, returned invisibly.

Examples

## Not run: 
dataset <- create_observed_data(
  name = "Study A",
  time = c(0, 1, 2),
  values = c(0, 5, 8),
  value_dimension = "Concentration (mass)"
)
snapshot <- load_snapshot("Midazolam") |>
  add_observed_data(dataset)

snapshot <- load_snapshot("Midazolam") |>
  add_observed_data(list(dataset, dataset))

## End(Not run)

Description

Add one or more ObserverSet building blocks to a Snapshot. The exported function is the canonical, pipeable surface for the mutation; it validates the snapshot before delegating to the underlying R6 method.

Usage

add_observer_set(snapshot, observer_set)

Arguments

Value

The updated Snapshot object, invisibly.

Examples

## Not run: 
snapshot <- load_snapshot("Midazolam")

observer_set <- ObserverSet$new(list(
  Name = "BrainPlasmaConcentration",
  Observers = list()
))

snapshot |> add_observer_set(observer_set)

snapshot |> add_observer_set(list(observer_set, observer_set))

## End(Not run)

Description

Add one or more Population objects to a Snapshot.

Usage

add_population(snapshot, population)

Arguments

Value

The updated Snapshot object, returned invisibly.

Examples

## Not run: 
pop <- create_population(name = "Adults", number_of_individuals = 100)
snapshot <- load_snapshot("Midazolam") |>
  add_population(pop)

snapshot <- load_snapshot("Midazolam") |>
  add_population(list(
    create_population(name = "Adults", number_of_individuals = 100),
    create_population(name = "Children", number_of_individuals = 50)
  ))

## End(Not run)

Description

Add one or more Protocol objects to a Snapshot.

Usage

add_protocol(snapshot, protocol)

Arguments

Value

The updated Snapshot object, returned invisibly.

Examples

## Not run: 
prot <- create_protocol(
  name = "Single oral dose",
  application_type = "Oral",
  dosing_interval = "Single"
)
snapshot <- load_snapshot("Midazolam") |>
  add_protocol(prot)

snapshot <- load_snapshot("Midazolam") |>
  add_protocol(list(prot, prot))

## End(Not run)

Description

Build a Simulation from named arguments and attach it to a Snapshot, or attach a pre-built Simulation.

A simulation is almost pure references into the snapshot, so the snapshot is its entry point. In build mode, with the snapshot in hand, add_simulation() resolves compound references and derives sensible defaults (calculation methods, formulation key, alternatives) from the referenced building blocks before attaching. Supply name plus exactly one of individual / population, and configure each compound inline through compounds, selecting a specific alternative by friendly property name and label, or a multi-slot protocol's formulations, where the derived defaults are not enough. References to building blocks not yet in the snapshot trigger one informational warning per simulation; the add proceeds either way.

Usage

add_simulation(
  snapshot,
  simulation = NULL,
  name = NULL,
  model = "4Comp",
  individual = NULL,
  population = NULL,
  compounds = NULL,
  events = NULL,
  observer_sets = NULL,
  observed_data_names = NULL,
  solver = NULL,
  output_schema = NULL,
  output_selections = NULL,
  output_mappings = NULL,
  parameters = NULL,
  advanced_parameters = NULL,
  description = NULL,
  allow_aging = NULL
)

Arguments

Value

The updated Snapshot object, returned invisibly.

Examples

## Not run: 
snapshot <- load_snapshot("Midazolam") |>
  add_simulation(
    name = "Sim 1",
    individual = "Korean (Yu 2004 study)",
    compounds = list(list(
      name = "Rifampicin",
      protocol = "Yu 2004 - Rifampicin - 600 mg MD OD 10 days",
      formulation = "Oral solution",
      processes = c("Hepatic"),
      alternatives = c(solubility = "FaSSIF")
    ))
  )

## End(Not run)

Description

An R6 class that represents an advanced parameter in a population.

Active bindings

Methods

Public methods

• AdvancedParameter$new()

• AdvancedParameter$print()

• AdvancedParameter$clone()

AdvancedParameter$new()

Create a new AdvancedParameter object

Usage

AdvancedParameter$new(data)

Arguments

Returns

A new AdvancedParameter object

AdvancedParameter$print()

Print a summary of the advanced parameter

Usage

AdvancedParameter$print(...)

Arguments

Returns

Invisibly returns the AdvancedParameter object for method chaining

AdvancedParameter$clone()

The objects of this class are cloneable with this method.

Usage

AdvancedParameter$clone(deep = FALSE)

Arguments

Description

Build an age value object for create_individual()'s age argument (or the writable Individual$age / OriginData$age field). Fills the OriginData Age characteristic (list(Value =, Unit =)).

Usage

age(value, unit = "year(s)")

Arguments

Value

An age_spec object to pass to create_individual().

See Also

create_individual()

Other value-object helpers: error(), fraction_unbound(), gestational_age(), height(), intestinal_permeability(), lipophilicity(), permeability(), solubility(), time(), values(), weight()

Examples

age(30)
create_individual(name = "Subject", age = age(30))

Description

Unified bridge from a Snapshot to the tidyverse for any building-block kind plus observed data. Replaces the nine per-kind ⁠get_*_dfs()⁠ functions as the canonical entry point; those remain available as thin wrappers. Omit kind to convert every kind of a snapshot in a single call.

Usage

as_tibbles(snapshot, kind = NULL)

Arguments

Value

When kind names a single collection, a tibble or a named list of tibbles for that collection (see below). When kind names several collections, or is NULL (all nine kinds), a named list keyed by the requested kinds, each entry the native shape of that kind:

• "compounds": a list with properties and processes tibbles. properties carries one row per (compound, physicochemical property) pair (plus folded process rows for backwards compatibility); processes is the long-form, one row per (compound, process, parameter) triple.

• "protocols", "observed_data": a single tibble.

• "observer_sets": a list with observer_sets (one row per ObserverSet) and observers (one row per Observer, joinable to its parent via observer_set_id / observer_set_name).

• "individuals": a list with individuals, individuals_parameters, individuals_expressions.

• "formulations": a list with formulations, formulations_parameters.

• "populations": a list with populations, populations_parameters.

• "events": a list with events, events_parameters.

• "expression_profiles": a list with expression_profiles, expression_profiles_parameters.

Examples

## Not run: 
snapshot <- load_snapshot("Midazolam")

# List of tibbles (compounds returns properties + processes)
compounds <- as_tibbles(snapshot, "compounds")
compounds$properties
compounds$processes

# List of tibbles
individuals <- as_tibbles(snapshot, "individuals")
individuals$individuals_parameters

# Omit `kind` to convert every kind at once, keyed by kind name
all_kinds <- as_tibbles(snapshot)
names(all_kinds)

## End(Not run)

Description

An R6 class that wraps the set of calculation methods PK-Sim uses to derive compound quantities (e.g. partition coefficient method, cellular permeability method, body surface area method). In an OSP snapshot, the calculation methods are serialised as an array of method name strings. They appear in two places: directly on a Compound and inside an OriginData of an Individual.

Active bindings

Methods

Public methods

• CalculationMethods$new()

• CalculationMethods$print()

• CalculationMethods$add()

• CalculationMethods$remove()

• CalculationMethods$to_list()

• CalculationMethods$clone()

CalculationMethods$new()

Create a new CalculationMethods object

Usage

CalculationMethods$new(names = character())

Arguments

Returns

A new CalculationMethods object

CalculationMethods$print()

Print a summary of the calculation methods

Usage

CalculationMethods$print(...)

Arguments

Returns

Invisibly returns the CalculationMethods object

CalculationMethods$add()

Add a method name. Duplicates are kept to mirror the snapshot's raw representation.

Usage

CalculationMethods$add(name)

Arguments

Returns

Invisibly returns the CalculationMethods object

CalculationMethods$remove()

Remove a method name. If name is not present, the set is unchanged. Note the asymmetry with ⁠$add()⁠: ⁠$add()⁠ keeps duplicates to mirror the snapshot's raw representation, whereas ⁠$remove()⁠ deletes every occurrence of name in a single call.

Usage

CalculationMethods$remove(name)

Arguments

Returns

Invisibly returns the CalculationMethods object

CalculationMethods$to_list()

Convert back to the raw snapshot representation: a list of method-name strings, or NULL when empty. A list is used (rather than a character vector) so that single-method sets round-trip as JSON arrays.

Usage

CalculationMethods$to_list()

Returns

A list of method-name strings, or NULL when empty.

CalculationMethods$clone()

The objects of this class are cloneable with this method.

Usage

CalculationMethods$clone(deep = FALSE)

Arguments

Description

An R6 class that represents a compound in an OSP snapshot. This class provides methods to access different properties of a compound and display a summary of its information.

Compound processes are exposed via ⁠$processes⁠, a flat named list of Process objects. The per-category tibble accessors (⁠$protein_binding_partners⁠, ⁠$metabolizing_enzymes⁠, ⁠$hepatic_clearance⁠, ⁠$transporter_proteins⁠, ⁠$renal_clearance⁠, ⁠$biliary_clearance⁠, ⁠$inhibition⁠, ⁠$induction⁠) are lifecycle::deprecate_soft()-warned in favour of ⁠$processes⁠ and the long-form processes tibble returned by get_compounds_dfs().

Active bindings

Methods

Public methods

• Compound$new()

• Compound$print()

• Compound$to_df()

• Compound$clone()

Compound$new()

Create a new Compound object

Usage

Compound$new(data)

Arguments

Returns

A new Compound object

Compound$print()

Print a summary of the compound including its properties and parameters.

Usage

Compound$print(...)

Arguments

Returns

Invisibly returns the Compound object for method chaining

Compound$to_df()

Convert this compound's physicochemical properties and process parameters to a single long-form tibble (legacy shape).

Used by get_compounds_dfs() to assemble the compound-wide properties tibble. The process-derived rows produced here are lifecycle::deprecate_soft()-warned at the get_compounds_dfs() entry point; prefer the long-form processes tibble returned alongside.

Usage

Compound$to_df()

Returns

A tibble with columns compound, category, type, parameter, value, unit, data_source, source.

Compound$clone()

The objects of this class are cloneable with this method.

Usage

Compound$clone(deep = FALSE)

Arguments

Description

An R6 class representing one entry in a CompoundProperties's Processes array. Selects a compound process by some combination of name, molecule, metabolite, compound, and systemic process type; the resolver in PK-Sim picks the right placeholder when only a subset of fields is supplied.

Active bindings

Methods

Public methods

• CompoundProcessSelection$new()

• CompoundProcessSelection$clone()

CompoundProcessSelection$new()

Create a new CompoundProcessSelection object.

Usage

CompoundProcessSelection$new(data)

Arguments

Returns

A new CompoundProcessSelection object.

CompoundProcessSelection$clone()

The objects of this class are cloneable with this method.

Usage

CompoundProcessSelection$clone(deep = FALSE)

Arguments

Description

Convert a time value and ospsuite unit to a lubridate duration object. This function handles unit conversion and special cases like kiloseconds.

Usage

convert_ospsuite_time_to_duration(value, unit)

Arguments

Value

A lubridate duration object

Description

Convert time units from ospsuite format to lubridate-compatible format. This function handles the mapping of units like "day(s)" to "days", etc.

Usage

convert_ospsuite_time_unit_to_lubridate(unit)

Arguments

Value

A lubridate-compatible time unit

Description

Create a Compound building block from named arguments. This is a thin factory around Compound$new() that builds the raw list shape for you, including the physicochemical properties, pKa, and processes.

Each of lipophilicity, fraction unbound, solubility (including reference pH, gain per charge, and table solubility), intestinal permeability, permeability, and pKa must be set through its dedicated argument (or by mutating the matching writable Compound field). The parameters argument is for additional/loose compound parameters only; it cannot set these physicochemical properties, because each lives in its own top-level alternative array or typed list rather than in Parameters.

Usage

create_compound(
  name,
  description = NULL,
  is_small_molecule = NULL,
  plasma_protein_binding_partner = NULL,
  molecular_weight = NULL,
  molecular_weight_unit = "g/mol",
  calculation_methods = NULL,
  parameters = NULL,
  lipophilicity = NULL,
  fraction_unbound = NULL,
  solubility = NULL,
  intestinal_permeability = NULL,
  permeability = NULL,
  pKa = NULL,
  processes = NULL
)

Arguments

Value

A Compound object.

See Also

lipophilicity(), fraction_unbound(), solubility(), intestinal_permeability(), permeability() for the physicochemical property helpers.

Examples

# Create a minimal compound
compound <- create_compound(name = "Drug X")

# Create a small molecule with molecular weight and binding partner
compound <- create_compound(
  name = "Drug X",
  is_small_molecule = TRUE,
  molecular_weight = 250.3,
  plasma_protein_binding_partner = "Albumin"
)

# Set the single-parameter physicochemical properties
compound <- create_compound(
  name = "Drug X",
  lipophilicity = lipophilicity(2.5),
  fraction_unbound = fraction_unbound(0.1),
  intestinal_permeability = intestinal_permeability(1.14e-05),
  permeability = permeability(0.0069)
)

# Solubility with reference pH and gain per charge
compound <- create_compound(
  name = "Drug X",
  solubility = solubility(9999, reference_pH = 7, gain_per_charge = 1000)
)

# Table-based solubility (first column pH, second column value)
compound <- create_compound(
  name = "Drug X",
  solubility = solubility(
    table = data.frame(
      pH = c(3, 6, 6.8),
      value = c(5000, 3000, 90)
    )
  )
)

# Several named solubility alternatives (the first is the default)
compound <- create_compound(
  name = "Drug X",
  solubility = list(
    solubility(9999, name = "Aqueous"),
    solubility(200, name = "FaSSIF")
  )
)

# Several named solubility alternatives, explicitly marking the default
compound <- create_compound(
  name = "Drug X",
  solubility = list(
    solubility(9999, name = "Aqueous"),
    solubility(200, name = "FaSSIF", default = TRUE)
  )
)

# Multiple pKa entries
compound <- create_compound(
  name = "Drug X",
  pKa = list(
    list(type = "Base", value = 10.02),
    list(type = "Acid", value = 1.7)
  )
)

# Attach a process
compound <- create_compound(
  name = "Drug X",
  processes = list(
    create_process(
      internal_name = "GlomerularFiltration",
      data_source = "Publication X"
    )
  )
)

# Additional/loose parameters (not physicochemical properties)
compound <- create_compound(
  name = "Drug X",
  parameters = list(
    create_parameter(name = "Cl_spec", value = 5, unit = "ml/min/kg")
  )
)

Description

Build a CompoundProcessSelection entry, used inside a CompoundProperties to record which compound processes are selected for the simulation.

All arguments are optional and serialized only when supplied. PK-Sim resolves the right process placeholder from whichever combination of fields is set.

Usage

create_compound_process_selection(
  name = NULL,
  molecule_name = NULL,
  metabolite_name = NULL,
  compound_name = NULL,
  systemic_process_type = NULL
)

Arguments

Value

A CompoundProcessSelection object.

Examples

create_compound_process_selection(
  name = "P-gp-Collett 2004",
  molecule_name = "P-gp"
)

create_compound_process_selection(systemic_process_type = "Hepatic")

Description

Build a single DescriptorCondition entry for an Observer's ContainerCriteria. A container criterion matches the containers an observer applies to by a Tag and an optional match Type. This is a small builder that returns the raw named list; assemble several of them into a list for create_observer() or observer$container_criteria.

Usage

create_descriptor_condition(tag, type = NULL)

Arguments

Value

A named list with Tag and, when supplied, Type.

Examples

create_descriptor_condition("Brain", "InContainer")

# The match type is optional
create_descriptor_condition("Brain")

Description

Create an Event building block from named arguments. This is a thin factory around Event$new() that builds the raw list shape for you.

An Event is a discrete non-administration perturbation that fires at a specific simulation time (for example a meal, gallbladder emptying, or organ removal). PK-Sim creates events by cloning a named template and overriding parameters, so a template name is required.

Usage

create_event(name, template, parameters = NULL)

Arguments

Value

An Event object.

Examples

# Create a minimal event
event <- create_event(
  name = "Breakfast",
  template = "Meal: Standard (Human)"
)

# Create an event with parameter overrides
event <- create_event(
  name = "Breakfast",
  template = "Meal: Standard (Human)",
  parameters = list(
    create_parameter(name = "Meal energy content", value = 500, unit = "kcal"),
    create_parameter(name = "Meal volume", value = 0.3, unit = "l")
  )
)

Description

Build an EventSelection entry that references an Event building block by name and supplies a numeric start time (in hours) for the event inside the simulation.

Usage

create_event_selection(name, start_time)

Arguments

Value

An EventSelection object.

Examples

create_event_selection(name = "GB emptying", start_time = 12)

Description

Create an ExpressionProfile building block from named arguments. This is a thin factory around ExpressionProfile$new() that builds the raw list shape for you.

An ExpressionProfile's identity is the composite Molecule|Species|Category, so all three of molecule, species, and category are required.

Usage

create_expression_profile(
  molecule,
  species,
  category,
  type,
  localization = NULL,
  transport_type = NULL,
  ontogeny = NULL,
  parameters = NULL,
  expression = NULL,
  disease = NULL,
  description = NULL
)

Arguments

Value

An ExpressionProfile object.

Examples

# Create a minimal enzyme expression profile
profile <- create_expression_profile(
  molecule = "CYP3A4",
  species = "Human",
  category = "Healthy",
  type = "Enzyme"
)

# Create a transporter expression profile with ontogeny
profile <- create_expression_profile(
  molecule = "P-gp",
  species = "Human",
  category = "Healthy",
  type = "Transporter",
  transport_type = "Efflux",
  ontogeny = "P-gp"
)

# Create an enzyme profile with per-organ relative expression
profile <- create_expression_profile(
  molecule = "CYP3A4",
  species = "Human",
  category = "Healthy",
  type = "Enzyme",
  expression = data.frame(
    name = c("Liver", "Kidney"),
    value = c(1, 0.5)
  )
)

Description

Build a single FormulaUsablePath entry for the References of an observer's ExplicitFormula. A formula reference binds an alias used in the formula expression to a model path. This is a small builder that returns the raw named list; assemble several of them into a list for create_observer() or observer$formula_references.

Usage

create_formula_reference(alias, path, dimension = NULL)

Arguments

Value

A named list with Alias, Path, and, when supplied, Dimension.

Examples

create_formula_reference(
  "Conc_Br",
  "Organism|Brain|Plasma|Drug|Concentration"
)

# With an explicit dimension
create_formula_reference(
  "Conc_Br",
  "Organism|Brain|Plasma|Drug|Concentration",
  "Concentration (molar)"
)

Description

Create a new formulation with the specified properties. All arguments are optional except for name and type.

Usage

create_formulation(name, type, parameters = NULL)

Arguments

Value

A Formulation object

Weibull formulation parameters

• dissolution_time - Time to achieve 50% dissolution (numeric, default: 240)

• dissolution_time_unit - Unit for dissolution time (character, default: "min")

• lag_time - Lag time before dissolution starts (numeric, default: 0)

• lag_time_unit - Unit for lag time (character, default: "min")

• dissolution_shape - Dissolution shape parameter (numeric, default: 0.92)

• suspension - Whether to use as suspension (logical, default: TRUE)

Lint80 formulation parameters

• dissolution_time - Time to achieve 80% dissolution (numeric, default: 240)

• dissolution_time_unit - Unit for dissolution time (character, default: "min")

• lag_time - Lag time before dissolution starts (numeric, default: 0)

• lag_time_unit - Unit for lag time (character, default: "min")

• suspension - Whether to use as suspension (logical, default: TRUE)

Particle formulation parameters

• thickness - Thickness of unstirred water layer (numeric, default: 30)

• thickness_unit - Unit for thickness (character, default: "\u00b5m")

• distribution_type - Type of distribution, "mono" or "poly" (character, default: "mono")

• radius - Particle radius (mean or geometric mean) (numeric, default: 10)

• radius_unit - Unit for radius (character, default: "\u00b5m")

Parameters for polydisperse distribution (when distribution_type = "poly"):

• particle_size_distribution - "normal" or "lognormal" (character, default: "normal")

• radius_sd - Radius standard deviation, for normal distribution (numeric, default: 3)

• radius_sd_unit - Unit for radius SD (character, default: "\u00b5m")

• radius_cv - Coefficient of variation, for lognormal distribution (numeric, default: 1.5)

• radius_min - Minimum particle radius (numeric, default: 1)

• radius_min_unit - Unit for minimum radius (character, default: "\u00b5m")

• radius_max - Maximum particle radius (numeric, default: 19)

• radius_max_unit - Unit for maximum radius (character, default: "\u00b5m")

• n_bins - Number of bins (integer, default: 3)

Table formulation parameters

• tableX - Vector of time points for release profile in hours (numeric vector, required)

• tableY - Vector of fraction of dose at each time point (numeric vector, required)

• suspension - Whether to use as suspension (logical, default: TRUE)

ZeroOrder formulation parameters

• end_time - Time of administration end (numeric, default: 60)

• end_time_unit - Unit for end time (character, default: "min")

FirstOrder formulation parameters

• thalf - Half-life of the drug release (numeric, default: 0.01)

• thalf_unit - Unit for half-life (character, default: "min")

Examples

# Create a dissolved formulation (simplest type)
dissolved <- create_formulation(name = "Oral Solution", type = "Dissolved")

# Create a Weibull tablet formulation
tablet <- create_formulation(
  name = "Standard Tablet",
  type = "Weibull",
  parameters = list(
    dissolution_time = 60,
    dissolution_time_unit = "min",
    lag_time = 10,
    lag_time_unit = "min",
    dissolution_shape = 0.92,
    suspension = TRUE
  )
)

# Create a particle formulation with monodisperse distribution
particle <- create_formulation(
  name = "Suspension",
  type = "Particle",
  parameters = list(
    thickness = 25,
    thickness_unit = "µm",
    radius = 5,
    radius_unit = "µm"
  )
)

# Create a table formulation with custom release profile
custom <- create_formulation(
  name = "Custom Release",
  type = "Table",
  parameters = list(
    tableX = c(0, 0.5, 1, 2, 4, 8),
    tableY = c(0, 0.1, 0.3, 0.6, 0.9, 1.0),
    suspension = TRUE
  )
)

# Raw form: set an arbitrary parameter (with a ValueOrigin) on Dissolved
raw_dissolved <- create_formulation(
  name = "Suspension",
  type = "Dissolved",
  parameters = list(
    create_parameter(
      name = "Use as suspension",
      value = 1,
      source = "Lit",
      description = "Reference XYZ"
    )
  )
)

# Raw form on an unknown type carrying a custom TableFormula
custom_type <- create_formulation(
  name = "Novel",
  type = "Formulation_BrandNew",
  parameters = list(
    create_parameter(
      name = "Fraction (dose)",
      value = 0,
      table_points = list(list(x = 0, y = 0), list(x = 60, y = 1)),
      x_name = "Time",
      y_name = "Fraction",
      x_unit = "min",
      x_dimension = "Time",
      y_dimension = "Fraction"
    )
  )
)

Description

Build a FormulationSelection entry, used inside a ProtocolSelection to bind a formulation building block to one of the protocol's application slots.

Usage

create_formulation_selection(name, key)

Arguments

Value

A FormulationSelection object.

Examples

create_formulation_selection(name = "Oral solution", key = "Formulation")

Description

Create a new individual with the specified properties. All arguments are optional and will use default values if not provided.

Usage

create_individual(
  name = "New Individual",
  species = NULL,
  population = NULL,
  gender = NULL,
  age = NULL,
  weight = NULL,
  height = NULL,
  gestational_age = NULL,
  calculation_methods = NULL,
  disease_state = NULL,
  disease_state_parameters = NULL,
  seed = NULL,
  expression_profiles = NULL,
  description = NULL,
  parameters = NULL
)

Arguments

Value

An Individual object

See Also

age(), weight(), height(), gestational_age() for the demographic value-object helpers.

Examples

# Create a minimal individual
individual <- create_individual(name = "Test Individual")

# Create a complete individual
individual <- create_individual(
  name = "John Doe",
  species = "Human",
  population = "European_ICRP_2002",
  gender = "MALE",
  age = age(30),
  weight = weight(70),
  height = height(175)
)

# Create an individual with calculation methods
individual <- create_individual(
  name = "Test Individual",
  calculation_methods = c("Method 1", "Method 2", "Method 3")
)

# Create an individual with disease state (emitted as the modern
# `Disease` object: `OriginData$Disease = { Name, Parameters }`)
individual <- create_individual(
  name = "Patient",
  disease_state = "CKD",
  disease_state_parameters = list(
    list(Name = "eGFR", Value = 45.0, Unit = "ml/min/1.73m²")
  )
)

# Create an individual referencing expression profiles with a localized
# parameter and a description
individual <- create_individual(
  name = "Subject 1",
  expression_profiles = c("CYP3A4|Human|Healthy", "P-gp|Human|Healthy"),
  description = "Reference healthy adult",
  parameters = list(
    create_parameter(
      path = "Organism|Liver|EHC continuous fraction",
      value = 1
    )
  )
)

Description

Build a MoleculeList for an Observer, selecting which molecules the observer applies to. This is a small builder that returns the raw named list for create_observer() or observer$molecule_list.

Usage

create_molecule_list(for_all = NULL, include = NULL, exclude = NULL)

Arguments

Value

A named list with ForAll, MoleculeNamesToInclude, and MoleculeNamesToExclude for the arguments supplied (an empty named list when all are NULL).

Examples

create_molecule_list(for_all = FALSE, include = "Drug")

# Multiple names and an exclusion
create_molecule_list(include = c("Drug", "Metabolite"), exclude = "Water")

Description

Create an ospsuite::DataSet from named arguments. This is a thin factory around loadDataSetFromSnapshot() that builds the raw snapshot observed-data shape for you and converts it into a DataSet.

An observed data entry is the time + value (+ optional error) series attached to a snapshot. It is referenced by name from a Snapshot's simulations.

Usage

create_observed_data(
  name,
  time,
  values,
  error = NULL,
  molecular_weight = NULL,
  lloq = NULL,
  metadata = NULL
)

Arguments

Value

An ospsuite::DataSet object.

See Also

time(), values(), error() for the series value-object helpers.

Examples

# Create a minimal observed data set
obs <- create_observed_data(
  name = "Subject 001",
  time = time(c(0, 1, 2, 4, 8)),
  values = values(c(0, 12, 18, 11, 5), dimension = "Concentration (mass)")
)

# Create observed data with units and error
obs <- create_observed_data(
  name = "Subject 001",
  time = time(c(0, 1, 2, 4, 8), unit = "h"),
  values = values(
    c(0, 12, 18, 11, 5),
    unit = "mg/l",
    dimension = "Concentration (mass)"
  ),
  error = error(c(0, 1.2, 1.5, 1.1, 0.6), type = "ArithmeticStdDev")
)

Description

Create a single Observer from named arguments. This is a thin factory around Observer$new() that builds the raw list shape for you and composes with create_observer_set() via create_observer_set(observers = list(...)).

An observer is a simulation-time formula that computes a derived quantity from the underlying model (for example an amount observer or a container observer). It is not itself a building block; it lives inside an ObserverSet.

Usage

create_observer(
  name,
  type,
  dimension = NULL,
  formula = NULL,
  formula_references = NULL,
  container_criteria = NULL,
  molecule_list = NULL
)

Arguments

Value

An Observer object.

Examples

# Minimal amount observer
create_observer(name = "drug_amount", type = "Amount")

# Container observer with all sub-properties
obs <- create_observer(
  name = "brain_plasma_conc",
  type = "Container",
  dimension = "Concentration (molar)",
  formula = "Conc_Br",
  formula_references = list(
    create_formula_reference(
      "Conc_Br",
      "Organism|Brain|Plasma|Drug|Concentration"
    )
  ),
  container_criteria = list(
    create_descriptor_condition("Brain", "InContainer")
  ),
  molecule_list = create_molecule_list(for_all = FALSE, include = "Drug")
)

# Compose into an observer set
create_observer_set(name = "BrainPlasmaConcentration", observers = list(obs))

Description

Create an ObserverSet building block from named arguments. This is a thin factory around ObserverSet$new() that builds the raw list shape for you.

An ObserverSet bundles a collection of Observer objects (each one a simulation-time formula that computes a derived quantity from the underlying model) so a simulation can reference the whole bundle by name.

Usage

create_observer_set(name, observers = NULL)

Arguments

Value

An ObserverSet object.

Examples

# Create an empty observer set
empty_set <- create_observer_set(name = "BrainPlasmaConcentration")

# Create an observer set from raw observer lists
raw_set <- create_observer_set(
  name = "BrainPlasmaConcentration",
  observers = list(
    list(
      Name = "brain_plasma_conc",
      Type = "Container",
      Dimension = "Concentration (molar)",
      Formula = list(Formula = "Conc_Br")
    )
  )
)

# Create an observer set from Observer R6 objects
observer <- Observer$new(list(
  Name = "brain_plasma_conc",
  Type = "Container",
  Dimension = "Concentration (molar)",
  Formula = list(Formula = "Conc_Br")
))
observer_set <- create_observer_set(
  name = "BrainPlasmaConcentration",
  observers = list(observer)
)

Description

Build an ObserverSetSelection entry that references an ObserverSet building block by name inside a Simulation.

Usage

create_observer_set_selection(name)

Arguments

Value

An ObserverSetSelection object.

Examples

create_observer_set_selection(name = "BrainPlasmaConcentration")

Description

Build an OutputInterval entry, used inside an OutputSchema to record one time window of output reporting (start time, end time, resolution). All three time parameters are required; PK-Sim's default units ("h" for times and "pts/h" for resolution) are used.

Usage

create_output_interval(name = NULL, start_time, end_time, resolution)

Arguments

Value

An OutputInterval object.

Examples

create_output_interval(start_time = 0, end_time = 24, resolution = 20)

Description

Build an OutputMapping entry, used inside a Simulation to link a simulation output quantity to an observed-data set for downstream comparison and parameter identification.

All arguments are optional and serialized only when supplied.

Usage

create_output_mapping(
  path = NULL,
  observed_data = NULL,
  scaling = NULL,
  weight = NULL,
  weights = NULL
)

Arguments

Value

An OutputMapping object.

Examples

create_output_mapping(
  path = "Organism|PeripheralVenousBlood|Drug|Plasma",
  observed_data = "Study A",
  scaling = "Log",
  weight = 1
)

Description

Build an OutputSchema from a list of OutputInterval objects.

Usage

create_output_schema(intervals = list())

Arguments

Value

An OutputSchema object.

Examples

create_output_schema(
  intervals = list(
    create_output_interval(start_time = 0, end_time = 2, resolution = 20),
    create_output_interval(start_time = 2, end_time = 24, resolution = 20)
  )
)

Description

Create a new parameter with the specified properties. All arguments except name and value are optional.

Returns a LocalizedParameter when a non-NULL path is supplied (i.e. the parameter is identified by its position within a target's parameter tree); otherwise returns a plain Parameter.

Usage

create_parameter(
  name,
  value,
  path = NULL,
  unit = NULL,
  source = NULL,
  description = NULL,
  source_id = NULL,
  source_method = NULL,
  table_formula = NULL,
  table_points = NULL,
  x_name = NULL,
  y_name = NULL,
  x_unit = NULL,
  x_dimension = NULL,
  y_dimension = NULL
)

Arguments

Value

A Parameter object, or a LocalizedParameter when path is supplied.

Data shape

Plain Parameter objects carry the identifier in data$Name, matching the JSON shape used by Parameter slots in Compound, Formulation, Protocol, and Event (per snapshot-spec.md). LocalizedParameter objects carry the identifier in data$Path. The factory writes whichever field matches the returned class so the raw data shape reflects the kind of parameter unambiguously.

Examples

# Create a basic parameter
param <- create_parameter(
  name = "Organism|Liver|Volume",
  value = 1.5
)

# Create a parameter with unit
param <- create_parameter(
  name = "Organism|Liver|Volume",
  value = 1.5,
  unit = "L"
)

# Create a parameter with value origin
param <- create_parameter(
  name = "Organism|Liver|Volume",
  value = 1.5,
  unit = "L",
  source = "Publication",
  description = "Reference XYZ",
  source_method = "ParameterIdentification"
)

# Create a localized parameter (path-bearing)
localized <- create_parameter(
  path = "Organism|Liver|Volume",
  value = 1.5,
  unit = "L"
)

# Create a table parameter
param <- create_parameter(
  name = "Fraction (dose)",
  value = 0.0,
  table_points = list(
    list(x = 0.0, y = 0.0),
    list(x = 1.0, y = 0.5),
    list(x = 2.0, y = 0.8),
    list(x = 4.0, y = 1.0)
  ),
  x_name = "Time",
  y_name = "Fraction (dose)",
  x_unit = "h",
  x_dimension = "Time",
  y_dimension = "Dimensionless"
)

Description

Create a Population building block from named arguments. This is a thin factory around Population$new() that builds the raw Settings shape for you.

A Population is a recipe for generating subjects: it owns the settings PK-Sim uses to sample a cohort at simulation time. Subjects themselves are not stored in the snapshot.

Usage

create_population(
  name,
  number_of_individuals,
  proportion_of_females = 50,
  individual_name = NULL,
  species = NULL,
  source_population = NULL,
  age_range = NULL,
  weight_range = NULL,
  height_range = NULL,
  bmi_range = NULL,
  seed = NULL,
  advanced_parameters = NULL,
  description = NULL,
  gestational_age_range = NULL,
  disease_state_parameters = NULL,
  individual = NULL
)

Arguments

Value

A Population object.

Examples

# Create a minimal population
pop <- create_population(
  name = "Adults",
  number_of_individuals = 100
)

# Create a population with demographic ranges
pop <- create_population(
  name = "Healthy Adults",
  number_of_individuals = 50,
  proportion_of_females = 50,
  species = "Human",
  source_population = "European_ICRP_2002",
  age_range = range(20, 60, "year(s)"),
  weight_range = range(50, 90, "kg")
)

# Compose a base individual and set a disease-state parameter
pop <- create_population(
  name = "Renal Impairment",
  number_of_individuals = 25,
  individual = create_individual(
    name = "Base",
    species = "Human",
    population = "European_ICRP_2002",
    gender = "MALE"
  ),
  gestational_age_range = range(37, 42, "week(s)"),
  disease_state_parameters = list(
    eGFR = range(60, 120, "ml/min/1.73m²")
  ),
  description = "Adults with reduced renal function"
)

Description

Create a Process (a PK-Sim CompoundProcess) from named arguments. This is a thin factory around Process$new() that builds the raw list shape for you.

For richer process structures (such as parameters with full value origins), build the raw list directly or load a snapshot and copy the relevant entry.

Usage

create_process(
  internal_name,
  data_source,
  molecule = NULL,
  metabolite = NULL,
  species = NULL,
  parameters = NULL
)

Arguments

Value

A Process object.

Examples

# Minimal protein-binding process
p <- create_process(
  internal_name = "SpecificBinding",
  data_source = "Publication X",
  molecule = "Albumin"
)

# Metabolizing enzyme with a parameter
p <- create_process(
  internal_name = "MetabolizationSpecific_MM",
  data_source = "Optimized",
  molecule = "CYP3A4",
  metabolite = "Hydroxy-Drug",
  parameters = list(
    create_parameter(name = "Km", value = 1.2, unit = "µmol/l")
  )
)

Description

Create a Protocol building block from named arguments. This is a thin factory around Protocol$new() that builds the raw list shape for you.

By default this creates a Simple Protocol with a single application type and dosing interval. To create an Advanced Protocol pass a list of schemas via schemas instead of application_type and dosing_interval.

Usage

create_protocol(
  name,
  application_type = NULL,
  dosing_interval = NULL,
  target_organ = NULL,
  target_compartment = NULL,
  parameters = NULL,
  schemas = NULL,
  time_unit = NULL,
  dose = NULL,
  dose_unit = "mg",
  start_time = NULL,
  start_time_unit = "h",
  end_time = NULL
)

Arguments

Value

A Protocol object.

Examples

# Create a simple oral protocol with one dose via promoted arguments
protocol <- create_protocol(
  name = "Single dose 10mg",
  application_type = "Oral",
  dosing_interval = "Single",
  dose = 10,
  dose_unit = "mg",
  start_time = 0
)

# The same protocol via the free-form `parameters` escape hatch
protocol <- create_protocol(
  name = "Single dose 10mg",
  application_type = "Oral",
  dosing_interval = "Single",
  parameters = list(
    create_parameter(name = "Start time", value = 0, unit = "h"),
    create_parameter(name = "InputDose", value = 10, unit = "mg")
  )
)

# Create a twice-daily intravenous protocol
protocol <- create_protocol(
  name = "BID IV",
  application_type = "IntravenousBolus",
  dosing_interval = "DI_12_12",
  parameters = list(
    create_parameter(name = "InputDose", value = 5, unit = "mg")
  )
)

# Create an Advanced Protocol from Schema objects
protocol <- create_protocol(
  name = "Advanced",
  schemas = list(
    create_schema(
      name = "Schema 1",
      parameters = list(
        create_parameter(name = "NumberOfRepetitions", value = 1)
      ),
      items = list(
        create_schema_item(
          name = "Item 1",
          application_type = "Oral",
          parameters = list(
            create_parameter(name = "InputDose", value = 5, unit = "mg")
          )
        )
      )
    )
  ),
  time_unit = "h"
)

Description

Build a ProtocolSelection entry, used inside a CompoundProperties to assign a Protocol building block to the compound and (optionally) map each application slot to a Formulation via FormulationSelection.

Usage

create_protocol_selection(name, formulations = NULL)

Arguments

Value

A ProtocolSelection object.

Examples

create_protocol_selection(
  name = "Yu 2004 - Rifampicin - 600 mg MD OD 10 days",
  formulations = list(
    create_formulation_selection(name = "Oral solution", key = "Formulation")
  )
)

Description

Create a Schema for an Advanced Protocol from named arguments. This is a thin factory around Schema$new() that builds the raw list shape for you.

A schema is a repeatable block inside an Advanced Protocol: it has a name, schema-level parameters (typically NumberOfRepetitions, TimeBetweenRepetitions, and ⁠Start time⁠), and an ordered list of SchemaItem applications. The three repetition parameters are available as the plain, unit-aware arguments number_of_repetitions, time_between_repetitions, and start_time; anything else is supplied through the parameters escape hatch.

Usage

create_schema(
  name,
  parameters = NULL,
  items = NULL,
  number_of_repetitions = NULL,
  time_between_repetitions = NULL,
  time_between_repetitions_unit = "h",
  start_time = NULL,
  start_time_unit = "h"
)

Arguments

Value

A Schema object.

Examples

# A schema using the promoted repetition arguments
schema <- create_schema(
  name = "Schema 1",
  number_of_repetitions = 3,
  time_between_repetitions = 24,
  start_time = 0
)

# A once-daily schema with a single oral application, using the
# `parameters` escape hatch for the schema-level parameters
schema <- create_schema(
  name = "Schema 1",
  parameters = list(
    create_parameter(name = "NumberOfRepetitions", value = 1),
    create_parameter(name = "TimeBetweenRepetitions", value = 0, unit = "h")
  ),
  items = list(
    create_schema_item(
      name = "Item 1",
      application_type = "Oral",
      parameters = list(
        create_parameter(name = "InputDose", value = 5, unit = "mg")
      )
    )
  )
)

Description

Create a SchemaItem for an Advanced Protocol from named arguments. This is a thin factory around SchemaItem$new() that builds the raw list shape for you.

A schema item is one application inside a Schema of an Advanced Protocol. It carries an application type, an optional formulation key, target organ and compartment, and the application-level parameters (dose, start time, ...).

Usage

create_schema_item(
  name,
  application_type,
  formulation_key = NULL,
  target_organ = NULL,
  target_compartment = NULL,
  parameters = NULL,
  dose = NULL,
  dose_unit = "mg",
  start_time = NULL,
  start_time_unit = "h"
)

Arguments

Value

A SchemaItem object.

Examples

# An oral schema item using the promoted dose and start-time arguments
item <- create_schema_item(
  name = "Item 1",
  application_type = "Oral",
  dose = 10,
  dose_unit = "mg",
  start_time = 0
)

# The same, authored through the free-form `parameters` escape hatch
item <- create_schema_item(
  name = "Item 1",
  application_type = "Oral",
  parameters = list(
    create_parameter(name = "Start time", value = 0, unit = "h"),
    create_parameter(name = "InputDose", value = 10, unit = "mg")
  )
)

# A user-defined schema item targeting the venous blood plasma
item <- create_schema_item(
  name = "User defined",
  application_type = "UserDefined",
  target_organ = "VenousBlood",
  target_compartment = "Plasma",
  dose = 5
)

Description

Create an in-memory Snapshot from scratch, carrying the current supported PK-Sim version and no building blocks. This is the snapshot-level constructor that pairs with load_snapshot() and export_snapshot(): rather than loading an existing project, it starts an empty one you can then populate.

The result touches no files and has no path. Mutate it with the ⁠add_*()⁠ verbs (for example add_compound()) and serialize it with export_snapshot().

Usage

create_snapshot(name = NULL, description = NULL)

Arguments

Value

A Snapshot object.

See Also

load_snapshot(), export_snapshot()

Examples

# An empty snapshot
snapshot <- create_snapshot()

# A named and described snapshot
snapshot <- create_snapshot(name = "My Project", description = "Notes")

# Populate it with a building block
snapshot <- add_compound(create_snapshot(), create_compound(name = "Drug X"))

Description

Build a SolverSettings object, used inside a Simulation. All arguments are optional; absent fields fall back to PK-Sim solver defaults at load time.

Usage

create_solver_settings(
  abs_tol = NULL,
  rel_tol = NULL,
  use_jacobian = NULL,
  h0 = NULL,
  h_min = NULL,
  h_max = NULL,
  mx_step = NULL
)

Arguments

Value

A SolverSettings object.

Examples

create_solver_settings()

create_solver_settings(abs_tol = 1e-9, rel_tol = 1e-9, mx_step = 100000)

Description

Build an error-series value object for create_observed_data()'s error argument. Carries the error y-values, an optional unit, and an auxiliary type.

The unit is not validated here: the error dimension is the values-series dimension, which this helper does not see. create_observed_data() validates the error unit against the values dimension when a unit is present, and defaults the error unit to the values unit when unit is NULL.

Usage

error(value, unit = NULL, type = "ArithmeticStdDev")

Arguments

Value

An error_spec object to pass to create_observed_data().

See Also

create_observed_data()

Other value-object helpers: age(), fraction_unbound(), gestational_age(), height(), intestinal_permeability(), lipophilicity(), permeability(), solubility(), time(), values(), weight()

Examples

error(c(0, 1.2, 1.5, 1.1, 0.6))

Description

An R6 class that represents an event in an OSP snapshot. This class provides methods to access different properties of an event and display a summary of its information.

Active bindings

Methods

Public methods

• Event$new()

• Event$print()

• Event$to_dataframe()

• Event$clone()

Event$new()

Create a new Event object

Usage

Event$new(data)

Arguments

Returns

A new Event object

Event$print()

Print a summary of the event

Usage

Event$print(...)

Arguments

Returns

Invisibly returns the object

Event$to_dataframe()

Convert the event to a data frame for easier manipulation

Usage

Event$to_dataframe()

Returns

A tibble with event information

Event$clone()

The objects of this class are cloneable with this method.

Usage

Event$clone(deep = FALSE)

Arguments

Description

An R6 class representing one entry in a Simulation's Events array. Resolves to an Event building block by name and carries the simulation-local StartTime Parameter used by the event.

Active bindings

Methods

Public methods

• EventSelection$new()

• EventSelection$clone()

EventSelection$new()

Create a new EventSelection object.

Usage

EventSelection$new(data)

Arguments

Returns

A new EventSelection object.

EventSelection$clone()

The objects of this class are cloneable with this method.

Usage

EventSelection$clone(deep = FALSE)

Arguments

Description

Export a Snapshot object to a JSON file. This is a convenient wrapper around the ⁠$export()⁠ method of the Snapshot class.

Usage

export_snapshot(snapshot, path)

Arguments

Value

Invisibly returns the snapshot object

Examples

## Not run: 
# Load a snapshot
snapshot <- load_snapshot("path/to/snapshot.json")

# Export to a new file
export_snapshot(snapshot, "path/to/exported_snapshot.json")

## End(Not run)

Description

An R6 class that represents an expression profile in an OSP snapshot. This class provides methods to access different properties of an expression profile and display a summary of its information.

Active bindings

Methods

Public methods

• ExpressionProfile$new()

• ExpressionProfile$print()

• ExpressionProfile$to_df()

• ExpressionProfile$clone()

ExpressionProfile$new()

Create a new ExpressionProfile object

Usage

ExpressionProfile$new(data)

Arguments

Returns

A new ExpressionProfile object

ExpressionProfile$print()

Print a summary of the expression profile

Usage

ExpressionProfile$print(...)

Arguments

Returns

Invisibly returns the object

ExpressionProfile$to_df()

Convert the expression profile to data frames for easier manipulation

Usage

ExpressionProfile$to_df()

Returns

A list with basic information and parameters as tibbles

ExpressionProfile$clone()

The objects of this class are cloneable with this method.

Usage

ExpressionProfile$clone(deep = FALSE)

Arguments

Description

An R6 class that represents a formulation in an OSP snapshot. This class provides methods to access different properties of a formulation and display a summary of its information.

Active bindings

Methods

Public methods

• Formulation$new()

• Formulation$print()

• Formulation$to_df()

• Formulation$get_human_formulation_type()

• Formulation$clone()

Formulation$new()

Create a new Formulation object

Usage

Formulation$new(data)

Arguments

Returns

A new Formulation object

Formulation$print()

Print a summary of the formulation including its properties and parameters.

Usage

Formulation$print(...)

Arguments

Returns

Invisibly returns the Formulation object for method chaining

Formulation$to_df()

Convert formulation data to tibbles

Usage

Formulation$to_df(type = "all")

Arguments

Returns

A list of tibbles containing the requested data:

• formulations: Basic formulation information (ID, name, type)

• formulations_parameters: All parameters including table parameter points

The formulations_parameters tibble includes the following columns:

• formulation_id: ID of the formulation

• name: Name of the parameter

• value: Value of the parameter (NA for table points)

• unit: Unit of the parameter (NA for table points)

• is_table_point: TRUE for table parameter points, FALSE for regular parameters

• x_value: X-axis value for table points (NA for regular parameters)

• y_value: Y-axis value for table points (NA for regular parameters)

• table_name: Name of the table (usually "Time" for release profiles)

• source: Source of the parameter (NA if not available)

• description: Description of the parameter (NA if not available)

• source_id: ID of the source (NA if not available)

Formulation$get_human_formulation_type()

Get human-readable formulation type

Usage

Formulation$get_human_formulation_type()

Returns

Character string with human-readable formulation type

Formulation$clone()

The objects of this class are cloneable with this method.

Usage

Formulation$clone(deep = FALSE)

Arguments

Description

An R6 class representing one entry in a ProtocolSelection's Formulations array. Each entry maps a formulation building-block name to a formulation key used by an application within the protocol.

Active bindings

Methods

Public methods

• FormulationSelection$new()

• FormulationSelection$clone()

FormulationSelection$new()

Create a new FormulationSelection object.

Usage

FormulationSelection$new(data)

Arguments

Returns

A new FormulationSelection object.

FormulationSelection$clone()

The objects of this class are cloneable with this method.

Usage

FormulationSelection$clone(deep = FALSE)

Arguments

Description

Build a fraction-unbound value object for create_compound()'s fraction_unbound argument (or the writable Compound$fraction_unbound field). Produces one default FractionUnbound alternative with parameter "Fraction unbound (plasma, reference value)". Fraction unbound stores a bare value with no unit, so this helper takes no unit argument.

Fraction unbound is the one species-dependent single-parameter group, so the emitted alternative carries a Species field (see species), which PK-Sim requires to load the snapshot.

Usage

fraction_unbound(
  value,
  name = "User defined",
  default = FALSE,
  species = "Human"
)

Arguments

Value

A fraction_unbound_spec object to pass to create_compound().

See Also

create_compound()

Other value-object helpers: age(), error(), gestational_age(), height(), intestinal_permeability(), lipophilicity(), permeability(), solubility(), time(), values(), weight()

Examples

fraction_unbound(0.1)
create_compound(name = "Drug X", fraction_unbound = fraction_unbound(0.1))

# Several alternatives, the second marked as the default
create_compound(
  name = "Drug X",
  fraction_unbound = list(
    fraction_unbound(0.1, name = "Plasma"),
    fraction_unbound(0.2, name = "Microsomal", default = TRUE)
  )
)

Description

Build a gestational-age value object for create_individual()'s gestational_age argument (or the writable Individual$gestational_age / OriginData$gestational_age field). Fills the OriginData GestationalAge characteristic (list(Value =, Unit =)).

Usage

gestational_age(value, unit = "week(s)")

Arguments

Value

A gestational_age_spec object to pass to create_individual().

See Also

create_individual()

Other value-object helpers: age(), error(), fraction_unbound(), height(), intestinal_permeability(), lipophilicity(), permeability(), solubility(), time(), values(), weight()

Examples

gestational_age(38)
create_individual(name = "Preterm", gestational_age = gestational_age(30))

Description

Thin wrapper around as_tibbles() with kind = "compounds". Prefer as_tibbles() in new code.

Usage

get_compounds_dfs(snapshot)

Arguments

Value

A list with properties and processes tibbles; see as_tibbles() for the column contract.

Examples

## Not run: 
snapshot <- load_snapshot("path/to/snapshot.json")
dfs <- get_compounds_dfs(snapshot)
dfs$properties
dfs$processes

## End(Not run)

Description

Returns the name of the default alternative in a compound physicochemical-property group, for example the Solubility, Lipophilicity, or FractionUnbound field of a Compound. The default is the alternative whose IsDefault flag is TRUE (an absent flag is treated as TRUE, per the snapshot schema); when no alternative sets it, the "User defined" alternative is used, and a group with no resolvable default returns NULL.

Usage

get_default_alternative(alternatives)

Arguments

Value

The default alternative's name as a character string, or NULL when the group has no resolvable default.

Examples

compound <- create_compound(
  name = "Drug X",
  solubility = list(
    solubility(9999, name = "Aqueous"),
    solubility(200, name = "FaSSIF", default = TRUE)
  )
)
get_default_alternative(compound$solubility)

Description

Thin wrapper around as_tibbles() with kind = "events". Prefer as_tibbles() in new code.

Usage

get_events_dfs(snapshot)

Arguments

Value

A list with events and events_parameters tibbles.

Examples

## Not run: 
snapshot <- load_snapshot("path/to/snapshot.json")
dfs <- get_events_dfs(snapshot)

## End(Not run)

Description

Thin wrapper around as_tibbles() with kind = "expression_profiles". Prefer as_tibbles() in new code.

Usage

get_expression_profiles_dfs(snapshot)

Arguments

Value

A list with expression_profiles and expression_profiles_parameters tibbles.

Examples

## Not run: 
snapshot <- load_snapshot("path/to/snapshot.json")
dfs <- get_expression_profiles_dfs(snapshot)

## End(Not run)

Description

Thin wrapper around as_tibbles() with kind = "formulations". Prefer as_tibbles() in new code.

Usage

get_formulations_dfs(snapshot)

Arguments

Value

A list with formulations and formulations_parameters tibbles. Table parameter points have is_table_point = TRUE and carry x_value, y_value, and table_name.

Examples

## Not run: 
snapshot <- load_snapshot("path/to/snapshot.json")
dfs <- get_formulations_dfs(snapshot)

## End(Not run)

Description

Thin wrapper around as_tibbles() with kind = "individuals". Prefer as_tibbles() in new code.

Usage

get_individuals_dfs(snapshot)

Arguments

Value

A list with individuals, individuals_parameters, and individuals_expressions tibbles.

Examples

## Not run: 
snapshot <- load_snapshot("path/to/snapshot.json")
dfs <- get_individuals_dfs(snapshot)

## End(Not run)

Description

Thin wrapper around as_tibbles() with kind = "observed_data". Prefer as_tibbles() in new code.

Usage

get_observed_data_dfs(snapshot)

Arguments

Value

A tibble in long format with columns name, xValues, yValues, yErrorValues, xDimension, xUnit, yDimension, yUnit, yErrorType, yErrorUnit, molWeight, lloq.

Examples

## Not run: 
snapshot <- load_snapshot("path/to/snapshot.json")
observed_data_df <- get_observed_data_dfs(snapshot)

## End(Not run)

Description

Thin wrapper around as_tibbles() with kind = "observer_sets". Prefer as_tibbles() in new code.

Usage

get_observer_sets_dfs(snapshot)

Arguments

Value

A list with two tibbles. observer_sets has one row per ObserverSet with columns observer_set_id, name, n_observers. observers has one row per Observer with columns observer_set_id, observer_set_name, name, type, dimension, formula_expression, formula_dimension, formula_references, container_tags; rows join back to their parent ObserverSet by observer_set_id or observer_set_name. formula_references flattens the underlying ExplicitFormula references to "alias=path" pairs joined with |.

Examples

## Not run: 
snapshot <- load_snapshot("path/to/snapshot.json")
observer_sets_df <- get_observer_sets_dfs(snapshot)

## End(Not run)

Description

Thin wrapper around as_tibbles() with kind = "populations". Prefer as_tibbles() in new code.

Usage

get_populations_dfs(snapshot)

Arguments

Value

A list with populations and populations_parameters tibbles.

Examples

## Not run: 
snapshot <- load_snapshot("path/to/snapshot.json")
dfs <- get_populations_dfs(snapshot)

## End(Not run)

Description

Thin wrapper around as_tibbles() with kind = "protocols". Prefer as_tibbles() in new code.

Usage

get_protocols_dfs(snapshot)

Arguments

Value

A tibble with one row per protocol parameter (or per schema item parameter for advanced protocols).

Examples

## Not run: 
snapshot <- load_snapshot("path/to/snapshot.json")
protocols_df <- get_protocols_dfs(snapshot)

## End(Not run)

Description

Build a height value object for create_individual()'s height argument (or the writable Individual$height / OriginData$height field). Fills the OriginData Height characteristic (list(Value =, Unit =)).

Usage

height(value, unit = "cm")

Arguments

Value

A height_spec object to pass to create_individual().

See Also

create_individual()

Other value-object helpers: age(), error(), fraction_unbound(), gestational_age(), intestinal_permeability(), lipophilicity(), permeability(), solubility(), time(), values(), weight()

Examples

height(175)
create_individual(name = "Subject", height = height(175))

Description

An R6 class that represents an individual in an OSP snapshot. This class provides methods to access different properties of an individual and display a summary of its information.

Active bindings

Methods

Public methods

• Individual$new()

• Individual$print()

• Individual$to_df()

• Individual$clone()

Individual$new()

Create a new Individual object

Usage

Individual$new(data)

Arguments

Returns

A new Individual object

Individual$print()

Print a summary of the individual including its properties and parameters.

Usage

Individual$print(...)

Arguments

Returns

Invisibly returns the Individual object for method chaining

Individual$to_df()

Convert individual data to tibbles

Usage

Individual$to_df(type = "all")

Arguments

Returns

A list of tibbles containing the requested data

Individual$clone()

The objects of this class are cloneable with this method.

Usage

Individual$clone(deep = FALSE)

Arguments

Description

Build an intestinal-permeability value object for create_compound()'s intestinal_permeability argument (or the writable Compound$intestinal_permeability field). Produces one default IntestinalPermeability alternative with parameter "Specific intestinal permeability (transcellular)".

Usage

intestinal_permeability(
  value,
  unit = "cm/min",
  name = "User defined",
  default = FALSE
)

Arguments

Value

An intestinal_permeability_spec object to pass to create_compound().

See Also

create_compound()

Other value-object helpers: age(), error(), fraction_unbound(), gestational_age(), height(), lipophilicity(), permeability(), solubility(), time(), values(), weight()

Examples

intestinal_permeability(1.14e-05)
create_compound(
  name = "Drug X",
  intestinal_permeability = intestinal_permeability(1.14e-05)
)

# Several alternatives, the second marked as the default
create_compound(
  name = "Drug X",
  intestinal_permeability = list(
    intestinal_permeability(1.14e-05, name = "Caco-2"),
    intestinal_permeability(2e-05, name = "PAMPA", default = TRUE)
  )
)