pyanno4rt.tools

Tools module.

This module aims to provide helpful functions that improve code readability.

Overview

Function
`add_square_brackets`(text)	Add square brackets to a string-type text.
`apply`(function, elements)	Apply a function to each element of an iterable.
`arange_with_endpoint`(start, stop, step)	Return evenly spaced values within an interval, including the endpoint.
`compare_dictionaries`(reference_dict, compare_dict)	Compare two dictionaries by their keys and values (including numpy arrays).
`copycat`(base_class, path)	Create a copycat from a treatment plan snapshot.
`custom_round`(number)	Round up a number from 5 as the first decimal place, otherwise round down.
`deduplicate`(elements)	Convert an iterable to a dictionary with index tuple for each element.
`flatten`(elements)	Convert a nested iterable to a flat one.
`get_all_constraints`(segmentation)	Return a tuple with the user-assigned constraints.
`get_all_objectives`(segmentation)	Return a tuple with the user-assigned objectives.
`get_constraint_segments`(segmentation)	Get a tuple with the segments associated with the constraints.
`get_conventional_objectives`(segmentation)	Get a tuple with all set conventional objective functions.
`get_conventional_constraints`(segmentation)	Get a tuple with all set conventional constraint functions.
`get_machine_learning_constraints`(segmentation)	Get a tuple with all set machine learning model-based constraint functions.
`get_machine_learning_objectives`(segmentation)	Get a tuple with all set machine learning model-based objective functions.
`get_objective_segments`(segmentation)	Get a tuple with the segments associated with the objectives.
`get_radiobiology_constraints`(segmentation)	Get a tuple with the set radiobiology model-based constraint functions.
`get_radiobiology_objectives`(segmentation)	Get a tuple with the set radiobiology model-based objective functions.
`identity`(value, *args)	Return the identity of the first input parameter.
`inverse_sigmoid`(value, multiplier, summand)	Calculate the inverse sigmoid function value.
`load_list_from_file`(path)	Load a list of values from a file path.
`non_decreasing`(array)	Test whether an array is non-decreasing.
`non_increasing`(array)	Test whether an array is non-increasing.
`monotonic`(array)	Test whether an array is monotonic.
`sigmoid`(value, multiplier, summand)	Calculate the sigmoid function value.
`snapshot`(instance, path, include_patient_data, include_dose_matrix, include_model_data)	Take a snapshot of a treatment plan.
`replace_nan`(elements, value)	Replace NaN in an iterable by a specific value.

Functions

pyanno4rt.tools.add_square_brackets(text)[source]

Add square brackets to a string-type text.

Parameters:: text (str) – Input text to be placed in brackets.
Returns:: text – Input text with enclosing square brackets (if non-empty string).
Return type:: str

pyanno4rt.tools.apply(function, elements)[source]

Apply a function to each element of an iterable.

Parameters:

function (function) – Function to be applied.
elements (iterable) – Iterable over which to loop.

pyanno4rt.tools.arange_with_endpoint(start, stop, step)[source]

Return evenly spaced values within an interval, including the endpoint.

Parameters:

start (int or float) – Starting point of the interval.
stop (int or float) – Stopping point of the interval.
step (int or float) – Spacing between points in the interval.

Returns:

Array of evenly spaced values.

Return type:

ndarray

pyanno4rt.tools.compare_dictionaries(reference_dict, compare_dict)[source]

Compare two dictionaries by their keys and values (including numpy arrays).

Parameters:

reference_dict (dict) – Reference dictionary.
compare_dict (dict) – Dictionary for the comparison.

Returns:

Indicator for the equality of the dictionaries.

Return type:

bool

pyanno4rt.tools.copycat(base_class, path)[source]

Create a copycat from a treatment plan snapshot.

Parameters:

base_class (class from base) – The base treatment plan class from which to create an instance.
path (str) – Directory path of the snapshot.

Returns:

The instantiated base treatment plan object.

Return type:

object of class from base

pyanno4rt.tools.custom_round(number)[source]

Round up a number from 5 as the first decimal place, otherwise round down.

Parameters:: number (int or float) – The number to be rounded.
Returns:: The rounded number.
Return type:: float

pyanno4rt.tools.deduplicate(elements)[source]

Convert an iterable to a dictionary with index tuple for each element.

Parameters:: elements (iterable) – Iterable over which to loop.
Returns:: Dictionary with the element-indices pairs.
Return type:: dict

pyanno4rt.tools.flatten(elements)[source]

Convert a nested iterable to a flat one.

Parameters:: elements (iterable) – (Nested) iterable to be flattened.
Returns:: Generator object with the flattened iterable values.
Return type:: generator

pyanno4rt.tools.get_all_constraints(segmentation)[source]

Return a tuple with the user-assigned constraints.

Parameters:: segmentation (dict) – Dictionary with information on the segmented structures.
Returns:: Flattened tuple with the user-assigned constraints.
Return type:: tuple

pyanno4rt.tools.get_all_objectives(segmentation)[source]

Return a tuple with the user-assigned objectives.

Parameters:: segmentation (dict) – Dictionary with information on the segmented structures.
Returns:: Flattened tuple with the user-assigned objectives.
Return type:: tuple

pyanno4rt.tools.get_constraint_segments(segmentation)[source]

Get a tuple with the segments associated with the constraints.

