Writing a Tucuxi drug model

This chapter presents the way medical drugs have to be described. Tucuxi is flexible in terms of handling various medical drugs (or substances). The drugs are defined within XML files, and can be edited thanks to the special Tucuxi drug editor which can be found at this address: http://www.tucuxi.ch/drugs/editor/index.html .

Tucuxi Drug File Editor

Two options are possible to write your drug model. You can start from a template by choosing the number of compartments, the way the drug is given from the drop-down menu and load it. Or, if you want to work from an existing drug file you can upload it.

During editing, some warnings are displayed. One of your goals is to end up without any warning.

The function Check file allows you to verify if the drug file loaded will work fine in Tucuxi. If everything is good in the file, the message “The file seems valid. You can try it in Tucuxi” is displayed in green. If it’s not the case, the description of the error reported appears in red. Some checks are automatically performed on your model, but everything can not be automated. For instance if there are syntactic issues within an apriori computation, it should find it, however there is no way to find computation errors related to bad values or formula written in the code.

Finally, you can download your file at any time by clicking on the button “Save file”. There is no auto-save feature, so try to save your work more than once a day in order not to loose something important.

By convention, the name of the file shall be the same as the drug model ID, followed by the .tdd suffix. For instance, for the drug model ch.tucuxi.imatinib.fuchs2012, the file name is ch.tucuxi.imatinib.fuchs2012.tdd .

Must read (general considerations)

This section contains general considerations that are useful for a better understanding of the writing.

Units :

The units must be well specified, and are present everywhere: covariates, targets, PK parameters, durations. Tucuxi deals with automatic translation of units, but it only works on the units known by the software. So, it is mandatory to use one of the available units. This is specially true for covariates and targets, however the PK parameter units are not checked, and are the responsibility of the drug model writer.

Concentration : The gram is the conventional unit of mass in chemistry, we usually use the gram per liter for concentration. A valid concentration unit is any of the following : g/l, mg/l, ug/l, g/ml, mg/ml, ug/ml.

Time : A valid time unit is any of the following : “y” for year, “month”, “d” for day, “h” for hour, “min” for minute and “s” for second.

Covariates : The units of the covariates have to be recognised by the system. The list of all recognized units is available List of units . Also, some covariates are quite standard, so it is important to keep the standard IDs to ease the integration of the model with external databases. Please have a look at section Covariates for a list of current covariates.

A priori computations : There are various parts where covariates can act on computations, thanks to a priori computations. These a priori computations are the most difficult part of a drug model writing.

Warning

It is strongly suggested to have a look at the drug model specifications for a full explanation of this part, in section Operation.

Conventions

  • (covariate Ids are camelCase. Parameter Ids are usually CamelCase)

  • Drug model ID : <country>.<company/institution>.<drugId>.<studyFirstAuthorName><yearOfPublication>

General structure

The global structure of the drug model is divided into three parts :

  • History (History of the file)

  • Head (General information)

  • DrugModel (Everything needed for computation)

Typically, the history part only serves as a revision control of the file. The Head contains general information about the drug and the study from which the drug model has been built. The DrugModel is definitely the most important, as it contains every information required for computations.

History

This section shows who made or modified the drug file and when.

  • History

    • Revisions

      • Revision

        • Action executed : Type of revision

        • Name of the author : Name of the person who wrote the revision

        • Name of the institution : Name of institution from which the revision was written

        • E-mail of the author : Email of the person who wrote the revision

        • Date of the modification : yyyy-mm-dd

        • Comments for revision

          • Commment lang (en and/or fr) : Comments about the modifications done in this revision in the specified language.

The type of revision is one of the following possibilities :

  • Creation : Creation of the file. Only one revision of this type is allowed.

  • Modification : Modification of the file.

  • Review : Review by a person. Comments in the revision tag allows to comment the review.

  • Validation : Validated by a person. No modification done on the document.

Warning

It is strongly suggested to add a new field every time someone edits the drug model.

Drug Model

