Keep missing Event timestamps as None; make Event copyable and picklable

[solarsys]

Summary

This fixes two bugs in pyhealth.data.Event.

1. A missing timestamp was silently replaced with datetime.now().
2. Event could not be copied or unpickled (RecursionError).

⚠️ Behaviour change (for the CHANGELOG): Event.timestamp is now None when an event has no time, instead of the current time. That includes Event("x") created without a timestamp. Code that needs a time should pass timestamp= explicitly.

1. Missing timestamps became "now"

Some tables have no time column, for example MIMIC-III/IV patients and all the eICU tables. Their rows have a null timestamp, but Event.__init__ did:

if timestamp is None:
    timestamp = datetime.now()

So every Event that get_events() built from those tables got an invented time. On the bundled MIMIC-III demo, patient 10006:

get_events("patients", return_df=True)["timestamp"]  ->  [None]
get_events("patients")[0].timestamp (1st call)       ->  2026-09-27 10:54:26.852890
get_events("patients")[0].timestamp (2nd call)       ->  2026-09-27 10:54:27.955225
admission timestamp                                  ->  2164-10-23 21:09:00

Why this matters:

• The value is not reproducible. It changes on every call and every run.
• The two views of the same row disagree. The DataFrame shows null; the Event shows a date.
• It silently passes time-window filters. MIMIC dates are shifted into the 2100s, so "now" sorts before every real event, and a filter like e.timestamp <= admission.timestamp wrongly includes demographic rows.
• Existing code already works around it. The FHIR timeline avoids Event.timestamp for this reason; see the comment in tests/core/test_fhir_dataset.py.

Fix: the timestamp stays None when missing. I found nothing in the library that reads timestamps from these tables (the eICU tasks filter by stay ID). The full test suite passes unchanged, including the FHIR tests.

2. Event could not be copied or unpickled

Event.__getattr__ read self.attr_dict. copy and pickle rebuild the object without calling __init__, then look up special methods such as __setstate__ before attr_dict exists. That lookup lands back in __getattr__, which recurses forever:

pickle.dumps(event)                 -> ok
pickle.loads(pickle.dumps(event))   -> RecursionError
copy.copy(event), copy.deepcopy(e)  -> RecursionError

Because dumps works, a task sample that contains an Event (e.g. in a "raw" field) is written fine and then fails with RecursionError when PyHealth reads it back. I reproduced this with create_sample_dataset.

Fix: __getattr__ now rejects dunder names and reads attr_dict via self.__dict__. Attribute access (event.hadm_id, event["hadm_id"], "hadm_id" in event) is unchanged, and a missing field still raises AttributeError.

Changes

• pyhealth/data/data.py: both fixes. timestamp is now typed datetime | None, and the docstring has >>> examples.
• tests/core/test_event.py (new, 8 tests):
  • missing and explicit timestamps
  • from_dict and get_events agree with the DataFrame and are stable across calls
  • pickle, copy and deepcopy round trips
  • attribute access
  • an Event stored inside a sample dataset
• docs/api/data/pyhealth.data.Event.rst: a new "Events without a time" section, with the migration note and copy/pickle support.
• examples/event_timestamps_mimic3demo.py: runs on the bundled demo data. It reads a timeless event, filters to timed events, and does a pickle round trip.

Verification

• New tests: 6 of 8 fail before the fix (3 with the invented timestamp, 3 with RecursionError); all 8 pass after.
• Full core suite: Ran 1335 tests … OK (skipped=76).
• tools/check_pr_rules.py: all rules pass.

Out of scope

• hash(Event) raises unhashable type: 'dict', because the frozen dataclass hashes the attr_dict dict. Nothing relies on hashing events.
• datasets/mimicextract.py builds Events with the 1.x signature and no event_type. That is already broken and is covered by PyHealth 2.0: several modules still target the 1.x dataset API #1201.

🤖 Generated with Claude Code

[jhnwu3]

That's a good catch. Thanks professor.

LGTM