Structured dosage model

Introduction

The structured dosage is inspired by the FHIR terminologies described here: https://www.hl7.org/fhir/

Dosage forms

Behavior

Two terminologies exist for the galenic form: FORM and BASE_FORM

The FORM terminology comes from a list provided by the European Directorate for the Quality of Medicines (EDQM). These complex dosage forms are generally detected by the prescription scan, as well as the corresponding BASE_FORM, the list of which also comes from the EDQM.

The attributes specific to these entities are of the form:

Name	Type	Description
category	`string`	`MEDICATION`
designation	`string`	String detected as quantity
entity_type	`string`	`FORM`
codings	`Codings`	Object containing 2 arrays of objects: `FORM` and `BASE_FORM`

Codings

Name	Type	Description
FORM	`array`	Array of objects `NELEntity`
BASE_FORM	`array`	Array of objects `NELEntity`

NELEntity

Name	Type	Description
code	`string`	Galenic form code
label	`string`	The attribute to use to match in the database
terminology	`string`	`FORM` or `BASE_FORM`
cosine_similarity	`number`	1 (because only exact matches)

Response

{
   "begin_offset": 2,
   "category": "MEDICATION",
   "codings": {
     “FORM”: [
       {
         "code": "compressed",
         "cosine_similarity": 1,
         "label": "tablet",
         "terminology": "FORM"
       }
     ],
     "BASE_FORM": [
       {
         "code": "Compressed",
         "cosine_similarity": 1,
         "label": "Compressed",
         "terminology": "BASE_FORM"
       }
     ]
   },
   "designation": "cpr",
   "end_offset": 5,
   "entity_type": "FORM"
}

Quantities

Generally speaking, a general number, whether or not linked to a unit, is called a quantity.

When this quantity refers to the quantity:

of a molecule in a tablet, capsule, etc. of medicine, it is called the force (strength).
of medication per dose, it is called the dose (also dose).

Behavior

If the quantity is a dose or a quantity, when detected, it is returned with the attributes:

Attribute	Type	Description
`as_needed`	`NERLAsNeeded`	Optional.
`category`	`string`	Always `MEDICATION` (these quantities are always related to the use of a medication).
`designation`	`string`	Detected string as quantity.
`entity_type`	`string`	Always `QUANTITY`.
`begin_offset`	`int`	Position of the first character in the original string.
`end_offset`	`int`	Position of the last character.
`quantity_and_rate`	`QuantityOrRate`
`timing`	`Timing`	For entities of subtype DOSE.

NERLAsNeeded

Attribute	Type	Description
`as_needed`	`bool`	If a text starts with “si” (if needed, if in pain, etc.).
`as_needed_for`	`string`	The corresponding text.

QuantityOrRate

Attribute	Type	Description
`value`	`float`	Detected quantity of units.
`unit`	`string`	Normalized unit (among a list of entities).
`type`	`string`	`"QUANTITY"`, `"DOSE"`, or `"STRENGTH"`.
`code`	`string`	Value of the detected code in the `system`
`system`	`string`	Terminology used
`rate`	`Rate`	When a fraction is detected, the `rate` attribute is added to the `value` attribute with the values and units of the numerator and denominator.

The value and unit attributes are non-empty only in the case where the value does not correspond to a ratio (like a concentration (mg/L) etc). Otherwise, both of these attributes are empty, and the rate attribute is used instead.

The units can come both from the international system or from SNOMED units (including the UK version) such as “tablet”, “ampoule”. Missing units have also been added with the prefix 94329990001. The full list of units used is available at https://api.preprod.posos.co/nerl/dose_units?lang=fr organized by system.

Example

{
  "query": "2 tablets",
  "preprocessed_query": "2 tablets",
  "entities": [
    {
      "category": "MEDICATION",
      "designation": "2 tablets",
      "begin_offset": 0,
      "end_offset": 11,
      "entity_type": "QUANTITY",
      "quantity_and_rate": {
        "value": 2.0,
        "unit": "tablet(s)",
        "type": "DOSE",
        "code": "428673006",
        "system": "http://snomed.info/sct"
      }
    }
  ]
}

When a character string is composed of a number and an international system unit but does not directly follow a drug, it is detected as QUANTITY (we do not know a priori if it is a STRENGTH or DOSE):

