Conservative temporal intervals¶

openmed.clinical.temporal_intervals normalizes caller-supplied synthetic or clinical temporal spans locally. It handles date, clock-time, duration, and finite or open-ended interval forms while retaining the exact half-open source offsets.

Basic use¶

from openmed.clinical.temporal_intervals import normalize_temporal_intervals

text = "Symptoms since 2024-01-01; review from 2024-02 to present."
spans = [
    (text.index("since"), text.index("since") + len("since 2024-01-01")),
    (text.index("from"), text.index("present") + len("present")),
]

records = normalize_temporal_intervals(text, spans)
records[0].value  # "2024-01-01/.."
records[1].value  # "2024-02/.."

normalize_temporal_interval(text, span) is the one-span form. Omitting spans normalizes the complete input string. Spans are inclusive at start and exclusive at end, and the returned source_span is always the original pair of offsets.

Conservative values¶

Each TemporalInterval exposes kind, value, precision, timezone_state, unknown_components, and conflicts. A scalar date, time, or duration uses its start component; an interval uses start and end. Open bounds are None and are represented canonically by .. in value. The normalizer never substitutes the current date/time for present, ongoing, or a missing timezone.

Examples of intentional outcomes:

Naive clock times are retained as wall-clock values but carry an explicit timezone_state="unknown"; no machine-local timezone is applied. Partial dates retain their source precision. A numeric date whose month/day ordering cannot be established is marked conflicting rather than assigned a locale.

Privacy and determinism¶

Normalization is rules-based, offline, and deterministic. It does not read environment state, consult a timezone database, use the wall clock, emit logs, or make network calls. to_dict() includes offsets and structured metadata but does not include surrounding source prose. Normalized dates and times can still be identifying clinical data: keep these results under the caller's PHI policy, not in public logs or audit artifacts. Use offsets and fingerprints for public audit records. Explicit timezone offsets participate in clock-time comparisons; mixed known and unknown timezones are not assigned an ordering. Invalid years, repeated interval prefixes, and expressions longer than 4096 characters remain unknown rather than being guessed or raising parser-limit errors.

This is assistive normalization metadata, not a diagnosis, treatment recommendation, or clinical decision.