Parameters:: segmentation (dict) – Dictionary with information on the segmented structures.
Returns:: Flattened tuple with the segments associated with the constraints.
Return type:: tuple

pyanno4rt.tools.get_conventional_objectives(segmentation)[source]

Get a tuple with all set conventional objective functions.

Parameters:: segmentation (dict) – Dictionary with information on the segmented structures.
Returns:: Flattened tuple with all set conventional objective functions.
Return type:: tuple

pyanno4rt.tools.get_conventional_constraints(segmentation)[source]

Get a tuple with all set conventional constraint functions.

Parameters:: segmentation (dict) – Dictionary with information on the segmented structures.
Returns:: Flattened tuple with all set conventional constraint functions.
Return type:: tuple

pyanno4rt.tools.get_machine_learning_constraints(segmentation)[source]

Get a tuple with all set machine learning model-based constraint functions.

Parameters:: segmentation (dict) – Dictionary with information on the segmented structures.
Returns:: Flattened tuple with all set machine learning model-based constraint functions.
Return type:: tuple

pyanno4rt.tools.get_machine_learning_objectives(segmentation)[source]

Get a tuple with all set machine learning model-based objective functions.

Parameters:: segmentation (dict) – Dictionary with information on the segmented structures.
Returns:: Flattened tuple with all set machine learning model-based objective functions.
Return type:: tuple

pyanno4rt.tools.get_objective_segments(segmentation)[source]

Get a tuple with the segments associated with the objectives.

Parameters:: segmentation (dict) – Dictionary with information on the segmented structures.
Returns:: Flattened tuple with the segments associated with the objectives.
Return type:: tuple

pyanno4rt.tools.get_radiobiology_constraints(segmentation)[source]

Get a tuple with the set radiobiology model-based constraint functions.

Parameters:: segmentation (dict) – Dictionary with information on the segmented structures.
Returns:: Flattened tuple with the set radiobiology model-based constraint functions.
Return type:: tuple

pyanno4rt.tools.get_radiobiology_objectives(segmentation)[source]

Get a tuple with the set radiobiology model-based objective functions.

Parameters:: segmentation (dict) – Dictionary with information on the segmented structures.
Returns:: Flattened tuple with the set radiobiology model-based objective functions.
Return type:: tuple

pyanno4rt.tools.identity(value, *args)[source]

Return the identity of the first input parameter.

Parameters:

value (arbitrary) – Value to be returned.
*args (tuple) – Tuple with optional (non-keyworded) parameters.

Returns:

value – See ‘Parameters’.

Return type:

arbitrary

pyanno4rt.tools.inverse_sigmoid(value, multiplier=1, summand=0)[source]

Calculate the inverse sigmoid function value.

Parameters:

value (int, float, tuple or list) – Value(s) at which to calculate the inverse sigmoid function.
multiplier (int or float, default=1) – Multiplicative coefficient in the linear term.
summand (int or float, default=0) – Additive coefficient in the linear term.

Returns:

Value(s) of the inverse sigmoid function.

Return type:

float or tuple

pyanno4rt.tools.load_list_from_file(path)[source]

Load a list of values from a file path.

Parameters:: path (str) – Path to the list file.
Returns:: Loaded list of values.
Return type:: list

pyanno4rt.tools.non_decreasing(array)[source]

Test whether an array is non-decreasing.

Parameters:: array (ndarray) – One-dimensional input array.
Returns:: Indicator for the non-decrease of the array.
Return type:: bool

pyanno4rt.tools.non_increasing(array)[source]

Test whether an array is non-increasing.

Parameters:: array (ndarray) – One-dimensional input array.
Returns:: Indicator for the non-increase of the array.
Return type:: bool

pyanno4rt.tools.monotonic(array)[source]

Test whether an array is monotonic.

Parameters:: array (ndarray) – One-dimensional input array.
Returns:: Indicator for the monotonicity of the array.
Return type:: bool

pyanno4rt.tools.sigmoid(value, multiplier=1, summand=0)[source]

Calculate the sigmoid function value.

Parameters:

value (int, float, tuple or list) – Value(s) at which to calculate the sigmoid function.
multiplier (int or float, default=1) – Multiplicative coefficient in the linear term.
summand (int or float, default=0) – Additive coefficient in the linear term.

Returns:

Value(s) of the sigmoid function.

Return type:

float or tuple

pyanno4rt.tools.snapshot(instance, path, include_patient_data=False, include_dose_matrix=False, include_model_data=False)[source]

Take a snapshot of a treatment plan.

Parameters:

instance (object of class from base) – The base treatment plan class from which to take a snapshot.
path (str) –
Directory path for the snapshot (folder).

Note

If the specified path does not reference an existing folder, one is created automatically.
include_patient_data (bool, default=False) – Indicator for the storage of the external patient data, i.e., computed tomography and segmentation data.
include_dose_matrix (bool, default=False) – Indicator for the storage of the dose-influence matrix.
include_model_data (bool, default=False) – Indicator for the storage of the outcome model-related dataset(s).

Raises:

AttributeError – If the treatment plan instance has not been configured yet.

pyanno4rt.tools.replace_nan(elements, value)[source]

Replace NaN in an iterable by a specific value.

Parameters:

elements (iterable) – Iterable over which to loop.
value (arbitrary) – Value by which to replace NaNs.

Returns:

Generator with the replaced elements.

Return type:

generator