Skip to main content

Scoring systems

The scoringSystems field lives under result and houses one or more scoring models for the identified pathology. These models come into play when the likelihood of the most probable conclusion surpasses a certain threshold, and they are used to estimate the severity of that condition.

"scoringSystems": [
  {
    "scoringSystem": {
      "name": "Acne lesion estimation grading index",
      "code": "alegi"
    },
    "score": {
      "value": 8,
      "severity": {
        "value": 1,
        "interpretations": [
          {
            "min": 0.0,
            "max": 0.0,
            "text": "None",
            "coding": [
              {
                "code": 1,
                "display": "low"
              }
            ]
          },
          ...
        ]
      }
    },
    "reduction": null,
    "facets": [
      {
        "facet": {
          "name": "Acne lesion density",
          "description": ""
        },
        "value": {
          "display": "None (0)",
          "raw": 0
        }
      },
      ...
    ],
    "explainabilityMedia": {
      "url": "https://bucket/diagnostic-report-medias/explainability/aaa.png"
    }
  }
]

Scoring system identifier​

In each scoring system:

  • scoringSystem includes the name and code of the scoring methodology. code is a camelCase identifier (e.g. alegi, apasiLocal, pasiLocal, scoradLocal, ihs4Local, hiscr, dlqi). Match on the exact camelCase string; do not assume SCREAMING_SNAKE_CASE.

Naming pattern:

  • Local suffix: the scoring system runs on a single body-site image.
  • Global suffix: the scoring system aggregates across all body sites for the same encounter.
  • a-prefix (e.g. apasiLocal, ascoradLocal, aihs4Local): AI-computed variants of the parent scoring system.

The complete list of supported scoring systems for a given pathology, together with their facet questionnaires, can be fetched from a public, unauthenticated endpoint:

GET https://medical-device-params.legit.health/v2.0/questionnaires?pathology=<ICD-11 code>

Pass the ICD-11 code of the pathology of interest as the pathology query parameter (e.g. EA90 for Psoriasis). The response is an array of objects describing each scoring system applicable to that pathology, with the following fields:

  • identifier: the camelCase scoring-system code emitted under scoringSystem.code (e.g. apasiLocal, pure4).
  • code: short identifier used internally by the severity-assessment endpoint (e.g. apasi, pure4).
  • mode: "local" or "global".
  • path: the severity-assessment endpoint path.
  • title, description: multilingual objects keyed by locale (en_GB, es_ES, ...).
  • questionnaire: an array of facet objects, each with code, name (multilingual), description (multilingual), and input (type, min/max, options). These correspond to the facets emitted under facets[] in the diagnostic-report response.

Use this endpoint as the source of truth: the catalog of scoring systems can grow over time.

Score, severity and facets​

  • score.value indicates the calculated score according to the system's rules. Can be null if the score could not be computed.
  • score.severity.value: integer severity code. One of 1 (low), 2 (moderate), 3 (high), or null when the scoring system has no severity band for this body site or locale. The English string label is exposed under score.severity.interpretations[].coding[0].display ("low", "moderate", "high"); the localized BAND label (such as "None", "Mild", "Moderate", "Severe", "Grade 1", "Stage 0") is exposed under score.severity.interpretations[].text.
  • score.severity.interpretations is an array describing every severity band defined for this scoring system at the relevant body site and locale. Each entry contains:
    • min: lower bound (inclusive) of the score range that maps to this band.
    • max: upper bound of the score range that maps to this band.
    • text: human-friendly label for the band (translated), e.g. "Mild", "Moderate", "Severe".
    • coding[]: machine-readable severity coding for the band, with each entry exposing a code and display.
  • reduction: object (or null) describing automatic score reductions (for example, lesion-density adjustments). Most scoring systems return null here.
  • facets is an array of facets used in score calculation, with each object containing the facet's information and the corresponding raw and displayed values.
  • explainabilityMedia: an object with a single url field. The object is always emitted; url is null when the scoring system did not produce an annotated overlay. When present, url is a signed S3 URL to a heatmap or bounding-box image explaining how the score was produced.