glowgreen.close_contact module

private-members

_ContactPattern

class glowgreen.close_contact.ContactPatternOnceoff(theta, c, d)

Bases: _ContactPattern

Class for onceoff contact patterns.

Constructor:

  • Calls constructor of _ContactPattern.

  • theta, c and d are converted into numpy.ndarrays if they were not supplied as such.

Parameters

  • theta (int, float, list or numpy.ndarray) – Time (h) from end of delay to start of pattern element.

  • c (int, float, list or numpy.ndarray) – Duration (h) of pattern element.

  • d (int, float, list or numpy.ndarray) – Distance (m) of pattern element; i.e., distance from radioactive person for duration of pattern element.

Raises

  • ValueError – If theta not 0 for first element of onceoff pattern.

  • ValueError – If element of onceoff pattern has d of 0.

get_dose(cfit: Clearance_1m, tau, *args) → float

Return the dose (mSv) from sharing the onceoff pattern with a radioactive person, for a given dose rate clearance function and delay period.

Unlike with repeating patterns, the dose from a onceoff pattern is independent of the administration datetime. *args allows this method to be called with additional argument administration datetime, so it can be called the same way on both ContactPatternRepeating and ContactPatternOnceoff objects.

Parameters

  • cfit (clearance.Clearance_1m) – Dose rate clearance from radioactive person.

  • tau (int or float) – Delay period (h); i.e., the time from administration to when the pattern is started.

Raises

ValueError – If tau less than 0.

Returns

Dose (mSv) from the pattern.

Return type

float

get_restriction(cfit: Clearance_1m, dose_constraint, admin_datetime: Optional[datetime] = None) → tuple[float, float, datetime.datetime]

Calculate the restriction period; i.e., the time from administration to beginning sharing the pattern with a radioactive person, such that the dose from the pattern is equal to the dose constraint.

Parameters

  • cfit (clearance.Clearance_1m) – Dose rate clearance from radioactive person.

  • dose_constraint (int or float) – Dose constraint (mSv).

  • admin_datetime (datetime.datetime, optional) – Administration datetime.

Raises

ValueError – If dose_constraint not greater than 0.

Returns

Restriction period (h), dose (mSv) from the pattern with this restriction period, and datetime at the end of this restriction period (None if admin_datetime is None).

Return type

tuple[float, float, datetime.datetime]

class glowgreen.close_contact.ContactPatternRepeating(theta, c, d)

Bases: _ContactPattern

Class for infinitely repeating diurnal contact patterns.

Constructor:

  • Calls constructor of _ContactPattern.

  • theta, c and d are converted into numpy.ndarrays if they were not supplied as such.

  • Pattern elements with duration longer than 1 h are broken up, so that the restriction period can be better resolved.

Parameters

  • theta (int, float, list or numpy.ndarray) – Time (h) from 12 AM to start of pattern element.

  • c (int, float, list or numpy.ndarray) – Duration (h) of pattern element.

  • d (int, float, list or numpy.ndarray) – Distance (m) of pattern element; i.e., distance from radioactive person for duration of pattern element.

Raises

  • ValueError – If element of repeating pattern has d of 0 and c not 0.

  • ValueError – If repeating pattern extends beyond pattern period (24 h).

get_dose(cfit: Clearance_1m, tau, admin_datetime: datetime) → tuple[float, float]

Calculate the lifetime dose (mSv) from sharing the infinitely repeating pattern with a radioactive person, for a given dose rate clearance function, delay period and administration datetime.

Implements method in: Cormack J & Shearer J. “Calculation of radiation exposures from patients to whom radioactive materials have been administered.” Phys Med Biol 1998; 43(3).

NB. If the delay period tau ends during a pattern element, the dose calculated will not include a contribution from the remainder of that pattern element in the first cycle. I.e., the calculated dose will be for the delay period shifted forward (by less than 1 h) to the end of the pattern element. Hence, the potentially corrected delay period is returned along with the dose.

