Alertes de posologie

Introduction

La requête getDosageAlertpermet de récupérer la liste des alertes de posologies qui sont déclenchées par la liste de médicaments et les instructions de posologies entrés en paramètres en l'appel à l'API.

Fonctionnement de l'API

L'utilisateur de l'API doit d'abord spécifier les types d'alertes désirés en utilisant le champ type ainsi que les requêtes de médication via MedicationRequest, où chaque requête correspond à un médicament spécifique. Les codes des médicaments sont à indiquer dans les champs clinicalDrug, brandedDrug ou packagedDrug. Le modèle de données est détaillé plus bas.

Pour chaque médicament, l'utilisateur doit fournir des instructions de dosage via le paramètre dosageInstructions. Il est possible de définir plusieurs instructions pour refléter différentes phases de traitement. Par exemple, une instruction peut indiquer de prendre 100 mL pendant une semaine, suivie d'une instruction pour prendre 200 mL pendant deux semaines. Chaque instruction doit être associée à un numéro de séquence pour clarifier l'ordre des phases.

Si plusieurs instructions de dosage sont fournies sans numéro de séquence, ou si plusieurs instructions partagent le même numéro de séquence, elles seront interprétées comme devant être administrées simultanément. Cette configuration est particulièrement utile pour les traitements nécessitant des prises à différents moments de la journée, comme prendre deux comprimés le matin et un le soir. Pour ces cas, la durée totale du traitement doit être la même pour toutes les instructions partageant un numéro de séquence identique.

Comment spécifier le médicament ?

Lors de la formulation d'une requête, il est nécessaire de spécifier un médicament et d'y associer des instructions de dosage.

Pour définir le médicament concerné, on utilise l'objet DrugInput qui comprend les champs clinicalDrug, brandedDrug et packagedDrug. Chacun de ces champs représente un type de codage différent.

Il est crucial de remplir uniquement un des champs par DrugInput, car un DrugInput ne peut pas être simultanément un clinicalDrug et un packagedDrug. Il est également essentiel de compléter le champ terminology et de fournir soit label, soit code. Si les champs label et code sont tous deux renseignés, seul le code sera utilisé pour le traitement des données.

Voici des exemples de paramètres d'entrée pour la partie médicament:

{
  "drug": {
    "clinicalDrug": { "code": "MV00003894", "terminology": "posos" }
  }
}

{
  "drug": { "brandedDrug": { "code": "63934499", "terminology": "cis" } }
}

Les terminologies qui sont utilisées pour requêter les différents types de médicaments font parties de listes pré-définies:

Comment spécifier une instruction de prise ?

L'objet DosageInstruction est un objet complexe qui permet de modéliser une prise de médicament de la façon la plus complète possible. Le modèle complet est présenté ci-dessous.

Voici quelques exemples de modèlisation de prises:

Prendre 3 comprimés par jour

{
  "dosageInstructions": [
    {
      "doseAndRate": {
        "doseQuantity": {
          "code": "428673006",
          "unit": "comprimé(s)",
          "system": "https://snomed.org",
          "value": 3
        }
      },
      "timing": {
        "repeat": {
          "frequency": 1,
          "period": 1,
          "periodUnit": "d"
        }
      }
    }
  ]
}

Prendre 1 comprimé 3 fois par jour

{
  "dosageInstructions": [
    {
      "doseAndRate": {
        "doseQuantity": {
          "code": "428673006",
          "unit": "comprimé(s)",
          "system": "https://snomed.org",
          "value": 1
        }
      },
      "timing": {
        "repeat": {
          "frequency": 3,
          "period": 1,
          "periodUnit": "d"
        }
      }
    }
  ]
}

Prendre 2 comprimés au réveil, au déjeuner et au dîner

{
  "dosageInstructions": [
    {
      "doseAndRate": {
        "doseQuantity": {
          "code": "428673006",
          "unit": "comprimé(s)",
          "system": "https://snomed.org",
          "value": 2
        }
      },
      "timing": {
        "repeat": {
          "frequency": 3,
          "period": 1,
          "periodUnit": "d",
          "when": ["WAKE", "CD", "CV"]
        }
      }
    }
  ]
}