This third part of a model file embeds every information required for any computation.

  • Drug Model

    • Drug ID : Unique identifier of the drug. The drugId shall uniquely identify the drug. It shall come out of a dictionary, and by convention is in lower case. This ID shall allow to have various models for the same drug.

    • Drug Model ID : This is the identifier of the model proposed in the file. It shall be unique. Some conventions will help maintain such models. It shall consist of alphanumeric characters separated by dots, such as ch.tucuxi.vancomycin.someone2020. The first part is the country identifier, the second the instution identifier, and the third the drug identifier. A fourth one is composed of the first author name and the year of publication of the underlying PK study.

Domain

  • Domain The Domain represents the validity of the drug model for a specific patient. So, depending on his covariates, the model should not be used. The domain of application gives information about the population on which the model can be applied.

    • Description

      • Description lang (en and/or fr) : The characteristics of the patients treated (disease, age, weidght range, etc). The description shall allow to understand the domain of application of the model. It shall be as complete as possible.

The constraints then allow the software to check wether the model can be used for a specific patient or not.

For instance, if the model is valid for adults from 20 to 60 years old, the covariate ageInYears of the patient shall be available and checked in order to avoir the use of the model for children.

In case a specific constraint is not met, then the errorMessage is used to notify the user.

  • Constraint List of constraints allowing the model to be used. You can click on it to add other different constraints. A constraint allows to check for the possibility to use the model with a specific patient, depending on his covariates validity.

    • Constraint Type : It is the importance of the constraint. A constraint can be soft or hard. In case of a soft one, only a warning is issued, while a hard constraint shall impose a rejection of a priori and a posteriori calculations.

    • Error message

      • Text lang (en and/or fr) : The translated error message describing whats is wrong for this constraint in the specified language

    • Required covariates List of required covariates for checking this constraint

      • Covariate ID : ID of a covariate required by this constraint

    • Checking operation

      • Soft formula (Javascript)

        • Function input

          • id : Name of the covariate

          • Simple Data Type : int or double or bool

        • code : Formula used to check the validity of covariates

Covariates

A covariate is a medical information about the patient. A drug can contain from 0 to an unlimited number of covariates that can then be used by Tucuxi to compute and adapt the parameters for the given patient. They are defined in this manner:

  • Covariates You can click on it to append a new covariate or a new type of covariate

    • Covariate

      • Covariate ID : The covariate’s unique identifier

      • Name of the covariate

        • Name lang (en and/or fr) : Name of the covariate for the specified language

      • Description lang (en and/or fr) : Description of the covariate for the specified language

      • Unit : The covariate’s unit

      • Covariate Specific Data Type : The covariate type allows to indicate if the covariate is standard, related to birth, or related to sex.(stard / sex / ageInYears / ageInDays / ageInWeeks / ageInMonths)

      • Covariate Data Type : The covariate data type allows to indicate the type in terms of int, double, bool or date.

      • Interpolation Type : The interpolation type allow to decide how the calculation interprets covariates changing over time. (direct/linear/sigmoid/tanh)

      • Refresh period The refresh period for the covariate value. It is used when the interpolation type is not direct. The period defines the time between two modifications of the real covariate value to be used for adjusting other parameters.

        • Unit : The unit of the refresh period

        • Value : The duration of the refresh period

      • CovariateValue

        • Standard or population value

      • Validation

        • Error message

          • Texte lang (en and/or fr)

        • Operation

          • Soft formula (Javascript)

            • Function inputs

              • Function input

                • ID

                • Simple Data Type

            • Code

          • Comments for operation

        • Comment for validation

      • Comments for covariate

A covariate ID must identify the covariate. Some conventions allow to handle generic covariates and are described below.

The unit of the covariate is the unit presented to the user - for example “kg” for the covariate “weight”. The type, on the other hand, is the internal type used to store the covariate’s value. It can be either an int, a double or a boolean. In case of boolean, then the term is bool, and the value shall be 1 for true and 0 for false.

For genetic factors, it is suggested to use gene_XXX for the covariate ID, where XXX is the gene identification.

Covariate ID

Description

birthbodyweight

weight of the patient at birth

bodyweight

current body weight of the patient

age

current age of the patient, in year

pna

for neonates, post natal age, in days

ga

gestational age, in weeks

clcr

clearance of creatinine

gist

boolean indicating the presence of a gastrointestinal stromal tumor

sex

sex of the patient (0: female, 1: male)

mic

minimal inhibitory concentration