Parameters

  • cfit (clearance.Clearance_1m) – Dose rate clearance from radioactive person.

  • tau (int or float) – Delay period (h); i.e., the time from admin_datetime to when the pattern is resumed.

  • admin_datetime (datetime.datetime) – Administration datetime.

Raises

  • ValueError – If tau less than 0.

  • ValueError – If tau is numpy.inf with repeating pattern.

Returns

Dose (mSv) from the pattern from the end of the delay period to infinity, and the potentially corrected delay period (h).

Return type

tuple[float, float]

get_dose_finite(cfit: Clearance_1m, t1, t2, admin_datetime: datetime) → tuple[float, float, float]

Return the dose (mSv) from sharing the repeating pattern with a radioactive person between 2 time points.

For example, the dose if the pattern is resumed after some delay period then ceased again permanently at a later time.

NB. If t1 or t2 end during a pattern element, the calculated dose is for that time point shifted forward (by less than 1 h) to the end of the pattern element. Hence, the potentially corrected time interval is returned along with the dose.

Parameters

  • cfit (clearance.Clearance_1m) – Dose rate clearance from radiaoctive person.

  • t1 (int or float) – The time (h) from admin_datetime to the start of the exposure.

  • t2 (int or float) – The time (h) from admin_datetime to the end of the exposure.

  • admin_datetime (datetime.datetime) – Administration datetime.

Raises

ValueError – If t2 less than t1.

Returns

Dose (mSv) from the pattern between 2 time points with respect to admin_datetime, first time point (h), and second time point (h).

Return type

tuple[float, float, float]

get_restriction(cfit: Clearance_1m, dose_constraint, admin_datetime: datetime, next_element=True) → tuple[float, float, datetime.datetime]

Calculate the restriction period; i.e., the least time from administration (up to the resolution of the pattern element widths) to when sharing the pattern with a radioactive person can be resumed, such that the lifetime dose from the infinitely repeating pattern is less than the dose constraint.

NB. Using next_element True is advisable and can make a large difference for sparse repeating patterns such as public transport to and from work. For example, if we want you to miss the morning bus, it means you have to wait for the afternoon bus; you can’t just get on the morning bus at 9 AM instead of 8 AM and expect to comply with the dose constraint. By always having the end of the restriction period coincide with the start of a pattern element, it is clear that contact can resume immediately at the end of the restriction period.

Parameters

  • cfit (clearance.Clearance_1m) – Dose rate clearance from radioactive person.

  • dose_constraint (int or float) – Dose constraint (mSv).

  • admin_datetime (datetime.datetime) – Administration datetime.

  • next_element (bool, optional) – If the end of the restriction period does not coincide with the start of a pattern element, extend the restriction period to the start of the next pattern element. Default is True.

Raises

ValueError – If dose_constraint not greater than 0.

Returns

Calculated restriction period (h), dose (mSv) from the pattern from the end of this restriction period to infinity, and the datetime at the end of this restriction period.

