*********************************** Drug description file specification *********************************** This section describes formal specifications of the Tucuxi Drug Description file (.tdd). Specifically it lists formal specifications of the various fields. Each specification is a unique number, prefixed by DFS (for Drug File Specification). The drug model importer shall implement these verifications, and shall reference the DFS numbers in the comments. The drug file editor shall implement these verifications, and shall reference the DFS numbers in the comments. .. _drugfile_model: Model ----- | The global structure of the XML file is the following: +--------------------+-----------------+--------+-----------------------------------------------+ | Tag name | Format | Occ. | Description | +====================+=================+========+===============================================+ | | :ref:`history` | 1:1 | History of the file | +--------------------+-----------------+--------+-----------------------------------------------+ | | :ref:`head` | 1:1 | General information | +--------------------+-----------------+--------+-----------------------------------------------+ | | :ref:`drugModel`| 1:1 | Everything needed for computation | +--------------------+-----------------+--------+-----------------------------------------------+ .... :dfs:`0001` A *model* shall have exactly one *history*, one *head* and one *drugModel*. .. _drugfile_history: History ------- The history of the file is described inside the tag. A standard history looks like this: .. literalinclude:: drug_description/examples/history_example.xml :language: xml | +-----------------------------+------------------+--------+-----------------------------------------------------------------+ | Tag name |Format | Occ. | Description | +=============================+==================+========+=================================================================+ | | | 1:1 | List of revisions | +-----------------------------+------------------+--------+-----------------------------------------------------------------+ |___ | | 1:∞ | Revision | +-----------------------------+------------------+--------+-----------------------------------------------------------------+ |________ | string | 1:1 | Type of revision | +-----------------------------+------------------+--------+-----------------------------------------------------------------+ |________ | string | 1:1 | Name of the person who wrote the revision | +-----------------------------+------------------+--------+-----------------------------------------------------------------+ |________ | string | 1:1 | Name of institution from which the revision was written | +-----------------------------+------------------+--------+-----------------------------------------------------------------+ |________ | string | 1:1 | Email of the person who wrote the revision | +-----------------------------+------------------+--------+-----------------------------------------------------------------+ |________ | date | 1:1 | Date of the revision | +-----------------------------+------------------+--------+-----------------------------------------------------------------+ |________ | :ref:`comments` | 1:1 | Comments about the modifications done in this revision | +-----------------------------+------------------+--------+-----------------------------------------------------------------+ .... :dfs:`0002` The type of revision is one of the following possibilities: - creation - modification - review - validation .... :dfs:`0003` In a *revisions* list, there shall be at least one *revision* with *revisionAction* equal to *creation*. .... :dfs:`0004` A *revision* shall contain exactly one *revisionAction*, one *revisionAuthorName*, one *institution*, one *email*, one *date*, and one *comments*. .... :dfs:`0005` An *email* shall contain a valid email address, with an @ in it. Head ---- .. _drugfile_head: The head of the file contains general information about the drug, such as its ID, the model it uses, its name, description and so on. It does not embed information required by the computing engines. .. csv-table:: head content :header: "Tag name", "Format", "Occ.", "Description" :widths: 15, 10, 5, 30 "", , 1:1 , Description of the drug itself "___", , 1:1 , List of ATCs "______", string , 1:∞ , "The drug code, or Anatomical Therapeutic Chemical (ATC)" "___", , 1:1 , List of active substances "______", string , 1:∞ , An active substance present in the drug "___", , 1:1 , The translated drug's names "______", string , 1:∞ , Name of the drug for the specified language "___", , 1:1 , The translated drug's descriptions "______", string , 1:∞ , Description of the drug for the specified language "___", , 1:1 , The translated drug's TDM strategy "______", string , 1:∞ , TB : The description of the TDM strategy "", , 1:1 , Description of the study used to fill this file "___", , 1:1 , The translated drug's study names "______", string , 1:∞ , Study name of the drug for the specified language "___", string , 1:1 , The name of the study authors "___", , 1:1 , The translated descriptions of the study "______", string , 1:∞ , Description of the study for the specified language "___", , 1:1 , References to related publications "______", string , 0:∞ , Reference to a specific article or publication "", :ref:`comments` , 1:1 , Comments about the drug's header .... :dfs:`0006` A *head* shall contain exactly one *drug*, one *study* and one *comments*. .... :dfs:`0007` A *drug* shall contain exactly one *atcs*, one *activeSubstances*, one *drugName*, one *drugDescriptions* and one *tdmStrategy*. .... :dfs:`0008` In *drug*, the list *atcs* shall contain at least one *atc*. .... :dfs:`0009` In *drug*, an *atc* shall be a non empty string corresponding to a valid ATC format. .... :dfs:`0010` In *drug*, the list *activeSubstances* shall contain at least one *activeSubstance*. .... :dfs:`0011` In *drug*, an *activeSubstance* shall be a non empty string. .... :dfs:`0012` In *drug*, the list *drugName* shall contain at least one *name*. .... :dfs:`0013` In *drug*, the list *drugDescriptions* shall contain at least one *desc*. .... :dfs:`0014` In *drug*, the list *tdmStrategy* shall contain at least one *text*. .... :dfs:`0015` A *study* shall contain exactly one *studyName*, one *studyAuthors*, one *description* and one *references*. .... :dfs:`0016` In *study*, an *studyAuthors* shall be a non empty string. .... :dfs:`0017` In *study*, an *studyName* shall contain at least one *name*. .... :dfs:`0018` A *description* follows the rules of a *translatedDescs*. It shall contain at least one *desc*, and only *desc* tags. .... :dfs:`0019` In *study*, a *reference* shall have an attribute *type* that can be any of the following values: - plain - bibtex - doi Drug model ---------- The drug model embeds all information required for the various computations. .. csv-table:: drugModel content :header: "Tag name", "Format", "Occ.", "Description" :widths: 15, 10, 5, 30 "", , , Everything needed for any calculation "____", string , 1:1 , Unique identifier of the drug "____", string , 1:1 , Identifier of the model described in the file "____", :ref:`domain` , 1:1 , Usage domain for this model. TB "____", :ref:`covariates` , 1:1 , List of covariates used by the model "____", :ref:`activeMoieties`, 1:1 , List of active moieties. TB "____", :ref:`analyteGroups`, 1:1 , List of groups of analytes "____", :ref:`formulationAndRoutes`, 1:1 , List of formulation and routes of administration "____", :ref:`timeConsiderations`, 1:1 , "Some information about time, such as halflife" "____", :ref:`comments` , 1:1 , General comments on the model .... :dfs:`0020` A drug model shall contain exactly one *drugId*, one *drugModelId*, one *domain*, one *covariates*, one *activeMoieties*, one *analyteGroups*, one *formulationAndRoutes*, one *timeConsiderations*, and one *comments*. .... :dfs:`0021` A *drugId* shall be a non empty string. .... :dfs:`0022` A *drugModelId* shall be a non empty string. Domain ------ .. csv-table:: domain content :header: "Tag name", "Format", "Occ.", "Description" :widths: 15, 10, 5, 30 "", , 1:1 , The translated descriptions of the domain "___", string , 1:∞ , Description of the domain for the specified language "", string , 1:1 , List of constraints allowing the model to be used "___", :ref:`constraint`, 0:∞ , A constraint for using the model "______", :ref:`contraintType` , 1:1 , Importance of the constraint: soft or hard "______", , 1:1 , The translated error message for the constraint "_________", string , 1:∞ , Error message in the specified language "______", , 1:1 , List of required covariates for checking this constraint "_________", string , 1:∞ , Id of a covariate required by this constraint "______", :ref:`operation` , 1:1 , formula used to check the validity of covariates "______", :ref:`comments` , 1:1 , Comments conserning the constraint .... :dfs:`0023` A *domain* shall contain exactly one *description* and one *constraints*. .... :dfs:`0024` A *constraint* shall contain exactly one *constraintType*, one *errorMessage*, one *requiredCovariates*, one *checkOperation*, and one *comments*. .... :dfs:`0025` A *constraintType* is any of the following: - soft - hard .... :dfs:`0026` An *errorMessage* shall contain at least one *text*. .... :dfs:`0027` A *requiredCovariates* shall contain at least one *covariateId*. .... :dfs:`0028` A *covariateId* found in a *requiredCovariates* list shall exist as a *covariateId* in a *covariate*. .... :dfs:`0029` A *checkOperation* is an *operation*, and shall be validated as an *operation*. .. _drugfile_operation: Operation --------- An operation is used at many places within the file, with different tags refering to it. .... :dfs:`0030` An operation shall contain one of the following: - *softFormula* - *hardFormula* - *multiFormula* and a *comments*. .... :dfs:`0031` A *softFormula* shall contain one *inputs* and one *code*. .... :dfs:`0032` An *inputs* shall contain any number of *input*. .... :dfs:`0033` An *input* shall contain one *id* and one *type*. .... :dfs:`0034` In an *input*, an *id* shall reference an existing *covariateId* present in a *covariate*. .... :dfs:`0035` In an *input*, a *type* is any of the following: - int - double - bool .... :dfs:`0036` A *hardFormula* contains a single identifier, from a predefined list: - To be defined .... :dfs:`0037` A *multiFormula* contains at least one *softFormula* or *hardFormula*. It can then contain any number of these items, in any order. Covariate --------- A covariate represents an information about the patient that can be useful for computations. .. csv-table:: covariates content :header: "Tag name", "Format", "Occ.", "Description" :widths: 15, 10, 5, 30 " ", , 0:∞ , Description of a covariate "____ ", string , 1:1 , The covariate's unique identifier "____ ", , 1:1 , The translated covariate's names "_______ ", string , 1:∞ , Name of the covariate for the specified language "____ ", , 1:1 , The translated covariate's descriptions "_______ ", string , 1:∞ , Description of the covariate for the specified language "____ ", string , 1:1 , The covariate's unit "____ ", :ref:`covariateType` , 1:1 , The covariate's type "____ ", :ref:`covariateDataType` , 1:1 , The covariate's type "____", :ref:`interpolationType` , 1:1 , The covariate's type "____ ", , 0:1 , "The refresh period for the covariate value" "________ ", , 1:1 , "The unit of the refresh period" "________ ", , 1:1 , "The duration of the refresh period" "____", :ref:`stdAprioriValue` , 1:1 , "The covariate's value, that can be modified by other covariates" "____", ref:`validation` , 1:1 , Potential validation function for the covariate value "____", :ref:`comments` , 1:1 , Comments about the covariate | .... :dfs:`0038` A *covariates* shall contain any number of *covariate*, but only *covariate* tags. .... :dfs:`0039` A *covariate* shall contain exactly one *covariateId*, one *covariateName*, one *description*, one *unit*, one *covariateType*, one *dataType*, one *interpolationType*, one *covariateValue*, one *validation* and one *comments*. .... :dfs:`0040` A *covariateId*, in a *covariate*, shall be an non-empty string. .... :dfs:`0041` A *covariateName* follows the rules of a *translatedNames*. .... :dfs:`0043` In a *covariate*, a unit is any valid unit, as described in :ref:`drugfile_unit`. .... :dfs:`0044` In a *covariate*, if the *covariateType* is a *sex*, then the unit shall be empty or *-*. If the *covariateType* is *ageInYears*, then the unit shall be *y*. If the *covariateType* is *ageInMonths*, then the unit shall be *mon*. If the *covariateType* is *ageInWeeks*, then the unit shall be *w*. If the *covariateType* is *ageInDays*, then the unit shall be *d*. If the *covariateType* is *dose*, then the unit shall be a valid :ref:`drugfile_weight_unit`. .... :dfs:`0045` In a *covariate*, if the *covariateId* is *bodyweight*, then the unit shall be a :ref:`drugfile_weight_unit`. If the *covariateId* is *temperature*, then the unit shall be a :ref:`drugfile_temperature_unit`. TODO : Add validations for known covariateIds. .... :dfs:`0046` A *dataType* is any of the following: - int - double - bool .... :dfs:`0047` A *covariateType* is any of the following: - *standard* - *sex* - *ageInYears* - *ageInMonths* - *ageInWeeks* - *ageInDays* - *dose* .... :dfs:`0048` A *interpolationType* is any of the following: - *direct* - *linear* Two other values are valid, but not yet supported by the software. .... :dfs:`0049` In a *covariate*, if *interpolationType* is not *direct*, then there should be a *refreshPeriod* in *covariate*. .... :dfs:`0050` A *refreshPeriod* shall contain one *unit* and one *value*. .... :dfs:`0051` In a *refreshPeriod*, the unit shall be a valid :ref:`drugfile_time_unit`. .... :dfs:`0052` In a *refreshPeriod*, the *value* shall be a valid strictly positive floating point number. .... :dfs:`0053` A *validation* tag shall contain an *errorMessage*, an *operation*, and a *comments*. Active moiety ------------- An active moiety corresponds to an active substance of the medical drug. A drug model can be composed of more than one active moiety, but this case is not very common. The *activeMoietyId* uniquely identifies the active moiety. In case of a single analyte drug model it is usually convenient to share the same Id as the analyte. .. csv-table:: activeMoiety content :header: "Tag name", "Format", "Occ.", "Description" :widths: 15, 10, 5, 30 " ", , , "An active moiety" "____ ", string , 1:1 , "active moiety unique identifier" "____ ", , 1:1 , "The translated active moiety's names" "_______ ", string , 1:∞ , "Name of the active moiety for the specified language" "____ ", string , 1:1 , "The active moiety's unit" "____ ", , 1:1 , "The list of analytes influencing this active moiety" "_______ ", string , 1:∞ , "The Id of an analyte required to compute this active moiety" "____ ", :ref:`operation` , 1:1 , "The formula for calculating the active moiety concentration based on the analytes" "____ ", :ref:`targets` , 1:1 , "A list of targets" "________ ", :ref:`target` , 0:∞ , "A target to be reached" .... :dfs:`0055` An *activeMoieties* shall contain at least one *activeMoiety*, and only *activeMoiety* tags. .... :dfs:`0056` An *activeMoiety* shall contain one *activeMoietyId*, one *activeMoietyName*, one *unit*, one *analyteIdList*, one *analytesToMoietyFormula*, and one *targets*. .... :dfs:`0057` An *activeMoietyId* shall be a non-empty string. .... :dfs:`0058` An *activeMoietyName* is a *translatedNames*. .... :dfs:`0059` In an *activeMoiety* the *unit* shall be a valid :ref:`drugfile_concentration_unit`. .... :dfs:`0060` An *analyteIdList* shall contain at least one *analyteId*, and only *analyteId* tags. .... :dfs:`0061` In an *analyteIdList*, an *analyteId* shall be a non-empty string. .... :dfs:`0062` An *analytesToMoietyFormula* is an operation. Target ------ The targets of an active moiety are described in the tag. It contains all the data about the targeted residual concentration, peak concentration and mean concentration. .. csv-table:: target content :header: "Tag name", "Format", "Occ.", "Description" :widths: 15, 10, 5, 30 " ", , , "A target" "____ ", :ref:`targetType` , 1:1 , "Type of target, from an enumeration" "____ ", , 1:1 , "The target values" "________ ", string , 1:1 , "The target unit" "________ ", :ref:`stdAprioriValue` , 1:1 , "Minimum targeted value" "________ ", :ref:`stdAprioriValue` , 1:1 , "Maximum targeted value" "________ ", :ref:`stdAprioriValue` , 1:1 , "Best targeted value" "________ ", :ref:`stdAprioriValue` , 1:1 , "Threshold over which an alarm shall be triggered" "________ ", :ref:`stdAprioriValue` , 1:1 , "Threshold under which an alarm shall be triggered" "________ ", , 0:1 , "The MIC value, optional" "____________ ", string , 1:1 , "The MIC unit" "____________ ", :ref:`stdAprioriValue` , 1:1 , "The MIC value" "____ ", , 0:1 , "Time targets when required by the target type" "________ ", string , 1:1 , "The time unit" "________ ", :ref:`stdAprioriValue` , 1:1 , "Minimum targeted time" "________ ", :ref:`stdAprioriValue` , 1:1 , "Maximum targeted time" "________ ", :ref:`stdAprioriValue` , 1:1 , "Best targeted time" "____ ", :ref:`comments` , 1:1 , "Comments about the target" .... :dfs:`0063` A *targets* shall only contain *target* tags. .... :dfs:`0064` A *target* shall contain one *targetType*, one *targetValues*, 0 or 1 *times* (depending on the target type), and one *comments*. If *targetType* is *peak* or *peakDividedByMic*, *times* is mandatory. Else it should not be present. .... :dfs:`0065` A *targetType* shall be any of the following: - peak - residual - mean - auc - auc24 - cumulativeAuc - aucOverMic - auc24OverMic - timeOverMic - aucDividedByMic - auc24DividedByMic - peakDividedByMic - residualDividedByMic - fractionTimeOverMic .... :dfs:`0066` A *targetValues* shall contain one *unit*, one *max*, one *min*, one *best*, one *toxicityAlarm*, one *inefficacyAlarm*, and 0 or 1 *mic*, depending on the target type. If *targetType* is *aucOverMic*, *auc24OverMic*, *timeOverMic*, *aucDividedByMic*, *auc24DividedByMic*, *peakDividedByMic*, *residualDividedByMic*, or *fractionTimeOverMic* *mic* is mandatory. Else it should not be present. .... :dfs:`0067` In a *target*, if the *targetType* is *peak*, *residual*, *mean*, then the *unit* shall be a valid :ref:`drugfile_concentration_unit`. In a *target*, if the *targetType* is *auc*, *auc24*, *cumulativeAuc*, *aucOverMic*, *auc24OverMic*, then the *unit* shall be a valid :ref:`drugfile_concentrationtime_unit`. In a *target*, if the *targetType* is *timeOverMic*, *aucDividedByMic*, then the *unit* shall be a valid :ref:`drugfile_time_unit`. In a *target*, if the *targetType* is *peakDividedByMic*, *residualDividedByMic*, or *fractionTimeOverMic*, then the *unit* shall be empty or "-". .... :dfs:`0068` A *min* is a *stdAprioriValue*. .... :dfs:`0069` A *max* is a *stdAprioriValue*. .... :dfs:`0070` A *best* is a *stdAprioriValue*. .... :dfs:`0071` A *toxicityAlarm* is a *stdAprioriValue*. .... :dfs:`0072` A *inefficacyAlarm* is a *stdAprioriValue*. .... :dfs:`0160` In a *targetValues*, the default value of *inefficacyAlarm* shall be smaller of equal to the default value of *min*. .... :dfs:`0161` In a *targetValues*, the default value of *toxicityAlarm* shall be greater or equal to the default value of *max*. .... :dfs:`0154` In a *targetValues*, the default value of *min* shall be less or equal to the default value of *best*, the default value of *best* shall be less or equal to the default value of *max*. .... :dfs:`0155` In a *times*, the default value of *min* shall be less or equal to the default value of *best*, the default value of *best* shall be less or equal to the default value of *max*. .... :dfs:`0073` A *times* shall contain one *unit*, one *min*, one *max*, and one *best*. .... :dfs:`0074` In a *times*, the *unit* shall be a valid :ref:`drugfile_time_unit`. Analyte group ------------- .. csv-table:: analyteGroups content :header: "Tag name", "Format", "Occ.", "Description" :widths: 15, 10, 5, 30 " ", , 0:∞ , List of groups of analytes "____ ", string , 1:∞ , A group a analytes "________ ", string , 1:1 , A unique Id for the group of analytes "________ ", string , 1:1 , The Id of the Pk Model to be used for computation related to this group "________ ", , 1:1 , The list of analytes of the group "____________ ", :ref:`analyte` , 1:∞ , An analyte "________ ", :ref:`parameterSet` , 1:1 , A set of disposition parameters "____________ ", , 1:1 , List of parameters "________________ ", :ref:`parameter` , 1:∞ , A disposition parameter "____________ ", :ref:`correlations` , 1:1 , correlation between disposition parameters | .... :dfs:`0075` An *analytGroups* shall contain at least one *analyteGroup*, and only *analyteGroup* tags. .... :dfs:`0076` An *analytGroup* shall contain one *groupId*, one *pkModelId*, on *analytes*, and one *dispositionParameters*. .... :dfs:`0077` An *groupId* shall be a non-empty string. .... :dfs:`0078` A *pkModelId* identifies the PK model, and shall be one of the following (this list has to be updated when new models are added to Tucuxi): - "linear.1comp.macro" - "linear.1comp.micro" - "linear.2comp.macro" - "linear.2comp.macroRatios" - "linear.2comp.micro" - "linear.3comp.macro" - "linear.3comp.micro" - "linear.2comp.erlang1.macro" - "linear.2comp.erlang1.micro" - "linear.2comp.erlang2.macro" - "linear.2comp.erlang2.micro" - "linear.2comp.erlang3.macro" - "linear.2comp.erlang3.micro" - "linear.2comp.erlang4.macro" - "linear.2comp.erlang4.micro" - "linear.2comp.erlang5.macro" - "linear.2comp.erlang5.micro" - "linear.2comp.erlang6.macro" - "linear.2comp.erlang6.micro" - "michaelismenten.enzyme.1comp" .... :dfs:`0079` A *dispositionParameters* is a *parameterSet*. Analyte ------- .. csv-table:: analyte content :header: "Tag name", "Format", "Occ.", "Description" :widths: 15, 10, 5, 30 " ", , , An analyte "____ ", string , 1:1 , The Id of the analyte "____ ", string , 1:1 , The unit used to do calculation with the analyte "____ ", string , 1:1 , The molar mass of the analyte "________ ", , 1:1 , Value of the molar mass "________ ", :ref:`analyte` , 1:∞ , Unit of the molar mass "____ ", , 1:1 , The translated descriptions of the analyte "________", string , 1:∞ , Description of the analyte "____ ", :ref:`errorModel` , 1:1 , The error model corresponding to this analyte "____ ", :ref:`comments` , 1:1 , Comments about this analyte | .... :dfs:`0080` An *analytes* shall contain at least one *analyte*, and only *analyte* tags. .... :dfs:`0081` An *analyte* shall contain one *analyteId*, one *unit*, one *molarMass*, one *description*, one *errorModel*, and one *comments*. .... :dfs:`0082` In an *analyte*, the *unit* shall be a valid :ref:`drugfile_concentration_unit`. .... :dfs:`0083` A *molarMass* shall contain one *value* and one *unit*. .... :dfs:`0084` In a *molarMass*, the *value* shall be a valid positive floating point number. .... :dfs:`0085` In a *molarMass*, the *unit* shall be a :ref:`drugfile_molarmass_unit`. .... :dfs:`0086` In an *analyte*, an *analyteId* shall contain a non-empty string. This string shall be a valid *analyteId* defined in an *activeMoiety*. .... :dfs:`0158` All analytes and active moieties have to share the same concentration unit. This constraint may be removed in a later version, but currently it has to be met. Error model ----------- .. csv-table:: errorModel content :header: "Tag name", "Format", "Occ.", "Description" :widths: 15, 10, 5, 30 " ", , , Some time considerations "____ ", :ref:`errorModelType` , 1:1 , "Type of error model, an enum" "____ ", , 1:1 , A list of sigmas "________ ", :ref:`stdAprioriValue` , 1:∞ , A sigma used by the error model "____ ", :ref:`comments` , 1:1 , Comments about the error model | .... :dfs:`0087` An *errorModel* shall contain one *errorModelType*, one *sigmas* and one *comments*. .... :dfs:`0088` An *errorModelType* shall be any of the following: - additive - proportional - exponential - mixed - propexp - none .... :dfs:`0089` In an *errorModel*, if the *errorModelType* is *none*, then *sigmas* shall be empty. If the *errorModelType* is *mixed*, then *sigmas* shall contain two *sigma*. If the *errorModelType* is *additive*, *proportional*, *exponential* or *propexp*, then *sigmas* shall contain one *sigma*. .... :dfs:`0090` A *sigma* shall be a a *stdAprioriValue* with a default positive value. Formulation and routes ---------------------- .. csv-table:: formulationAndRoute content :header: "Tag name", "Format", "Occ.", "Description" :widths: 15, 10, 5, 30 " ", , , Formulation and route "____ ", string , 1:1 , "Id of the formulation and route" "____ ", string , 1:1 , "the formulation. Taken from a dictionary" "____ ", string , 1:1 , "A free field to discriminate vendors" "____ ", string , 1:1 , "The route of administration, taken from a dictionary" "____ ", :ref:`absorptionModel` , 1:1 , Id of the absorption model "____ ", :ref:`dosages` , 1:1 , Possible dosages "____ ", , 1:1 , Sets of absorption parameters "________ ", , 0:∞ , A set of absorption parameters for an analyte group "____________ ", string , 1:1 , Id of the analyte group "____________ ", string , 1:1 , Id of the absorption model "____________ ", :ref:`parameterSet` , 1:1 , The absorption parameters .... :dfs:`0091` A *formulationAndRoutes* shall contain at least one *formulationAndRoute*, and only *formulationAndRoute* tags. .... :dfs:`0092` A *formulationAndRoute* shall contain one *formulationAndRouteId*, one *formulation*, one *administrationName*, one *administrationRoute*, one *absorptionModel*, one *dosages*, one *absorptionParameters*. .... :dfs:`0093` A *formulationAndRouteId* shall be a non-empty string. .... :dfs:`0094` A *formulation* shall be any of the following: - undefined - parenteralSolution - oralSolution - test .... :dfs:`0095` An *administrationName* is any string. .... :dfs:`0096` An *administrationRoute* shall be any of the following: - undefined - intramuscular - intravenousBolus - intravenousDrip - nasal - oral - rectal - subcutaneous - sublingual - transdermal - vaginal .... :dfs:`0097` An *absorptionModel* shall be any of the following: - undefined - bolus - extra - extra.lag - infusion .... :dfs:`0098` An *absorptionParameters* shall only contain *parameterSetAnalyteGroup* tags. .... :dfs:`0099` A *parameterSetAnalyteGroup* shall contain one *analyteGroupId*, one *absorptionModel*, and one *parameterSet*. .... :dfs:`0100` In a *parameterSetAnalyteGroup*, the *analyteGroupId* shall contain an Id that corresponds to an existing *groupId* in an *ananyteGroup*. .... :dfs:`0101` In a *parameterSetAnalyteGroup*, the *absorptionModel* shall be a valid absorption model Id. :dfs:`0159` In a *formulationAndRoute*, each *parameterSetAnalyteGroup* shall be using a different *analyteGroupId*. It means there should not be two groups of parameters for the same analyte group. Dosages ------- .. csv-table:: dosages content :header: "Tag name", "Format", "Occ.", "Description" :widths: 15, 10, 5, 30 " ", , , "Available dosages associated with a formulation and route" "____ ", , 0:1 , "A potential standard treatment" "________ ", bool, 1:1 , "Has the treatment a fixed duration?" "________ ", , 0:1 , "The duration of the fixed duration" "____________ ", , 1:1 , "The unit of the duration" "____________ ", , 1:1 , "The duration value" "____ ", , 1:1 , "List of analyte conversions" "________ ", , 1:∞ , "Conversion from the quantity of drug to the quantity of analyte" "____________ ", string , 1:1 , "The Id of the analyte" "____________ ", double , 1:1 , "The factor to be multiplied to the drug quantity to obtain the analyte quantity" "____", boolean, 0:1, "Is a loading dose recommended if the current dosage is too low?" "____", boolean, 0:1, "Is a rest period recommended if the current dosage is too high?" "____ ", :ref:`availableDoses` , 1:1 , "Available doses" "____ ", :ref:`availableIntervals` , 1:1 , "Available intervals" "____ ", :ref:`availableInfusions` , 0:1 , "Available infusion times" "____ ", :ref:`comments` , 1:1 , "Comments about the dosages" .... :dfs:`0102` A *dosages* shall have 0 or 1 *standardTreatment*, 0 or 1 *isLoadingDoseRecommended*, 0 or 1 *isRestPeriodRecommended*, one *analyteConversions*, one *availableDoses*, one *availableIntervals*, 0 or 1 *availableInfusions* and one *comments*. If *absorptionModel* is *infusion*, there shall be one *availableInfusions*, else it shall not be present. .... :dfs:`0103` A *standardTreatment* shall have one *isFixedDuration*. .... :dfs:`0104` In a *standardTreatment*, if *isFixedDuration* is *true*, then there shall be a *timeValue*. .... :dfs:`0105` A *timeValue* shall contain one *unit* and one *value*. .... :dfs:`0106` In a *timeValue*, the *unit* shall be a valid :ref:`drugfile_time_unit`. .... :dfs:`0107` In a *timeValue*, the *value* shall be a valid positive floating point number. .... :dfs:`0108` An *analyteConversions* shall contain at least one *analyteConversion*, and only *analyteConversion* tags. .... :dfs:`0109` An *analyteConversion* shall contain one *analyteId* and one *factor*. .... :dfs:`0110` In an *analyteConversion*, the *analyteId* shall be an identifier existing in an *activeMoiety* *analyteId*. .... :dfs:`0111` A *factor* shall be a valid floating point number in the interval [0, 1]. .... :dfs:`0112` An *availableDoses* is an *availableValues*. .... :dfs:`0113` In an *availableDoses*, the *unit* shall be a :ref:`drugfile_weight_unit`. .... :dfs:`0114` An *availableIntervals* is an *availableValues*. .... :dfs:`0115` In an *availableIntervals*, the *unit* shall be a :ref:`drugfile_time_unit`. .... :dfs:`0116` An *availableInfusions* is an *availableValues*. .... :dfs:`0117` In an *availableInfusions*, the *unit* shall be a :ref:`drugfile_time_unit`. AvailableValues --------------- The available values are used for the doses, intervals and infusions. In the following example *availableValues* would be replaced by *availableDoses*, *availableInfusions* or *availableIntervals*. .. csv-table:: availableValues content :header: "Tag name", "Format", "Occ.", "Description" :widths: 15, 10, 5, 30 " ", , , "Available values" "____ ", , 1:1 , "Unit of the values" "____ ", :ref:`stdAprioriValue` , 1:1 , "Default value" "____ ", , 0:∞ , "Available values represented as a range" "________ ", :ref:`stdAprioriValue` , 1:1 , "Starting value of the range" "________ ", :ref:`stdAprioriValue` , 1:1 , "Ending value of the range" "________ ", :ref:`stdAprioriValue` , 1:1 , "Step to be applied between from and to" "____ ", , 0:1 , "A list of fixed values" "________ ", double , 1:1 , "A value" .... :dfs:`0118` An availableValues shall contain one *unit*, one *default*, any number of *rangeValues*, and 0 or 1 *fixedValues*. .... :dfs:`0119` In an availableValues, *default* is an :ref:`drugfile_stdapriorivalue`. .... :dfs:`0120` A *rangeValues* shall contain one *from*, one *to*, and one *step*. .... :dfs:`0121` In a *rangeValues*, *from*, *to*, and *step* are :ref:`drugfile_stdapriorivalue`. .... :dfs:`0122` In a *rangeValues*, *from* shall have a default value smaller than *to*. .... :dfs:`0123` In a *rangeValues*, *step* shall have a strictly positive floating point number as default value. .... :dfs:`0156` In a *rangeValues*, for the default values, *step* shall be strictly smaller than *to* - *from*. .... :dfs:`0124` A *fixedValues* shall only contain *value* tags. .... :dfs:`0125` In a *fixedValues*, a *value* shall contain a valid floating point number. Time considerations ------------------- .. csv-table:: timeConsiderations content :header: "Tag name", "Format", "Occ.", "Description" :widths: 15, 10, 5, 30 " ", , , Some time considerations "____ ", halfLife , 1:1 , Half life of the drug "_______ ", , 1:1 , Time unit of the half life "_______ ", :ref:`stdAprioriValue` , 1:1 , value of the half life "_______ ", , 1:1 , Number of half lifes to reach steady state "_______ ", :ref:`comments` , 1:1 , "Comments about the half life" "____ ", outdatedMeasure , 1:1 , Indication about the relevance of a measure "_______ ", string , 1:1 , Time unit "_______ ", :ref:`stdAprioriValue` , 1:1 , Time after which a measure shall be considered as irrelevant "_______ ", :ref:`comments` , 1:1 , "Comments about the outdate measure fields" .... :dfs:`0126` A *timeConsiderations* shall contain one *halfLife* and one *outdatedMeasure*. .... :dfs:`0127` A *halfLife* shall contain one *unit*, one *duration*, one *multiplier* and one *comments*. .... :dfs:`0128` In a *halfLife*, the *unit* shall be a valid :ref:`drugfile_time_unit`. .... :dfs:`0129` A *duration* is a :ref:`drugfile_stdapriorivalue`. .... :dfs:`0130` A *duration* default value shall be positive. .... :dfs:`0131` A *multiplier* shall be a positive floating point number. .... :dfs:`0132` An *outdatedMeasure* shall contain one *unit*, one *duration* and one *comments*. .... :dfs:`0133` In an *outdatedMeasure*, the *unit* shall be a :ref:`drugfile_time_unit`. Parameters ---------- .. csv-table:: parameterSet content :header: "Tag name", "Format", "Occ.", "Description" :widths: 15, 10, 5, 30 " ", , 1:1 , The absorption parameters "____ ", :ref:`parameters` , 1:1 , List of parameters "________ ", :ref:`parameter` , 0:∞ , A parameter "____ ", :ref:`correlations` , 1:1 , Correlations between absorption parameters or between absorption and disposition parameters "________ ", :ref:`correlation` , 0:∞ , Correlations between absorption parameters or between absorption and disposition parameters .... :dfs:`0134` A *parameterSet* shall contain one *parameters* and one *correlations*. .... :dfs:`0135` A *parameters* shall contain only *parameter* tags. .... :dfs:`0136` A *correlations* shall contain only *correlation* tags. Parameter structure: .. csv-table:: parameter content :header: "Tag name", "Format", "Occ.", "Description" :widths: 15, 10, 5, 30 " ", , , "A Pk parameter" "____ ", string , 1:1 , "Id of the parameter" "____ ", string , 1:1 , "the unit of the parameter value" "____ ", :ref:`stdAprioriValue` , 1:1 , "The parameter value and its optional apriori computation" "____ ", string , 1:1 , "Between Subject Variability (BSV) " "________ ", :ref:`bsvType` , 1:1 , "Type of BSV" "________ ", , 0:1 , "A list of standard deviations" "____________ ", double , 1:∞ , "A standard deviation" "____ ", , 1:1 , "A potential validation of the parameter value" "________ ", , 1:1 , "A translated list of error messages" "____________ ", string , 1:∞ , "An error message, translated in a specific language" "________ ", :ref:`operation` , 1:1 , "A formula to check the validity of the parameter" "________ ", :ref:`comments` , 1:1 , "Comments about the validation" "____ ", :ref:`comments` , 1:1 , "Comments about the parameter" .... :dfs:`0137` A *parameter* shall contain one *parameterId*, one *unit*, one *parameterValue*, one *bsv*, one *validation*, and one *comments*. .... :dfs:`0138` A *parameterId* shall be a non-empty string. .... :dfs:`0157` A *parameterId* shall be a parameter Id present in the selected Pk model. The list of Pk models is as follows, with the potential parameter Ids. It is to be noted that not all parameters are mandatory, as the elimination parameters depend on the formulation and route. .. csv-table:: pkModelParameters :header: "pkModelId", "Parameters" :widths: 15, 30 linear.1comp.macro , "CL, V, Ka, F, Tlag" linear.2comp.macro , "CL, V1, V2, Ka, F, Q, Tlag" linear.2comp.erlang1.macro, "CL, V1, V2, Q, Ktr, F" linear.2comp.erlang1.micro, "K12, K21, V1, Ke, Ktr, F" linear.2comp.erlang2.macro, "CL, V1, V2, Q, Ktr, F" linear.2comp.erlang2.micro, "K12, K21, V1, Ke, Ktr, F" linear.2comp.erlang3.macro, "CL, V1, V2, Q, Ktr, F" linear.2comp.erlang3.micro, "K12, K21, V1, Ke, Ktr, F" linear.2comp.erlang4.macro, "CL, V1, V2, Q, Ktr, F" linear.2comp.erlang4.micro, "K12, K21, V1, Ke, Ktr, F" linear.2comp.erlang5.macro, "CL, V1, V2, Q, Ktr, F" linear.2comp.erlang5.micro, "K12, K21, V1, Ke, Ktr, F" linear.2comp.erlang6.macro, "CL, V1, V2, Q, Ktr, F" linear.2comp.erlang6.micro, "K12, K21, V1, Ke, Ktr, F" michaelismenten.1comp, "F, Ka, V, Km, Vmax" michaelismenten.2comp.macro, "V1, Km, Vmax, V2, Q, F, Ka, Tlag" michaelismenten.2comp.micro, "V1, Km, Vmax, K12, K21, F, Ka, Tlag" michaelismenten.2comp.vmaxamount.macro, "V1, Km, Vmax, V2, Q, F, Ka, Tlag" michaelismenten.2comp.vmaxamount.micro, "V1, Km, Vmax, K12, K21, F, Ka, Tlag" michaelismenten.enzyme.1comp, "V, Km, Vmax, F, Ka, Kenz, Emax, ECmid, EDmid, DoseMid, Fmax, NN, MTT, AllmCL" .... :dfs:`0139` A *parameterValue* is a :ref:`drugfile_stdapriorivalue`. .... :dfs:`0140` A *bsv* shall contain one *bsvType* and one *stdDevs*. .... :dfs:`0141` A *bsvType* is any of the following: - none - normal - lognormal - proportional - exponential - additive - logit .... :dfs:`0142` An *stdDevs* shall contain zero *stdDev* if the *bsvType* is *none*, one *stdDev* else, and shall only contain *stdDev* tags. .... :dfs:`0143` An *stdDev* shall be a valid positive floating point number. Correlation structure: +---------------+--------+-----+-----------------------------------------+ | Tag name | Format | Occ.| Description | +===============+========+=====+=========================================+ | | | 0:∞ | Description of the correlation | +---------------+--------+-----+-----------------------------------------+ |____ | string | 1:1 | The first parameter's ID | +---------------+--------+-----+-----------------------------------------+ |____ | string | 1:1 | The second parameter's ID | +---------------+--------+-----+-----------------------------------------+ |____ | double | 1:1 | The correlation's value | +---------------+--------+-----+-----------------------------------------+ |____ | | 1:1 | Comments about the correlation | +---------------+--------+-----+-----------------------------------------+ .... :dfs:`0145` A *correlation* shall contain one *param1*, one *param2*, one *value*, and one *comments*. .... :dfs:`0146` A *param1* shall reference an existing parameter Id of the model used. .... :dfs:`0147` A *param2* shall reference an existing parameter Id of the model used. .... :dfs:`0148` In a *correlation*, *param1* and *param2* shall not be equal. .... :dfs:`0149` In a *correlation*, *value* shall be a valid floating point number in the interval [-1,1]. .. _drugfile_stdapriorivalue: StdAprioriValue --------------- The StdAprioriValue is used at various places in the drug file. .... :dfs:`0150` An *stdAprioriValue* shall contain one *standardValue*, and 0 or 1 *aprioriComputation*. .... :dfs:`0151` A *standardValue* shall be a floating point number. .... :dfs:`0152` An *aprioriComputation* is an :ref:`drugfile_operation`. .. _drugfile_unit: Unit ---- .. _drugfile_weight_unit: Weight unit ^^^^^^^^^^^ A valid weight unit is any of the following: - kg - g - mg - ug - µg - ng .. _drugfile_concentration_unit: 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 .. _drugfile_temperature_unit: Temperature unit ^^^^^^^^^^^^^^^^ A valid temperature unit is any of the following: - celsius .. _drugfile_flowrate_unit: Flow rate unit ^^^^^^^^^^^^^^ A valid flow rate unit is any of the following: - ml/min - l/min - ml/h - l/h .. _drugfile_moleconcentration_unit: Mole Concentration unit ^^^^^^^^^^^^^^^^^^^^^^^ A valid mole concentration unit is any of the following: - kg/mol - g/mol - mg/mol - ug/mol - µg/mol - ug/umol - µg/umol - g/umol - kg/umol .. _drugfile_time_unit: Time unit ^^^^^^^^^ A valid time unit is any of the following: - y - month - d - h - min - s .. _drugfile_lenght_unit: Length unit ^^^^^^^^^^^ A valid length unit is any of the following: - m - cm - dm - mm - ft - in .. _drugfile_molarmass_unit: Molar mass ^^^^^^^^^^ A valid molar mass unit is any of the following: - g/mol - ug/mol - kg/mol - kg/umol .. _drugfile_concentrationtime_unit: 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 .. _drugfile_empty_unit: Empty unit ^^^^^^^^^^ A valid absence of unit is any of the following: - empty string - "-" Removed rules ------------- The following rules have been removed. .... :dfs:`0153` In a *targetValues*, the default value of *inefficacyAlarm* shall be smaller than the default value of *toxicityAlarm*. Removed because redundant with other rules concerning inefficacy and toxicity.