Skip to main content

Measures

warning

Satxuma is still under active development. It is not yet HIPAA compliant and should only be used with dummy data.

A measure is a tool for quantifying a patient's ability to perform some task. Measures can be used to track patient's progress towards a goal. Common measures include Balance, Bed Mobility, Sit-to-stand, and Memory recall.

Data model​

Satxuma stores measures under a case:

When a document (eval, tx, prog note, or discharge) is signed, each active measure in the case acquires a lock. A lock references the document that created it along with a timestamp. This essentially creates an unmodifiable snapshot of the measure as it existed when the document was signed. (I.e. it "locks" measurements and goals on or before the lock date from editing.)

Discussion​

Measures come in two flavors, numeric and categorical.

Numeric measures are scored with a number. For example,

  1. How much does the patient weight (in pounds)?
  2. How much time does it take the patient to go from sitting to standing (in seconds)?
  3. How many items can the patient recall in a memory test?
note

Numeric measures may include units - a label that describes the number being tracked. For example, "pounds", "seconds", "feet", etc.

Categorical measures are scored using a ranked, discrete set of categories. For example

  1. How much assistance does the patient need to microwave a meal? (none < minimal < moderate < maximal)
  2. How much pain does the patient feel? (none < minimal < moderate < severe)
note

Categorical measures are scored using a pre-established set of ranked categories.

Properties​

A measure in Satxuma has the following properties:

  • description (string)
    A description of the measure.
  • discontinuedAt (Timestamp | Date | null)
    When the measure was discontinued, if applicable.
  • discontinuedBy ({ id: string; name: string } | null)
    The user who discontinued the measure, if applicable.
  • goals (Goal[])
    A list of goals tied to the measure. Each goal includes:
    • description (string)
      Description of the goal.
    • discontinuedAt When the goal was discontinued, if applicable.
    • discontinuedBy
      The user who discontinued the goal, if applicable.
    • expiresAt (Timestamp | Date)
      When the goal expires.
    • id (UUID)
      Unique identifier for the goal.
    • name (string)
      Name of the goal.
    • value (number)
      Numeric value associated with the goal.
  • locks (Lock[])
    A list of locks tied to related records (certifications, discharges, progress notes, or treatments). Each lock includes the linked record’s ID and the time it was locked.
  • measurements ({ measuredAt: Timestamp | Date; isNA: boolean; value: number }[])
    Historical measurements for the measure, including date, value, and NA status.
  • naCategories ({ name: string; description: string }[])
    Categories used when a measurement is marked as NA (not applicable).
  • name (string)
    The name of the measure.
  • priorValue ({ isNA: boolean; value: number | null })
    The most recent previous value recorded for the measure, including NA status.
  • template ({ id: string; name: string } | null)
    The template from which this measure was created, if applicable.
  • type ('numeric' | 'categorical')
    The type of measure:
    • numeric — includes units (string) specifying the measurement units.
    • categorical — includes categories ({ name: string; description: string }[]) defining the allowed categories.

Examples​

Example 1: Numeric measure (Activity Tolerance)​

{
  "id": "msr-123",
  "name": "Activity tolerance",
  "description": "Measure the duration the patient can sustain activity before fatigue.",
  "type": "numeric",
  "units": "minutes",
  "createdAt": "2025-03-01T10:00:00Z",
  "createdBy": { "id": "usr-101", "name": "Therapist Jane Doe" },
  "updatedAt": "2025-03-15T10:00:00Z",
  "updatedBy": { "id": "usr-101", "name": "Therapist Jane Doe" },
  "discontinuedAt": null,
  "discontinuedBy": null,
  "goals": [
    {
      "id": "goal-1",
      "name": "Improve activity tolerance",
      "description": "Patient will tolerate 15 minutes of activity to improve participation in daily tasks.",
      "createdAt": "2025-03-01T10:05:00Z",
      "createdBy": { "id": "usr-101", "name": "Therapist Jane Doe" },
      "updatedAt": "2025-03-15T10:05:00Z",
      "updatedBy": { "id": "usr-101", "name": "Therapist Jane Doe" },
      "expiresAt": "2025-04-01T00:00:00Z",
      "discontinuedAt": null,
      "discontinuedBy": null,
      "value": 15
    }
  ],
  "measurements": [
    { "measuredAt": "2025-03-02T09:00:00Z", "isNA": false, "value": 5 },
    { "measuredAt": "2025-03-09T09:00:00Z", "isNA": false, "value": 10 },
    { "measuredAt": "2025-03-16T09:00:00Z", "isNA": false, "value": 12 }
  ],
  "priorValue": { "isNA": false, "value": 10 },
  "naCategories": [
    {
      "name": "07. Patient refused",
      "description": "Patient or resident refused to perform this activity"
    },
    {
      "name": "09. Not applicable",
      "description": "Not attempted and the patient/resident did not perform this activity prior to the current illness, exacerbation, or injury."
    },
    {
      "name": "10. Not attempted (environment)",
      "description": "Not attempted due to environmental limitations (e.g., lack of equipment, weather constraints)"
    },
    {
      "name": "88. Not attempted (medical)",
      "description": "Not attempted due to medical condition or safety concerns"
    }
  ],
  "locks": [],
  "template": { "id": "activity-tolerance", "name": "Activity tolerance" }
}

