definePopulationElement
[Simulx] Define population element
Define or edit an element of population parameters. Population parameter elements are defined and used for simulation as in Simulx GUI. As for other elements, the population parameters elements can be defined or imported, and they are saved with the Simulx project if calling saveProject
. Once a population parameters element is defined, it needs to be added to a simulation group with setGroupElement
to be used in simulation.
Usage
definePopulationElement(name, element)
Arguments
- name
(character) Element name.
- element
(character or dataFrame or list) Element definition from external file path or data frame with population parameters as columns, or list to select the sheet of an excel file:
file
(character) Path to the population file.sheet
(character) Name of the sheet in xlsx/xls file.
Details
Definition of population parameters as simulation elements allows to simulate individual parameters from probability distributions. It is possible only if the model includes a block [INDIVIDUAL] to consider the inter-individual variability.
A population parameters element can be defined as an external file (csv, xlsx, xlsx, sas7bdat, xpt or txt) or as a data frame. In any case, it should contain one column per population parameter (mandatory).
To check exactly which column names to use, you can use getPopulationElements
and view the population parameters element that was automatically created after defining the model (if the model has an [INDIVIDUAL] block).
To define a population parameters element with several lines, with several sets to be used in different replicate simulations, an external file is required. In this case, you should also set the number of replicates for your simulation with setNbReplicates
, otherwise only the first set of population parameters will be taken into account. Each replicate uses one set of population parameters with the order of the appearance in the table.
Note: It is not possible to define population elements with distributions with the connectors as in the GUI. To do this, please sample values from distributions in R and create the element with different rows as in the last example below.
See also
Examples
if (FALSE) {
definePopulationElement(name = "name", element = "file/path")
definePopulationElement(name = "name", element = list(file = "file/path", sheet = "sheet_name"))
definePopulationElement(name = "name", element = data.frame(Cl_pop = 1, V_pop = 2.5))
}
# Define a pop param element with a data frame
loadProject(file.path(getDemoPath(),"3.definition","3.3.population_parameters","pop_parameters_manual.smlx"))
# get the existing pop param element as an example
ExamplePopParamData = getPopulationElements()$manual_parameters$data
ExamplePopParamData[] = rep(1,11) #set the desired values, for simplicity we use all param =1
definePopulationElement(name = "PopParam", element = ExamplePopParamData)
# Check impact of varying ka with replicates (external file required)
loadProject(file.path(getDemoPath(),"3.definition","3.3.population_parameters","pop_parameters_manual.smlx"))
# get the existing pop param element as an example:
ExamplePopParamData = getPopulationElements()$manual_parameters$data
# add lines to the data frame to have different values for ka:
PopParamReplicates = ExamplePopParamData[rep(1,10),]
PopParamReplicates$ka_pop = rnorm(10,mean = 0.8, sd = 0.1)
# write the table to an external file (required because it has several lines):
file_name = tempfile("PopParamReplicates.csv")
write.csv(PopParamReplicates, file_name, row.names = FALSE)
# define the new element and use it in simulation:
definePopulationElement(name = "PopParamReplicates", element = file_name)
setGroupElement(group = "simulationGroup1", elements = "PopParamReplicates")
setNbReplicates(nb = 10) # to simulate the project 10x, each time with a different population parameter element
runSimulation()
if (FALSE) getSimulationResults()