When it is not possible to know the value of a covariate for a specific patient, the default value is used instead. It corresponds to the value of the average individual, also called the typical patient.

Details on sex and age as a covariate :

Sex is represented as a floating point value in the range [0,1]. The rationale is that it allows to have continuous formula taking advantage of the mean value. If we do not know the person’s sex, then how would we choose if he/she is supposed to be a man or a woman? Using a floating point allows to set the value to 0.5 if that information is missing. Therefore the prediction will correspond to an individual being an intermediate between a man and a woman.

Sex is considered as a special covariate in the sense that it could be retrieved from administrative data about the patient.

The age of the patient corresponds to a special covariate, because of two factors :

  • As for the sex, it can be retrieved from administrative data, that is the birthdate.

  • In the drug models it can be used in years, months, weeks or days.

In a drug model, when an age is required, it shall be using the special type to specify if it is ageInYears, ageInMonths, ageInWeeks or ageInDays. A default value has to be indicated as well.

In the patient data that will be scanned to get the covariates used for calculation, there are two means of specifiying the age. It can be of the same type as the drug model covariates, or it can come from a birthdate.

In case the patient data contains the birthdate, it should have the ID birthdate

Tucuxi is then able to calculate the age based on the birthdate, following the granularity defined in the drug model covariate. It will therefore be automatically updated by the software. For instance, in a model of gentamicin for neo-nates, the ageInDays will be updated every day automatically.

covariateType :

Value

Description

standard

A normal covariate

sex

The covariate represents the sex of the patient. Can be automatically retrieved from administrative data, specifically in a patient covariate called sex

ageInYears

The age of the patient, in years. Can be automatically retrieved from administrative data, specifically in a patient covariate called birthdate

ageInMonths

The age of the patient, in months. Can be automatically retrieved from administrative data, specifically in a patient covariate called birthdate

ageInWeeks

The age of the patient, in weeks. Can be automatically retrieved from administrative data, specifically in a patient covariate called birthdate

ageInDays

The age of the patient, in days. Can be automatically retrieved from administrative data, specifically in a patient covariate called birthdate

covariateDataType :

Value

Description

int

An integer

double

A 64-bit double

bool

A boolean value

date

A date in format

interpolationType :

Value

Description

direct

As soon as a new covariate value exists, its value is applied

linear

If the covariate has two values at two different times, a linear interpolation is applied between both time points

sigmoid

If the covariate has two values at two different times, a sigmoid interpolation is applied between both time points

tanh

If the covariate has two values at two different times, an hyperbolic tangent interpolation is applied between both time points

Active moiety

  • Active moieties

    • Active moiety

      • Active moiety ID Active moiety unique identifier

      • Active moiety name The translated active moiety’s names

      • Unit The active moiety’s unit

      • List of analyte IDs The list of analytes influencing this active moiety

        • Analyte ID The ID of an analyte required to compute this active moiety

      • Formula to convert analytes to active moiety The formula for calculating the active moiety concentration based on the analytes

        • Hardcoded formula : IdealBodyWeight / BodySurfaceArea / eGFR_CockcroftGaultGeneral / OperationEGFRCockcroftGaultGeneral / eGFR_CockcroftGaultIBW / eGFR_CockcroftGaultAdjIBW / GFR_MDRD / GFR_CKD_EPI / eGFR_Schwartz / GFR_Jelliffe / eGFR_SalazarCorcoran / direct / sum2

        • Comments for analytesToMoietyFormula

      • Targets A list of targets. It contains all the data about the targeted residual concentration, peak concentration and mean concentration.

        • Target A target to be reached

          • Target type : peak / residual / mean / auc / auc24 / cumulativeAuc / aucOverMic / auc24OverMic / timeOverMic / aucDividedByMic / auc24DividedByMic / peakDividedByMic

          • Target values

          • Unit The target unit

          • Minimum

            • Standard or population value : Minimum targeted value

          • Maximum

            • Standard or population value : Maximum targeted value

          • Best

            • Standard or population value : Best targeted time

          • Toxicity alarm level

            • Standard or population value : Toxicity threshold

          • Inefficacy alarm level

            • Standard or population value : Effectiveness threshold

        • Comments for target click on it to append a comment

          • comment (lang en and/or fr)