Prendre 1 à 2 comprimés par jour pendant 2 semaines

{
  "dosageInstructions": [
    {
      "doseAndRate": {
        "doseRange": {
          "low": {
            "code": "428673006",
            "unit": "comprimé(s)",
            "system": "https://snomed.org",
            "value": 1
          },
          "high": {
            "low": {
              "code": "428673006",
              "unit": "comprimé(s)",
              "system": "https://snomed.org",
              "value": 2
            }
          }
        }
      },
      "timing": {
        "repeat": {
          "period": 1,
          "periodUnit": "d",
          "boundsDuration": {
            "value": 2,
            "code": "wk",
            "system": "ucum"
          }
        }
      }
    }
  ]
}

Quantité maximale par dose

Pour activer les alertes concernant la quantité maximale par dose, il est nécessaire d'ajouter le paramètre max_quantity_per_dose dans le champ types.

Afin de déterminer si cette alerte doit être déclenchée, l'utilisateur doit fournir les valeurs de doseAndRate.doseRange et doseAndRate.doseQuantity.value dans les requêtes de médication.

Lorsque plusieurs instructions de dosage sont fournies séquentiellement, l'API évalue les alertes pour chaque séquence de manière indépendante. Les résultats indiquent les séquences spécifiques pour lesquelles une alerte a été déclenchée.

Lorsque plusieurs instructions de dosage sont fournies sans numéro de séquence unique ou partagent le même numéro de séquence, elles sont considérées comme devant être administrées simultanément. Ainsi, les quantités indiquées dans chaque instruction appartenant à la même séquence sont cumulées. Cette somme est ensuite comparée à la limite maximale autorisée par dose, conformément aux spécifications de l'alerte.

Voici un exemple de requête de Quantité maximale par dose valide:

query GetDosageAlert($medicationRequests: [MedicationRequestInput!]!,$types: [DosageAlertType!]) {
  getDosageAlert(medicationRequests: $medicationRequests, types: $types){
    drug {
      clinicalDrug {
        label
        code
        terminology
      }
    }
    doseAlert {
      text
      type
      value
      unit
      code
      system
    }
    alertDetected
  }
}

[
  {
    "drug": {
      "clinicalDrug": {
        "label": "OVITRELLE 250 microgrammes, solution injectable en stylo prérempli",
        "code": "NV68822746",
        "terminology": "posos"
      }
    },
    "doseAlert": {
      "text": "Quantité maximale par prise",
      "type": "MAX_QUANTITY_PER_DOSE",
      "value": 250,
      "unit": "microgram",
      "code": "ug",
      "system": "ucum"
    },
    "alertDetected": true
  }
]

Quantité maximale par 24 heures

Pour activer les alertes concernant la quantité maximale par 24 heures, il est nécessaire d'ajouter le paramètre max_quantity_per_24_hours dans le champ types.

Pour déclencher cette alerte, l'utilisateur peut fournir plusieurs informations:

• Soit remplir le champ maxDosePerPeriod dans les dosageInstructions.
• Soit remplir les champs timing.repeat.frequency, timing.repeat.period ou timing.repeat.periodMax, timing.repeat.periodUnit ainsi que doseAndRate.quantityou doseAndRate.doseRange. Il faut une mesure de la quantité de traitement à administrer (via doseAndRate) et une mesure de fréquence par unité de temps (via timing.repeat).

Le fonctionnement de l'analyse est le même que pour la quantité maximale par dose. Le déclenchement ou non de l'alerte est calculé pour chaque dosageInstructions avec un numéro de séquence différent.

Voici un exemple de requête de Quantité maximale par 24 heures, avec les paramètres ci dessous. Ici, l'utilisateur utilise les champs frequency, period et doseQuantity pour permettre de calculer la dose maximale en 24 heures.

