set_transfer: Set transfer events

In cvasi: Calibration, Validation, and Simulation of TKTD Models

Set transfer events

Description

A transfer refers to an event where a certain amount of biomass is moved to a new medium after a period of time. Effectively, this resets the scenario's state variable representing biomass and re-scales all state variables which are correlated with biomass, such as adsorbed chemical mass. This feature replicates a procedure occurring e.g. in Lemna effect studies and may be necessary to recreate study results.

Usage

set_transfer(x, interval, times, biomass, scaled_comp)

## S4 method for signature 'ANY'
set_transfer(x, interval, times, biomass, scaled_comp)

## S4 method for signature 'Transferable'
set_transfer(x, interval, times, biomass, scaled_comp)

set_notransfer(x)

Arguments

x	vector of EffectScenario objects
interval	optional numeric, interval in time units of the scenario, set to -1 to disable transfers.
times	optional numeric vector of time points where transfers occur
biomass	optional numeric vector, amount of biomass that is being transferred at each transfer
scaled_comp	optional character vector of affected compartments that are scaled according to new biomass levels

Details

If a transfer occurs, simulation results of that time point will report the model state before the transfer. Be aware that if transfers are defined using the interval argument, the transfers will always occur relative to time point zero (t = 0). As an example, setting a regular transfer of seven days, interval = 7, will result at transfers occurring at time points which are integer multiplicates of seven, such as t=0, t=7, t=14 and so forth. The starting and end times of a scenario do not influece when a regular transfer occurs, only if it occurs.

Transferred biomass

At each transfer, a defined amount of biomass is transferred to a new medium. This is modeled by interrupting the simulation at a transfer time point, modifying the biomass level BM, and scaling affected compartments according to new biomass levels. Scaling of compartments depending on biomass, such as internal toxicant mass, is necessary to correctly reflect mass balances and concentrations over time.

Transferred biomass is set using the biomass parameter. Is is either a single numerical value in which case the same biomass level is set at each transfer. Or it is a vector of numerical values with the same length as the times parameter in which case a custom biomass level can be set for each transfer. Multiple biomass levels can only be set in conjunction with custom transfer time points.

Some scenario types define default values for transferred biomass based on common study set ups.

Regular and custom transfer time points

Transfers can occur either in regular intervals of time or at selected, custom time points. For regular intervals, the parameter interval is set to a single numeric value which has the same unit as the scenario's time dimension. As an example: if a scenario uses the unit of days for time, the transfer interval is also specified in days:

Transfers occurring at custom time points are set by passing a numerical vector to the parameter times. The time points' units must match with the unit of time in the scenario. A custom transfer time point must not occur at the starting time point of a simulation.

Affected compartments

Some compartments depend on biomass to correctly reflect mass balances and concentrations over time, such as internal toxicant mass. These compartments need to be scaled linearly to reflect the change in biomass levels. The parameter scaled_comp accepts a character vector of compartment names which are scaled at each transfer. This parameter should only be used with custom, user-defined models. If no compartment needs to be scaled, set or use the default value of character(0).

Value

Modified scenario objects

Functions

• set_notransfer(): Disable biomass transfers

See Also

Lemna-models

Examples

# Simulate biomass transfer of 50 *g/m²* at a regular interval of 7 *days*
metsulfuron %>%
  set_transfer(interval=7, biomass=50) %>%
  simulate()

# Simulate irregular biomass transfers occuring at days 5, 10, and 12
metsulfuron %>%
  set_transfer(times=c(5, 10, 12), biomass=50) %>%
  simulate()

# Simulate irregular transfers with changing amounts of transferred biomass
metsulfuron %>%
  set_transfer(times=c(5, 10, 12), biomass=c(50, 20, 10)) %>%
  simulate()

# Disable all biomass transfers
metsulfuron %>%
  set_notransfer() %>%
  simulate()

cvasi documentation built on Sept. 11, 2025, 5:11 p.m.