Value

Description

peak

The target is the peak concentration. Times are to be added in the target to define when the peak should be found

residual

The target is the residual concentration

mean

The target is the mean concentration

auc

The target is the area under curve, for a single intake cycle

auc24

The target is the area under curve on 24h

cumulativeAuc

The target is the cumulative area under curve since the beginning of the treatment

aucOverMic

The target is the area under the concentration curve, but only the portion over the MIC, for a single intake cycle

auc24OverMic

The target is the area under the concentration curve, but only the portion over the MIC, for 24h

timeOverMic

The target is the time spent over the MIC, for a single intake cycle

aucDividedByMic

The target is the area under the concentration curve divided by the MIC, for a single intake cycle

auc24DividedByMic

boolean indicating the presence of a gastrointestinal stromal tumor

peakDividedByMic

The target is the area under the concentration curve for 24h divided by the MIC

fractionTimeOverMic

The target is the fraction of time spent over the MIC, in [0,1]

residualDividedByMic

The target is the value of the residual concentration divided by the MIC

In case of an aucOverMic, timeOverMix, aucDividedByMic, peakDividedByMic, residualDividedByMic or fractionTimeOverMic target, a covariate called mic has to be added in the drugModel.

A target can be one of the three types residual, peak or auc. Consequently, there can be a maximum of four different targets for a single drug. All four must contain a minimum, maximum and best targeted concentration, but only the peak target will use the targeted times.

The formula are used to adapt the targeted values using, for example, the patient’s covariates, but can be left blank if the values themselves are sufficient. Please note that appart from being used to display indicators in the curve panel, the targets will also be used by the reverse engines to find the appropriate dosage. If you do not provide any, the reverse engines will not be able to provide a solution.

Analyte groups

  • List of analytes groups List of groups of analytes

    • Analyte group A group a analytes

      • Analyte group ID A unique ID for the group of analytes. It uniquely identifies the group within the drugModel. It is required by the “Formulation and route” in order to indicate on which group the various parameters are connected to.

      • Pk Model ID The ID of the Pk Model to be used for computation related to this group. The drug’s Pk model ID must reference an existing pharmacokinetic model : linear/michaelismenten.1/2/3comp.micro/macro. The difference between macro and micro model consists in the parameters supplied. In case of macro the parameters are typically clearance and volume, while in case of micro the parameters are the micro constants k. A description of the available PK models can be found in section Tucuxi PK models.

      • List of analytes The list of analytes of the group

        • Analyte

          • Analyte ID The ID of the analyte

          • Unit The unit used to do calculation with the analyte

          • Molar mass The molar mass of the analyte

            • Value Value of the molar mass

            • Unit Unit of the molar mass

          • Description

            • Description lang (en and/or fr) : The translated descriptions of the analyte

          • Error model

            • Error Model Type The error model corresponding to this analyte. The error model is the representation of the intra-individual error. It is used by the post engines and the percentiles engines to regulate the patient’s measures and intra-individual variability. : additive / proportional / exponential / mixed / propexp / none.

            • Sigma values

              • Sigma value A sigma used by the error model

                • Standard or population value

            • Comments for errorModel

          • Comments for analyte

For additive, proportional, exponential and propexp, a single sigma is required. For mixed, two sigmas are mandatory: The first corresponds to the additive error, and the second to the proportional error.

For each error model except the softcoded one, the model is implemented in the software. For a softcoded, the formula supplied in the file is used instead.

Parameters

The parameters are used by the models to compute the curves and their value depend on the type of the prediction. If the prediction is made for the typical patient, the model will use the population parameters. If the prediction is made a priori for a specific patient, the population parameters will be adapted using patient’s covariates. Finally, if the prediction is made a posteriori, the a priori parameters will be adapted using the patient’s measures and a post engine.