With next_element False, the calculated restriction period is in the range: [true restriction period, true restriction period + (1 h) - min(self.c)[, where the true restriction period is limited only by the pattern element widths.

Return type

tuple[float, float, datetime.datetime]

glowgreen.close_contact.cs_patterns() → DataFrame

Return a dataframe containing the contact patterns published by Cormack & Shearer along with appropriate dose constraints.

Reference: Cormack J & Shearer J. “Calculation of radiation exposures from patients to whom radioactive materials have been administered.” Phys Med Biol 1998; 43(3).

Returns

Dataframe with column labels:

  • name (str): A name for the contact pattern and dose constraint pairing.

  • pattern_type (str): ‘repeating’ or ‘onceoff’, indicating the type of pattern.

  • theta (int, float, list or numpy.ndarray): Start times (h) of pattern elements.

  • c (int, float, list or numpy.ndarray): Durations (h) of pattern elements.

  • d (int, float, list or numpy.ndarray): Distances (m) of pattern elements.

  • dose_constraint (int or float): Dose constraint (mSv).

  • per_episode (int): 1 if dose constraint is to be treated as per treatment episode, 0 if per annum.

Return type

pandas.DataFrame

glowgreen.close_contact.cs_restrictions(cfit: Clearance_1m, num_treatments_in_year, admin_datetime: datetime) → DataFrame

Return a dataframe containing the restriction periods for the contact patterns and dose constraints from Cormack & Shearer, using the supplied dose rate clearance function, number of treatments anticipated in a year and administration datetime.

Reference: Cormack J & Shearer J. “Calculation of radiation exposures from patients to whom radioactive materials have been administered.” Phys Med Biol 1998; 43(3).

Parameters

  • cfit (clearance.Clearance_1m) – Dose rate clearance from radioactive person.

  • num_treatments_in_year (int or float) – Number of treatments anticipated in a year.

  • admin_datetime (datetime.datetime) – Administration datetime.

Returns

Dataframe with column labels:

  • name (str): Name of the contact pattern and dose constraint pairing.

  • pattern_type (str): ‘repeating’ or ‘onceoff’, indicating the type of pattern.

  • theta (int, float, list or numpy.ndarray): Start times (h) of pattern elements.

  • c (int, float, list or numpy.ndarray): Durations (h) of pattern elements.

  • d (int, float, list or numpy.ndarray): Distances (m) of pattern elements.

  • dose_constraint (int or float): Dose constraint (mSv).

  • per_episode (int): 1 if dose constraint is to be treated as per treatment episode, 0 if per annum.

  • dose_constraint_corrected (float): Dose constraint (mSv) corrected for number of treatments in a year. Only differs from dose_constraint if per_episode is 0. If per_episode is 0, dose_constraint is per annum, so dose_constraint_corrected = dose_constraint / num_treatments_in_year.

  • restriction_period (float): Calculated restriction period (h).

  • dose (float): Dose (mSv) from the pattern with the calculated restriction period.

  • datetime_end (datetime.datetime): Datetime at the end of the calculated restriction period.

Return type

pandas.DataFrame

glowgreen.close_contact.restrictions_for(df: DataFrame, cfit: Clearance_1m, num_treatments_in_year, admin_datetime: Optional[datetime] = None) → DataFrame

Compute restriction periods for the supplied contact patterns and dose constraints in a dataframe, dose rate clearance function, number of treatments anticipated in a year and administration datetime.

Parameters

  • df (pandas.DataFrame) – Dataframe that includes column labels pattern_type, theta, c, d, dose_constraint and per_episode. See Returns section of cs_patterns().

  • cfit (clearance.Clearance_1m) – Dose rate clearance from radioactive person.

  • num_treatments_in_year (int, float) – Number of treatments anticipated in a year. Used to scale dose_constraint if per_episode is 0.

  • admin_datetime (datetime.datetime, optional) – Administration datetime. Can only be omitted or None if pattern_type is ‘onceoff’ for all rows in df, in which case the returned dataframe will have all None values in column datetime_end.

Raises

  • KeyError – If df missing column label pattern_type, theta, c, d, dose_constraint or per_episode.

  • ValueError – If row in df has pattern_type not ‘repeating’ or ‘onceoff’.

  • ValueError – If row in df has pattern_type ‘repeating’ and admin_datetime None.

  • ValueError – If num_treatments_in_year less than 1.

Returns

Deep copy of df with additional (or overwritten) columns labelled:

  • dose_constraint_corrected (float): Dose constraint (mSv) corrected for number of treatments in a year. Only differs from dose_constraint if per_episode is 0. If per_episode is 0, dose_constraint is per annum, so dose_constraint_corrected = dose_constraint / num_treatments_in_year.

  • restriction_period (float): Calculated restriction period (h).

  • dose (float): Dose (mSv) from the pattern with the calculated restriction period.

  • datetime_end (datetime.datetime): Datetime at the end of the calculated restriction period (None if admin_datetime is None).

Return type

pandas.DataFrame