Example 2: Categorical measure (ADL Performance)​

{
  "id": "msr-456",
  "name": "ADL performance",
  "description": "Assess the patient's ability to perform activities of daily living such as bathing and grooming.",
  "type": "categorical",
  "categories": [
    {
      "name": "01. Dependent",
      "description": "Helper does ALL of the effort. Patient/resident does none of the effort to complete the activity. Or, the assistance of 2 or more helpers is required for the patient/resident to complete the activity."
    },
    {
      "name": "02. Substantial/maximal assistance",
      "description": "Helper does MORE THAN HALF the effort. Helper lifts or holds trunk or limbs and provides more than half the effort."
    },
    {
      "name": "03. Partial/moderate assistance",
      "description": "Helper does LESS THAN HALF the effort. Helper lifts, holds or supports trunk or limbs, but provides less than half the effort."
    },
    {
      "name": "04. Supervision or touching assistance",
      "description": "Helper provides verbal cues and/or touching/steadying and/or contact guard assistance as patient/resident completes activity. Assistance may be provided throughout the activity or intermittently."
    },
    {
      "name": "05. Setup or clean-up assistance",
      "description": "Helper sets up or cleans up; patient/resident completes activity. Helper assists only prior to or following the activity."
    },
    {
      "name": "06. Independent",
      "description": "Patient/resident safely completes the activity by him/herself with no assistance from a helper."
    }
  ],
  "createdAt": "2025-03-05T10:00:00Z",
  "createdBy": { "id": "usr-202", "name": "Therapist John Smith" },
  "updatedAt": "2025-03-20T10:00:00Z",
  "updatedBy": { "id": "usr-202", "name": "Therapist John Smith" },
  "discontinuedAt": null,
  "discontinuedBy": null,
  "goals": [
    {
      "id": "goal-2",
      "name": "Improve ADL independence",
      "description": "Patient will complete ADLs at '04. Supervision or touching assistance' level to improve functional independence.",
      "createdAt": "2025-03-05T10:05:00Z",
      "createdBy": { "id": "usr-202", "name": "Therapist John Smith" },
      "updatedAt": "2025-03-20T10:05:00Z",
      "updatedBy": { "id": "usr-202", "name": "Therapist John Smith" },
      "expiresAt": "2025-04-15T00:00:00Z",
      "discontinuedAt": null,
      "discontinuedBy": null,
      "value": 4
    }
  ],
  "measurements": [
    { "measuredAt": "2025-03-06T09:00:00Z", "isNA": false, "value": 1 },
    { "measuredAt": "2025-03-13T09:00:00Z", "isNA": false, "value": 3 },
    { "measuredAt": "2025-03-20T09:00:00Z", "isNA": false, "value": 4 }
  ],
  "priorValue": { "isNA": false, "value": 3 },
  "naCategories": [
    {
      "name": "07. Patient refused",
      "description": "Patient or resident refused to perform this activity"
    },
    {
      "name": "09. Not applicable",
      "description": "Not attempted and the patient/resident did not perform this activity prior to the current illness, exacerbation, or injury."
    },
    {
      "name": "10. Not attempted (environment)",
      "description": "Not attempted due to environmental limitations (e.g., lack of equipment, weather constraints)"
    },
    {
      "name": "88. Not attempted (medical)",
      "description": "Not attempted due to medical condition or safety concerns"
    }
  ],
  "locks": [],
  "template": { "id": "adl-performance", "name": "ADL performance" }
}