Parameters are split into two categories: disposition and absorption parameters. The disposition parameters describe how the drug is eliminated from the body, while the absorption parameters describe how it diffuses into the main compartment. For one analyte group there can be various routes of administrations, and as such various absorption parameters, while the disposition parameters are shared among the routes of administrations.

  • Disposition parameters

    • PK Parameters

      • PK Parameter

        • Parameter ID ID of the parameter

        • Unit the unit of the parameter value

        • Parameter value

          • Standard or population value : The population value reported

          • A priori computation

            • Soft formula (Javascript)

              • Function inputs Each function input are the covariate for this PK parameter.

                • Function input

                  • ID

                  • Simple Data Type

                • Code

              • Comments for aprioriComputation

        • Between Subject Variability

          • Between Subject Variability type : none / normal / lognormal / proportional / exponential / additive

          • Standard Deviations

            • Standard Deviation : Value of the SD reported

        • Validation

          • Error message

            • Text lang (en and/or fr)

          • Operation

            • Soft formula (Javascript)

              • Function inputs

                • Function input

                  • ID

                  • Simple Data Type : int / double / bool

              • code

            • Comments for operation

          • Comments for validation

        • Comments for parameter

With the help of the BSV (Between Subject Variability) of each parameter, the correlations are used to build the correlation and covariance matrices. It is possible to express correlations between two parameters.

  • ** Correlations**

    • Correlation

      • param1 : The first parameter’s ID

      • param2 : The second parameter’s ID

      • value : The correlation’s value

Formulation and route

Finally, the absorptionParameters are the absorption parameters corresponding to the absorptionModel selected. For these absorption parameters, the Analyte group ID allows to identify the analytes group related to the parameter set.

  • List of formulations and routes default id0

    • Formulation and route

      • Formulation and Route ID : ID of the formulation and route

      • Formulation : undefined / parenteralSolution / oralSolution / test

      • administrationName : The administrationName is a free string, and can allow to differentiate between identical formulations offered by different vendors.

      • administrationRoute : undefined / intramuscular / intravenousBolus / intravenousDrip nasal / oral rectal / subcutaneous / sublingual / transdermal / vaginal

      • Absorption Model ID : undefined / bolus / extra / extra.lag / infusion

Value

Description

extra

Extravascular route. Can be used for various administration routes, like in a muscle, oral, anal, …

extra.lag

Extravascular route with lag time. Can be used for various administration routes, like in a muscle, oral, anal, …

infusion

Infusion in the central compartment.

bolus

Immediate availability of the drug in the blood, like an intravenous bolus.

Dosages

This section contains all the information about the dosages, such as the default units and values of the doses, intervals and infusions. It also contains the lists of doses, intervals and infusions used by the dosage adaptation module. A dosage adaptation module is used by Tucuxi to propose and adapt the dosage of a drug, given its targets and the patient’s data.

  • Dosages These are the dosages associated with a formulation and route used for proposing dosage adaptation.

    • Analyte conversions The analyte conversion is important if not all the drug is part of a single analyte. In that case the factor allows to link the quantity of analyte corresponding to a certain quantity of drug. The available doses, intervals and infusions are used by the dosage adaptation engine to propose a suitable dosage.

      • Analyte conversion Conversion from the quantity of drug to the quantity of analyte

        • Analytes ID : The ID of the analyte

        • Factor : The factor to be multiplied to the drug quantity to obtain the analyte quantity

    • Available doses The idea here is to use Range Values OR Fixed Values by clicking on it, but not both at the same time. However the software support both at the same time. Using Stardard Apriori Value fields allow the dose range to be very flexible, depending on the patient covariates. If rangeValues is used, then the dosage adaptation engine will try every dose between the boundaries from and to, using step. For instance, if from=5, to=25, and step=10, then the values will be 5, 15, and 25.

      • Unit : Unit of the intervals

      • Defaut

        • Standard or population value : Default interval

      • Range values Available intervals represented as a range

        • From

          • Standard or population value : Starting value of the range

        • To

          • Standard or population value : Ending value of the range

        • Step

          • Standard or population value : Step to be applied between from and to

    • AvailableIntervals The idea here is to use Range Values OR Fixed Values by clicking on it, or both at the same time. Using Stardard Apriori Value fields allow the dose range to be very flexible, depending on the patient covariates. If Range Values is used, then the dosage adaptation engine will try every interval between the boundaries from and to, using step. For instance, if from=5, to=25, and step=10, then the values will be 5, 15, and 25.

      • Unit : Unit of the intervals

      • Default

        • Standard or population value : Default interval

      • Fixed values A list of fixed intervals. You can add a value by clicking on it.

        • Value : An interval value.

    • AvailableInfusion The idea here is to use Range Values OR Fixed Values, or both at the same time. Using Stardard Apriori Value fields allow the infusion time range to be very flexible, depending on the patient covariates. If rangeValues is used, then the dosage adaptation engine will try every infusion time between the boundaries from and to, using step. For instance, if from=5, to=25, and step=10, then the values will be 5, 15, and 25.

      • UnitUnit of the infusion times

        • Default

        • Standard or population value : Default infusion time

      • Fixed values A list of fixed infusion times

        • Value : An infusion time value