{
  "query": "500mg",
  "preprocessed_query": "500mg",
  "dosage_string": "500 mg",
  "entities": [
    {
      "begin_offset": 0,
      "category": "MEDICATION",
      "designation": "500 mg",
      "end_offset": 6,
      "entity_type": "QUANTITY",
      "quantity_and_rate": {
        "unit": "mg",
        "code": "mg",
        "system": "https://ucum.org",
        "value": 500.0,
        "type": "QUANTITY"
      }
    }
  ]
}

When a fraction is detected, the rate attribute is added to the value attribute with the values and units of the numerator and denominator.

Example

{
  "query": "50 mg/20 mL",
  "preprocessed_query": "50 mg / 20 ml",
  "dosage_string": "50 mg / 20 ml",
  "entities": [
    {
      "begin_offset": 0,
      "category": "MEDICATION",
      "designation": "50 mg / 20 ml",
      "end_offset": 13,
      "entity_type": "QUANTITY",
      "quantity_and_rate": {
        "missed": {
          "numerator": 50.0,
          "denominator": 20.0,
          "numerator_unit": "mg",
          "numerator_unit_code": "mg",
          "denominator_unit": "mL",
          "denominator_unit_code": "mL",
          "numerator_system": "https://ucum.org",
          "denominator_system": "https://ucum.org"
        },
        "type": "QUANTITY"
      }
    }
  ]
}

When a character string recognized as a drug is followed by a number (with or without unit) and this number corresponds to a known strength of the drug, a strength attribute is added to the corresponding drug entity. This attribute is a list of QuantityOrRate.

Exemple

{
  "query": "ENTRESTO 24/26 mg",
  "preprocessed_query": "entresto 24 / 26 mg",
  "posology_string": "",
  "entities": [
    {
      "begin_offset": 0,
      "category": "MEDICATION",
      "codings": {},
      "designation": "entresto",
      "end_offset": 8,
      "entity_type": "DRUG",
      "strength": [
        {
          "unit": "mg",
          "code": "mg",
          "system": "https://ucum.org",
          "value": 24.0,
          "type": "STRENGTH"
        },
        {
          "unit": "mg",
          "code": "mg",
          "system": "https://ucum.org",
          "value": 26.0,
          "type": "STRENGTH"
        }
      ],
      "strength_designation": "24 / 26 mg",
      "selected_strength": "24 mg/26 mg",
      "prescripted_drug": true
    }
  ]
},
 
// Lorsque les unités sont différentes, on considère qu'il n'y a qu'un seul ingrédient
// On remplit alors l'attribut rate de strength
{
  "query": "ACUPAN 20 mg/2 mL",
  "preprocessed_query": "acupan 20 mg / 2 ml",
  "posology_string": "",
  "entities": [
    {
      "begin_offset": 0,
      "category": "MEDICATION",
      "designation": "acupan",
      "end_offset": 6,
      "entity_type": "DRUG",
      "strength": [
        {
          "rate": {
            "numerator": 20.0,
            "denominator": 2.0,
            "numerator_unit": "mg",
            "numerator_unit_code": "mg",
            "denominator_unit": "mL",
            "denominator_unit_code": "mL",
            "numerator_system": "https://ucum.org",
            "denominator_system": "https://ucum.org"
          },
          "type": "STRENGTH"
        }
      ],
      "strength_designation": "20 mg / 2 ml",
      "selected_strength": "20 mg/2 ml",
      "prescripted_drug": true
    }
  ]
}

Rate

Attribut	Type	Description
`numerator`	`float`	Numerator of the fraction.
`denominator`	`float`	Denominator of the fraction.
`numerator_unit`	`string`	Normalized unit of the numerator
`denominator_unit`	`string`	Normalized unit of the denominator
`numerator_system`	`string`	System of the numerator
`denominator_system`	`string`	System of the denominator
`numerator_unit_code`	`string`	Code of the numerator
`denominator_unit_code`	`string`	Code of the denominator

Timing

Behavior

Entities of type QUANTITY and subtype DOSE necessarily have a timing attribute whose values are as follows. ENTITIES of type FREQUENCY are deprecated.