{
  "types": ["MAX_QUANTITY_PER_24_HOURS"],
  "medicationRequests": [
    {
      "drug": {
        "clinicalDrug": { "code": "MV00005090", "terminology": "posos" }
      },
      "dosageInstructions": [
        {
          "sequence": 0,
          "timing": {
            "repeat": {
              "boundsDuration": {
                "system": "http://hl7.org/fhir/ValueSet/duration-units",
                "value": 7,
                "code": "d"
              },
              "frequency": 4,
              "period": 1,
              "periodUnit": "d",
              "when": ["MORN", "NOON", "EVE", "HS"]
            }
          },
          "doseAndRate": {
            "doseQuantity": {
              "value": 1,
              "system": "http://snomed.info/sct",
              "code": "426148002"
            }
          }
        },
        {
          "sequence": 1,
          "timing": {
            "repeat": {
              "boundsDuration": {
                "system": "http://hl7.org/fhir/ValueSet/duration-units",
                "value": 7,
                "code": "d"
              },
              "frequency": 3,
              "period": 1,
              "periodUnit": "d",
              "when": ["MORN", "NOON", "EVE"]
            }
          },
          "doseAndRate": {
            "doseQuantity": {
              "value": 1,
              "system": "http://snomed.info/sct",
              "code": "426148002"
            }
          }
        }
      ]
    }
  ]
}

Voici un autre exemple où l'utilisateur utilise le champ maxDosePerPeriod:

{
  "types": ["MAX_QUANTITY_PER_24_HOURS"],
  "medicationRequests": [
    {
      "drug": {
        "clinicalDrug": {
          "code": "MV00002665",
          "terminology": "posos"
        }
      },
      "dosageInstructions": [
        {
          "maxDosePerPeriod": {
            "numerator": {
              "value": 11,
              "system": "http://snomed.info/sct",
              "code": "428673006"
            },
            "denominator": {
              "value": 1,
              "system": "http://hl7.org/fhir/ValueSet/duration-units",
              "code": "d"                                                  
            }
          }
        }
      ]
    }
  ]
}

Quantité minimale par 24 heures

La récupération des alertes de quantité minimale par 24 heures fonctionne de manière similaire à celle des alertes de quantité maximale. Lorsqu'une requête est envoyée au système, celui-ci évalue la quantité totale de médicament consommée par le patient sur une période de 24 heures. Si cette quantité est inférieure à la quantité minimale définie pour le médicament concerné, une alerte est générée pour informer le professionnel de santé. Cette alerte indique que la quantité de médicament prise est insuffisante pour atteindre l'efficacité thérapeutique attendue, ce qui peut nécessiter une réévaluation du plan de traitement du patient.

Pour permettre l'analyse des données d'entrées, il faut que certains champs soit remplis dans les instructions de prises:

• Les champs timing.repeat.frequency, timing.repeat.period ou timing.repeat.periodMax, timing.repeat.periodUnit ainsi que doseAndRate.quantityou doseAndRate.doseRange. Il faut une mesure de la quantité de traitement à administrer (via doseAndRate) et une mesure de fréquence par unité de temps (via timing.repeat). Si les champs timing.repeat.period et timing.repeat.periodMax sont remplis simultanément, on utilisera le champs timing.repeat.periodMax pour réaliser le calcul de la dose minimale prescrite en 24 heures.

Voici un exemple de données d'entrée:

{
  "types": ["MIN_QUANTITY_PER_24_HOURS"],
  "medicationRequests": [
    {
      "drug": {
        "clinicalDrug": { "code": "MV00003302", "terminology": "posos" }
      },
      "dosageInstructions": [
        {
          "timing": {
            "repeat": {
              "frequency": 1,
              "period": 1,
              "periodUnit": "d",
              "when": ["MORN"]
            }
          },
          "doseAndRate": {
            "doseQuantity": {
              "value": 2.5,
              "system": "https://ucum.org",
              "code": "mg"
            }
          }
        }
      ]
    }
  ]
}

Durée de traitement maximale

