Configuration API

A session's configuration is session.configuration, an IsocenterConfiguration. load_config() fills it from a YAML file; the methods below change it in memory and write it back with save(). The file format is on Configuration. The class, its fields and these six methods are frozen at 1.0 (API stability).

IsocenterConfiguration dataclass

The configuration a session applies, reached as session.configuration.

load_config() fills it from a file; the methods below change it in memory, and save() writes it.

Attributes:

Name	Type	Description
rules	List[Dict[str, Any]]	List of machine redaction rules.
phi_tags	Dict[str, Any]	PHI tag policies, keyed by lowercase "gggg,eeee" tag. With none given, a copy of the floor policy (profiles.FLOOR_POLICY): the PS3.15 basic@2026c profile plus three research defaults, which a session applies before any config is loaded (see the Configuration guide). Each instance holds its own copy, so one session's set_phi_tag cannot reach another's policy or the module table.
date_jitter	Dict[str, int]	The range the per-patient date offset is derived within, in days, both ends included: {"min_days": -365, "max_days": -1} by default.
remove_private_tags	bool	Global flag to strip private tags.
config_path	Optional[str]	The file save() writes. Set by load_config(), or by hand.
auto_save	bool	Write config_path after every add_rule, update_rule, delete_rule and set_phi_tag. False by default.
privacy_profile	Optional[str]	The pinned name of the built-in profile whose rules were merged into phi_tags (basic@2026c, also when the file said basic), or an external profile's path, or None when no named profile was applied (the floor, or privacy_profile: none). Only ever set to a profile that resolved.

save()

Write the configuration to config_path as YAML.

The file names the profile rather than copying it: privacy_profile is the pinned name (basic@2026c), the external profile's path, none, or no line at all for the floor, and phi_tags holds only the rules that differ from that base's. Then date_jitter, remove_private_tags and every machine rule, each key kept (comment: as data). version is always written, as this library's configuration version. A file this writes loads to the configuration it was written from.

Comments and layout in an existing file are not kept: this writes a new file.

Raises:

Type	Description
ValueError	With no config_path; and when phi_tags has no rule for a tag its base supplies, because a file naming that base would bring the rule back on reload. Nothing is written.
OSError	The write's own error, unchanged.

add_rule(serial_number, manufacturer='Unknown', model_name='Unknown', redaction_zones=None)

Add a machine redaction rule.

Replaces any existing rule for the same serial number. Changes memory; writes config_path only when auto_save is on. The keywords are spelled as the rule's keys in a machines: file.

Parameters:

Name	Type	Description	Default
serial_number	str	The device serial number.	required
manufacturer	str	Metadata for reference.	'Unknown'
model_name	str	Metadata for reference.	'Unknown'
redaction_zones	List[Any]	The zones to set to zero, each [y1, y2, x1, x2] in pixels: rows y1 up to y2 and columns x1 up to x2, the end excluded. A zone with no area (y2 <= y1 or x2 <= x1) makes redact() fail that instance; one that starts past the image's edge is skipped.	None

Raises:

Type	Description
ValueError	For a rule load_config would refuse (a serial that is not a non-empty, non-blank string, a metadata field that is not a string, a malformed zone), before any rule or the file changes. Under auto_save, with no config_path, or when save() refuses; the rules are then as they were.
OSError	Under auto_save, when the write fails; the rules are then as they were.

update_rule(serial_number, updates)

Update the rule for serial_number.

Changes memory; writes config_path only when auto_save is on.

Parameters:

Name	Type	Description	Default
serial_number	str	The target rule's serial number.	required
updates	Dict[str, Any]	Dictionary of fields to update.	required

Raises:

Type	Description
ValueError	If no rule is found, if the update changes the serial number, or if the updated rule is one load_config would refuse (an unknown key such as redaction_zone, a value of the wrong type, a malformed zone). Raised before the rule or the file changes. Under auto_save, with no config_path, or when save() refuses; the rule is then as it was.
OSError	Under auto_save, when the write fails; the rule is then as it was.

delete_rule(serial_number)

Remove the rule for a serial number.

Changes memory; writes config_path only when auto_save is on and a rule was removed.

Parameters:

Name	Type	Description	Default
serial_number	str	The serial number to remove.	required

Returns:

Type	Description
bool	True if a rule was found and removed, False otherwise.

Raises:

Type	Description
ValueError	Under auto_save with no config_path (even when no rule matches), and when save() refuses.
OSError	Under auto_save, when the write fails; the rules are then as they were.

set_phi_tag(tag, action, value=None)

Set or replace the PHI rule for one tag.

Changes memory; writes config_path only when auto_save is on.

Parameters:

Name	Type	Description	Default
tag	str	The DICOM tag to target (e.g. "0010,0010"), stored lowercase.	required
action	str	One of KEEP, REMOVE, EMPTY, REPLACE, SHIFT and JITTER (JITTER is SHIFT).	required
value	str	The value REPLACE writes, stored as the rule's value, the key a file spells it with.	None

Raises:

Type	Description
ValueError	For an unknown action, and for a rule the pipeline cannot honour: a Patient ID rule other than KEEP or REPLACE with no value, a value under an action other than REPLACE, SHIFT/JITTER on a standard tag that is not DA or DT, or REPLACE on a standard tag whose VR cannot hold the value. Raised before the policy or its file is changed. Under auto_save, also with no config_path and when save() refuses; the policy is then as it was.
OSError	Under auto_save, when the write fails; the policy is then as it was.

get_rule(serial_number)

Return the rule for a serial number: the rule dictionary itself, not a copy.

Exact spelling, first match. Redaction does not use this: redact() and the export apply every matching rule, "*" included.

Parameters:

Name	Type	Description	Default
serial_number	str	The serial number to find.	required

Returns:

Type	Description
Optional[Dict[str, Any]]	The rule dictionary if found, else None.