Core

Trajectories and datasets are the shared representation every other part of ehr2rl reads and returns. See the synthetic quickstart for a walkthrough.

class ehr2rl.PatientTrajectory(subject_id, admission_id, timestamps, states, actions, rewards, terminals, metadata=<factory>)

One patient’s episode as aligned per-timestep arrays.

T is the number of timesteps, D the number of state features, and A the number of action columns. Arrays are converted to NumPy and their shapes validated on construction; a one-dimensional actions array is reshaped to (T, 1).

Parameters:

  • subject_id (str) – MIMIC-IV subject_id, as a string.

  • admission_id (str) – MIMIC-IV hadm_id, as a string.

  • timestamps (ndarray) – Shape (T,). Unix time in seconds for each step.

  • states (ndarray) – Shape (T, D), float. Column names are in metadata["feature_names"] when known.

  • actions (ndarray) – Shape (T, A).

  • rewards (ndarray) – Shape (T,), float.

  • terminals (ndarray) – Shape (T,), bool. True where the episode ends.

  • metadata (dict) – Per-trajectory information such as died, feature_names, action_names, action_sizes, sofa_scores, and provenance.

Raises:

ValueError – If there are no timesteps or an array has the wrong shape.

property n_steps: int

Number of timesteps T.

with_rewards(rewards)

Return a copy of this trajectory with different rewards.

Parameters:

rewards (ndarray) – Shape (T,). Converted to float.

Returns:

A new, validated trajectory. metadata is shared with this one, not copied.

Return type:

PatientTrajectory

class ehr2rl.EHRDataset(root=None, trajectories=None)

A collection of patient trajectories.

Supports len(), iteration, and integer indexing over its trajectories. The load_* and featurize methods implement the frozen local CSV path. They modify the dataset in place and return it, so calls can be chained.

Parameters:
Variables:

  • trajectories – The trajectories, as a list.

  • tables (dict[str, DataFrame]) – Raw tables loaded by the load_* methods, keyed by name.

copy_with(trajectories)

Return a new dataset with this one’s root and tables but other trajectories.

Parameters:

trajectories (Iterable[PatientTrajectory]) – Trajectories for the new dataset.

Returns:

A new dataset. The tables mapping is copied; the tables themselves are shared.

Return type:

EHRDataset

load_admissions(filename='hosp/admissions.csv.gz')

Load the admissions table from root.

Parameters:

filename (str) – Path relative to root. If it does not exist, admissions.csv is tried instead.

Returns:

This dataset, for chaining.

Return type:

EHRDataset

Raises:
load_vitals(filename='icu/chartevents.csv.gz', resample='1h')

Load ICU chart events from root and average them into time bins.

Parameters:

  • filename (str) – Path relative to root. If it does not exist, vitals.csv is tried instead.

  • resample (str) – Bin width as a pandas frequency string.

Returns:

This dataset, for chaining.

Return type:

EHRDataset

Raises:
load_labs(filename='hosp/labevents.csv.gz', codes=None)

Load lab events from root.

Parameters:

  • filename (str) – Path relative to root. If it does not exist, labs.csv is tried instead.

  • codes (list[str] | None) – Lab itemids to keep. All rows are kept when None.

Returns:

This dataset, for chaining.

Return type:

EHRDataset

Raises:
featurize(pipeline='standard')

Build trajectories from the loaded tables, replacing trajectories.

Does nothing when no tables are loaded.

Parameters:

pipeline (str) – Featurization pipeline. "standard" is the only one.

Returns:

This dataset, for chaining.

Return type:

EHRDataset

Raises:

ValueError – If pipeline is not "standard".

The load_* and featurize methods implement the frozen local CSV path.

exception ehr2rl.EHRValidationError

Raised when input tables, an itemid map, or a feature preset is invalid.