Le système d'alerte fonctionne en comparant la durée prescrite du traitement avec une durée maximale définie dans les paramètres de l'alerte. Si la durée prescrite dépasse la durée maximale autorisée, une alerte est générée pour informer le professionnel de santé. Cela permet d'intervenir et d'ajuster le traitement si nécessaire pour garantir la sécurité du patient.

Pour activer les alertes relatives à la durée maximale de traitement, il est impératif d'inclure le paramètre max_treatment_duration dans le champ types.

Afin de permettre l'analyse des données fournies, l'utilisateur doit renseigner l'un des champs suivants :

• timing.repeat.boundsRange.high pour spécifier la limite supérieure de la plage de temps.
• timing.repeat.boundsDuration pour définir une durée spécifique.
• timing.repeat.boundsPeriod, qui nécessite une date de début et une date de fin.

Lorsque plusieurs instructions de dosage sont présentes, chacune identifiée par un numéro de séquence distinct, la durée totale du traitement est calculée en additionnant les durées spécifiées pour chaque séquence. Ainsi, chaque séquence est traitée comme une extension successive de la précédente.

Voici un exemple dde donnée d'entrée, avec le champs boundsDuration:

{
  "types": ["MAX_TREATMENT_DURATION"],
  "medicationRequests": [
    {
      "drug": {
        "clinicalDrug": {
          "code": "MV00001769",
          "terminology": "posos"
        }
      },
      "dosageInstructions": [
        {
          "timing": {
            "repeat": {
              "boundsPeriod": {
                "start": "2024-04-20"
              },
              "boundsDuration": {
                "value": 2,
                "system": "ucum",
                "code": "wk"
              },
            }
          }
        }
      ]
    }
  ]
}

Voici un exemple de paramètres avec boundsRange:

{
  "types": ["MAX_QUANTITY_PER_24_HOURS"],
  "medicationRequests": [
    {
      "drug": {
        "clinicalDrug": {
          "code": "MV00004522",
          "terminology": "posos"
        }
      },
      "dosageInstructions": [
        {
          "timing": {
            "repeat": {
              "boundsDuration": {
                "system": "http://hl7.org/fhir/ValueSet/duration-units",
                "value": 2,
                "code": "wk"
              },
              "frequency": 1,
              "period": 1,
              "periodUnit": "d",
              "when": [
                "MORN"
              ]
            }
          },
          "doseAndRate": {
            "doseRange": {
              "low": {
                "value": 5,
                "system": "http://snomed.info/sct",
                "code": "428673006"
              },
              "high": {
                "value": 15,
                "system": "http://snomed.info/sct",
                "code": "428673006"
              }
            }
          }
        }
      ]
    }
  ]
}

Et enfin voici un exemple avec une boundsPeriod:

{
  "types": ["MAX_TREATMENT_DURATION"],
  "medicationRequests": [
    {
      "drug": {
        "brandedDrug": {
          "code": "68650684",
          "terminology": "cis"
        }
      },
      "dosageInstructions": [
        {
          "timing": {
            "repeat": {
              "boundsPeriod": {
                "start": "2024-04-20",
                "end": "2024-05-10"
              }
            }
          }
        }
      ]
    }
  ]
}

Durée de traitement minimale

Le système d'alerte pour la durée de traitement minimale compare la durée prescrite du traitement avec une durée minimale définie dans les paramètres de l'alerte. Cette alerte informe le professionnel de santé que la durée du traitement prescrite est insuffisante pour atteindre l'efficacité thérapeutique attendue, ce qui peut nécessiter une réévaluation du plan de traitement.

Pour activer les alertes relatives à la durée maximale de traitement, il est impératif d'inclure le paramètre min_treatment_duration dans le champ types.

Afin de permettre l'analyse des données fournies, l'utilisateur doit renseigner l'un des champs suivants :

• timing.repeat.boundsRange.low pour spécifier la limite supérieure de la plage de temps.
• timing.repeat.boundsDuration pour définir une durée spécifique.
• timing.repeat.boundsPeriod, qui nécessite une date de début et une date de fin.

Lorsque plusieurs instructions de dosage sont présentes, chacune identifiée par un numéro de séquence distinct, la durée totale du traitement est calculée en additionnant les durées spécifiées pour chaque séquence. Ainsi, chaque séquence est traitée comme une extension successive de la précédente.

