Generating a cohort | emtelligent Documentation

A cohort is up to 50 patients generated from one description of a population. The patients live in one fictional regional health system, created for the cohort: its hospitals, clinics and clinicians are shared, so patients see the same doctors and are admitted to the same hospitals, as in a real health system’s records.

Send POST /v1/cohorts:

{
  "size": 20,
  "age": {"min": 45, "max": 85},
  "female_proportion": 0.5,
  "complexity": {"min": 3, "max": 8},
  "conditions": [
    {"name": "type 2 diabetes mellitus", "proportion": 0.3},
    {"name": "essential hypertension", "proportion": 0.5}
  ],
  "documents_per_patient": {"min": 3, "max": 6},
  "country": "US",
  "region": "Ohio",
  "outputs": ["fhir", "notes", "bulk"],
  "seed": 7
}

The specification

Field	Default
`size`	(required)	Patients, 1 to 50
`age`	18 to 90	Each patient’s age is chosen in this range
`female_proportion`	`0.5`	The share of women
`complexity`	1 to 10	Each patient’s complexity is chosen in this range
`conditions`	none	Conditions given to an exact share of the patients (rounded): with `size` 20, a proportion of `0.3` gives exactly 6 patients the condition. Other patients may still have it, as it arises naturally
`documents_per_patient`	3 to 8	Each patient’s document count is chosen in this range, at most 50
`document_types`	all	As for a patient
`timeline`	ends today	As for a patient
`country`, `region`	random	Where the health system is: `US` or `CA`, and a state or province by name or abbreviation
`outputs`	`["fhir", "notes"]`	Each patient’s `fhir`, `notes` and `pdf`, and `bulk` for the whole cohort as FHIR Bulk Data
`seed`	random	The same specification and seed give the same patients’ ages, sexes, complexities, document counts and assigned conditions

Progress

Poll GET /v1/cohorts/{cohort_id}. Its progress counts the patients by status while they are generated, in parallel:

{ "id": "…", "status": "running", "size": 20, "max_documents": 120,
  "progress": { "queued": 9, "running": 3, "succeeded": 8, "failed": 0, "canceled": 0 }, … }

A cohort of 20 patients usually takes well under an hour. When every patient has finished, the cohort’s results are packaged and its status becomes succeeded.

Results

`name`	File
`patients`	`cohort_patients.zip`	A folder per patient, `001_<patient_id>/` and so on, with `fhir_bundle.json`, `result.json`, and `notes/` and `pdf/` as requested; and `manifest.json` listing each patient’s folder, status and document count
`bulk`	`cohort_fhir_bulk.zip`	The whole cohort as FHIR Bulk Data: one NDJSON file per resource type and a `manifest.json`
`result`	`cohort.json`	The health system (its facilities and clinicians), each patient’s status, and the condition counts below

Download each from GET /v1/cohorts/{cohort_id}/results/{name}, once, within 24 hours. See Results for the Bulk Data format.

Summary

A succeeded cohort’s summary says what was delivered, and counts the patients with each condition:

"summary": {
  "patients": 20, "succeeded": 20, "failed": 0, "canceled": 0, "documents": 91,
  "failures": [],
  "health_system": { "region": "Ohio", "country": "US", "facilities": 9, "clinicians": 24 },
  "conditions": {
    "requested": [
      { "name": "type 2 diabetes mellitus", "proportion": 0.3, "assigned": 6,
        "code": "44054006", "display": "Type 2 diabetes mellitus", "patients": 8 }
    ],
    "most_common": [
      { "code": "38341003", "display": "Hypertensive disorder", "patients": 13 }
    ]
  }
}

For each requested condition, assigned is the number of patients it was given to, and patients the number who have it, including those in whom it arose naturally. Counts follow the SNOMED CT hierarchy: a patient with a more specific kind of a condition, or a condition due to it (renal disorder due to type 2 diabetes, for type 2 diabetes), counts for it. most_common lists up to 15 conditions, counted the same way.

When some patients fail

If a patient cannot be generated, the others are still delivered. The cohort succeeds, the patient is listed in summary.failures with its error, and it is not billed. If every patient fails, the cohort fails.

Cancelling

DELETE /v1/cohorts/{cohort_id} cancels the cohort: queued patients at once, and running ones when they finish. A canceled cohort has no results and is not billed.