itasc.contact_analysis.curation

The curation artifact — hand QC exclusions joined onto the measurement tables.

A separate, git-versioned tidy table kept apart from the disposable measurement tables (the dividing line is who made the decisions in it). Schema, one row per exclusion:

experiment_id, position_id, frame, excluded, exclusion_reason

frame empty/NA means the whole position (every frame). At export the table is left-joined onto a measurement table by the natural keys the table already carries — a frame-level exclusion matches (experiment_id, position_id, frame); a position-level exclusion (frame NA) matches (experiment_id, position_id) — marking matched rows excluded = True and copying the reason. Rows with no entry default to kept; filter, don’t delete. The measurement source is never mutated.

This restores the curation that commit 95df159 removed, re-keyed on the natural keys (the old version, at rev 39d0df2, joined on a deterministic row id).

Module attributes

CURATION_COLUMNS

The columns a curation CSV carries.

Functions

append_exclusion(curation, *, experiment_id, ...)	Return curation with one exclusion row added.
apply_curation(table, curation)	Return table with excluded / exclusion_reason columns marked.
empty_curation()	An empty curation table with the canonical columns (object dtype).
filter_excluded(marked)	Drop the rows apply_curation() marked excluded.
read_curation(path)	Read the curation CSV at path, or None when path is unset/absent.
remove_exclusion(curation, *, experiment_id, ...)	Return curation without the row(s) matching the given key.
write_curation(path, curation)	Write curation to path as CSV (creating the parent dir), index-free.

itasc.contact_analysis.curation.CURATION_COLUMNS = ('experiment_id', 'position_id', 'frame', 'excluded', 'exclusion_reason')

The columns a curation CSV carries.

itasc.contact_analysis.curation.empty_curation()

An empty curation table with the canonical columns (object dtype).

Object columns keep an empty frame as NA (whole-position) rather than coercing the column to a float that would render NaN on write.

Return type:

DataFrame

itasc.contact_analysis.curation.read_curation(path)

Read the curation CSV at path, or None when path is unset/absent.

A missing file is not an error: an uncurated series simply keeps every row.

Return type:

DataFrame | None

Parameters:

path (Path | str | None)

itasc.contact_analysis.curation.write_curation(path, curation)

Write curation to path as CSV (creating the parent dir), index-free.

Return type:

None

Parameters:

• path (Path | str)

• curation (DataFrame)

itasc.contact_analysis.curation.append_exclusion(curation, *, experiment_id, position_id, frame, reason)

Return curation with one exclusion row added.

frame=None records a whole-position exclusion (stored as NA); a numeric frame records a single-frame exclusion. Idempotent on the (experiment_id, position_id, frame) key: an existing row with the same key is replaced (its reason updated) rather than duplicated. The input is not mutated.

Return type:

DataFrame

Parameters:

• curation (DataFrame | None)

• experiment_id (str)

• position_id (str)

• frame (int | None)

• reason (str)

itasc.contact_analysis.curation.remove_exclusion(curation, *, experiment_id, position_id, frame)

Return curation without the row(s) matching the given key.

frame=None removes the whole-position row (frame NA); a numeric frame removes that single-frame row. A non-matching key is a no-op. The input is not mutated.

Return type:

DataFrame

Parameters:

• curation (DataFrame | None)

• experiment_id (str)

• position_id (str)

• frame (int | None)

itasc.contact_analysis.curation.apply_curation(table, curation)

Return table with excluded / exclusion_reason columns marked.

A measurement row is marked excluded iff a curation entry matches it by either (experiment_id, position_id, frame) (frame-level) or (experiment_id, position_id) with the curation frame NA (position-level). Keys are compared as strings (CSV round-trips ids as strings); frame as an integer. Unmatched rows default to kept with an empty reason. The input frame is not mutated.

Return type:

DataFrame

Parameters:

• table (DataFrame)

• curation (DataFrame | None)

itasc.contact_analysis.curation.filter_excluded(marked)

Drop the rows apply_curation() marked excluded.

Returns (kept, n_dropped) where kept has the two marker columns removed (so it matches the source schema) and a reset index. A frame with no excluded column is returned unchanged with n_dropped == 0.

Return type:

tuple[DataFrame, int]

Parameters:

marked (DataFrame)