Attribute	Type	Description
`frequency`	`int`	Frequency of taking the medication (if `frequency_max` exists, `frequency` corresponds to the minimum frequency).
`frequency_max`	`int`	Maximum frequency.
`period`	`int`	Corresponds to the period during which `frequency` takes take place.
`period_unit`	`string`	Unit of the period.
`period_max`	`int`	Corresponds to the maximum period.
`bounds_duration`	`BoundsDuration`	Duration of treatment.
`time_of_day`	`string[]`	Hours of the day when the treatment must be taken (8 a.m., 12:30 p.m., etc.).
`day_of_week`	`string[]`	Days of the week the treatment should be taken (Mon, Tue, Wed, Thu, Fri, Sat, Sun).
`when`	`string[]`	Times of the day at which the processing takes place (the meanings of the codes are explained on this site https://www.hl7.org/fhir/valueset-event-timing.html#definition).
`offset`	`int`	Time interval between taking and when, in minutes.
`sequence`	`int`	Number starting from 0 indicating the succession of dosages (2 tabs for one week then 1 tab for 1 month).
`frequency_texts`	`string[]`	List of different texts corresponding to frequencies.
`bounds_duration_text`	`string`	Text corresponding to the processing duration.

Example

{
  "query": "1 cpr 3 to 4 times every 6 hours for 2 to 3 weeks",
  "preprocessed_query": "1 cpr 3 to 4 times every 6 hours for 2 to 3 weeks",
  "dosology_string": "1 cpr 3 to 4 times every 6 hours for 2 to 3 weeks",
  "entities": [
    {
      "begin_offset": 0,
      "category": "MEDICATION",
      "designation": "1 cpr",
      "end_offset": 5,
      "entity_type": "QUANTITY",
      "quantity_and_rate": {
        "unit": "tablet(s)",
        "code": "428673006",
        "system": "http://snomed.info/sct",
        "value": 1,
        "type": "DOSE"
      },
      "timing": {
        "frequency": 3,
        "frequency_max": 4,
        "period": 6,
        "period_unit": "hour",
        "bounds_duration": {
          "unit": "week",
          "value": 2,
          "max_value": 3
        },
        "frequency_texts": ["3 to 4 times every 6 hours"],
        "bounds_duration_text": "for 2 to 3 weeks"
      }
    },
    {
      "begin_offset": 2,
      "category": "MEDICATION",
      "codings": {},
      "designation": "cpr",
      "end_offset": 5,
      "entity_type": "FORM"
    }
  ]
}

BoundsDuration

Attribute	Type	Description
`unit`	`string`	Unit of treatment duration.
`value`	`float`	Duration (minimum) of treatment.
`max_value`	`float`	Maximum duration of treatment.

Duration

Behavior

The durations of application of a treatment are coded by objects whose entity_type is DURATION. Frequency entities are therefore coded by the following attributes:

Attribute	Type	Description
`category`	`string`	`MEDICATION` (durations are always linked to the use of a medication)
`designation`	`string`	string detected as duration
`entity_type`	`string`	`DURATION`
`begin_offset`	`int`	position of 1st character in original string
`end_offset`	`int`	position of last character
`description`	`object`	object containing the description of the duration
`duration`	`object`	object containing the duration of the take (minimum duration if `value_max` exists), and the unit of the duration
`value`	`float`	duration of intake
`value_max`	`float`	maximum duration of intake
`unit`	`string`	unit of duration

{
   "query": "apply for 3 minutes on the wound",
   "preprocessed_query": "apply for 3 minutes on the wound",
   "posology_string": "for 3 minutes the wound",
   "entities": [
     {
       "begin_offset": 35,
       "category": "CONDITION",
       "codings": {
         “MEDDRA”: [
           {
             "code": "10052428",
             "cosine_similarity": 1,
             "label": "Wound",
             "terminology": "MEDDRA",
             "level": "PT"
           }
         ]
       },
       "designation": "wound",
       "end_offset": 40,
       "entity_type": "CONDITION"
     }
   ]
}

Administrative information about the prescription

The RPPS and the prescription date are detected in an administrative field (at the end of the NERL outputs, outside of entities) which has the following format:

record:
- identify: the RPPS number
authoredOn:
- date: the raw date
- formatted_date: the date in YYYY/mm/dd format

Patient observations

Physiological information on the patient is detected by the NERL and grouped in an observations field which contains the list. The observations are NERLEntity with all the parameters associated with them. They have an additional observation field which contains the details of the observation:

code: LOINC code of the observation in question (Body weight, Body height, Body Mass Index (BMI), Age)
value: value of the observation
unit: unit

{
  "begin_offset": 10,
  "category": "PATIENT_INFORMATION",
  "designation": "34 kg",
  "end_offset": 15,
  "entity_type": "OBSERVATION",
  "observation": {
    "code": "Body weight",
    "value": 34.0,
    "unit": "kg"
  }
}

NB: Height is only detected in cm, ages only in years. If a height and a BMI are indicated, the weight is calculated from these two pieces of information.

FHIR prescription model