Voici un exemple dde donnée d'entrée, avec le champs boundsDuration:

{
  "types": ["MIN_TREATMENT_DURATION"],
  "medicationRequests": [
    {
      "drug": {
        "clinicalDrug": {
          "code": "MV00004546",
          "terminology": "posos"
        }
      },
      "dosageInstructions": [
        {
          "timing": {
            "repeat": {
              "boundsPeriod": {
                "start": "2024-04-20"
              },
              "boundsDuration": {
                "value": 4,
                "system": "ucum",
                "code": "d"
              }
            }
          }
        }
      ]
    }
  ]
}

Durée minimale entre les prises

Cette fonctionnalité analyse les données de dosage fournies pour chaque médicament et vérifie si l'intervalle entre les prises respecte la durée minimale prescrite. Si l'intervalle entre les doses est inférieur à la durée minimale spécifiée, une alerte est générée pour informer le professionnel de santé. Cela permet d'éviter les surdosages accidentels et de s'assurer que le médicament est administré de manière optimale selon les directives cliniques.

Ce type d'alerte est évalué en fonction des champs frequency et period renseignés dans timing.repeat. Une estimation plus précise de l'intervalle entre les doses est possible si les champs timeOfDay ou when sont également spécifiés. Par exemple, une fréquence de trois prises par jour suggère un intervalle de 8 heures entre chaque dose. Toutefois, si les moments spécifiques de la journée sont indiqués dans le champ when avec les valeurs [When.MORN, When.NOON, When.EVE], l'intervalle estimé entre les prises peut être réduit à 4 heures.

Voici un exemple où les moments de prise sont précisés, ce qui permet de déclencher l'alerte:

{
  "types": ["MIN_DURATION_BETWEEN_DOSES"],
  "medicationRequests": [
    {
      "drug": {
        "clinicalDrug": {
          "code": "MV00000756",
          "terminology": "posos"
        }
      },
      "dosageInstructions": [
        {
          "timing": {
            "repeat": {
            "frequency": 7,
            "period": 1,
            "periodUnit": "d"
            }
	  }
        }
      ]
    }
  ]
}

Et voici un exemple avec une frequencyMaxprécisée:

{
  "types": ["MIN_DURATION_BETWEEN_DOSES"],
  "medicationRequests": [
    {
      "drug": {
        "clinicalDrug": {
          "code": "MV00003567",
          "terminology": "posos"
        }
      },
      "dosageInstructions": [
        {
          "timing": {
	    "repeat": {
	      "frequency": 2,
	      "frequencyMax": 5,
	      "period": 1,
	      "periodUnit": "d"
	    }
	  }
        }
      ]
    }
  ]
}

Variables

MedicationRequest

DrugInput

DosageInstruction

DoseAndRate

Quantity

Range

Timing

Repeat

Résultat

L'API renvoie un objet de type DosageAlertResult.

** Drug **

** DoseAlert **

L'API renvoie toutes les alertes correspondant au type requêté en entrée. Si une alerte est déclenchée, elle est renvoyée avec la valeur alertDetected égale à true. Si une alerte n'est pas déclenchée, la valeur de alertDetected est false. Dans le cas où les informations fournies en entrée sont insuffisantes pour effectuer une analyse complète, la valeur de alertDetected sera null.

Erreurs

L'API getDosageAlert peut fournir des données partielles en cas d'erreur, lorsque cela est réalisable. Par exemple, même si les instructions de dosage sont incorrectes, l'API peut tout de même retourner les alertes liées au médicament demandé, mais avec alertDetected = null. Les données partielles sont disponibles dans le champ data et les erreurs éventuelles sont listées dans le champ errors.

Voici les types d'erreurs possibles liées aux données d'entrée que l'utilisateur peut rencontrer. Voici les différentes erreurs que l'utilisateur peut obtenir, qui sont liées la donnée d'entrée.

Enums

Dosage Alert Type

When

DayOfWeek