Time considerations

Time considerations can help the software to optimize some computations, and also to get information about the relevance of a measure. The second part of the time considerations consists in the time after which a measure is considered irrelevant, and shall not be used for a posteriori computations.

The half-life describes the time it takes for the plasma concentration, or the amount of drug in the body, to be reduced by 50%. Therefore, in each succeeding half-life, less drug is eliminated. After one half-life the amount of drug remaining in the body is 50%, after two half-lives 25%, etc. After 4 half-lives the amount of drug (6.25%) is considered to be negligible regarding its therapeutic effects.

The half-life is used to determine the residual concentration of a drug at steady-state. The half-life duration given above is multiplied by the cycle multiplier in order to find out how many cycles need to be completed before reaching the steady-state. It is then possible to compute the residual concentration of the drug at steady-state. In most cases, a multiplier of 10 is sufficient, but it is suggested to have a a bigger multiplier. At the end, the automated tests allow to detect if a multiplier was suffenciently big.

  • Time considerations

    • Half life

      • Unit : Time unit of the half life

      • Duration

        • Standard or population value : Value of the half life

      • ** Multiplier** : Number of half lifes to reach steady state

      • Comments for halfLife : Comments about the half life

        • comment lang (en and/or fr)

    • Outdated measure information Indication about the relevance of a measure

      • Unit : Time unit

      • Duration

        • Standard or population value

      • Comments for outdatedMeasure

        • comment lang (en and/or fr)

List of units

Weight unit

A valid weight unit is any of the following:

  • kg

  • g

  • mg

  • ug

  • µg

  • ng

Concentration unit

A valid concentration unit is any of the following:

  • g/l

  • mg/l

  • ug/l

  • µg/l

  • ng/l

  • g/dl

  • mg/dl

  • µg/dl

  • ug/dl

  • ng/dl

  • g/cl

  • mg/cl

  • µg/cl

  • ug/cl

  • ng/cl

  • g/ml

  • mg/ml

  • µg/ml

  • ug/ml

  • ng/ml

Temperature unit

A valid temperature unit is any of the following:

  • celsius

Flow rate unit

A valid flow rate unit is any of the following:

  • ml/min

  • l/min

  • ml/h

  • l/h

Mole Concentration unit

A valid mole concentration unit is any of the following:

  • mol/l

  • mmol/l

  • umol/l

  • mol/ml

  • mmol/ml

  • umol/ml

Time unit

A valid time unit is any of the following:

  • y

  • month

  • d

  • h

  • min

  • s

Length unit

A valid length unit is any of the following:

  • m

  • cm

  • dm

  • mm

  • ft

  • in

Molar mass

A valid molar mass unit is any of the following:

  • kg/mol

  • g/mol

  • mg/mol

  • ug/mol

  • µg/mol

  • ug/umol

  • µg/umol

  • g/umol

  • kg/umol

Concentration Time unit

A valid concentration times time unit is any of the following:

  • h*g/l

  • h*mg/l

  • h*ug/l

  • h*g/ml

  • h*mg/ml

  • h*ug/ml

  • g*h/l

  • mg*h/l

  • ug*h/l

  • g*h/ml

  • mg*h/ml

  • ug*h/ml

  • min*g/l

  • min*mg/l

  • min*ug/l

  • min*g/ml

  • min*mg/ml

  • min*ug/ml

  • g*min/l

  • mg*min/l

  • ug*min/l

  • g*min/ml

  • mg*min/ml

  • ug*min/ml

Empty unit

A valid absence of unit is any of the following:

  • empty string

  • “-”