Module `ctsimu.helpers`

Functions

def abspath_of_referenced_file(filepath: str, referenced: str) ‑> str

Get the absolute path of an external file referenced in file.

Parameters

filepath : str: The path of a file (e.g. scenario or metadata) in which an external file is referenced.
referenced : str: The path (relative to filepath or absolute) of the referenced file.

Returns

referenced_abs : str: Absolute path of the referenced file.

def backslash_to_slash(s: str) ‑> str

Convert backslashed to slashes, used for Windows paths.

Parameters

s : str: String in which the replace will take place.

Returns

converted : str: String where backslashes are replaced by slashes.

def convert(converter_dict: dict, key: str) ‑> str

Map a string to a different (converted) string.

Parameters

converter_dict : dict: Mapping dictionary.
key : str: Key to be converted.

Returns

mapped_value : str: String that's mapped to the key.

def convert_SNR_FWHM(SNR_or_FWHM: float, mean: float) ‑> float

Converts between SNR and Gaussian FWHM for a given mean value of the Gaussian distribution (e.g., intensity).

Parameters

SNR_or_FWHM : float: SNR value (signal to noise ratio) or FWHM value (full width at half maximum).
mean : float: Mean value of the Gaussian distribution.

Returns

FWHM_or_SNR : float: FWHM if an SNR was given, or the SNR if an FWHM was given.

def convert_str_to_float(string)

def convert_to_native_unit(given_unit: str, native_unit: str, value: float) ‑> float | str | bool

Check which native unit is requested, convert value accordingly.

If the native_unit is set to None, the value will simply be returned as it is (i.e., unaltered).

Parameters

given_unit : str: The unit of the given value.
native_unit : str: The native unit into which the value must be converted. Possible values: None, "mm", "rad", "deg", "s", "mA", "kV", "g/cm^3", "lp/mm", "deg/s", "C", "bool", "string".
value : float or str or bool: Value to convert.

Returns

value_in_native_unit : float or str or bool: Converted value.

Raises

ValueError: If the given_unit is not compatible with the native_unit. For example, the function cannot convert a length into a time.

def convert_to_preferred_unit(preferred_unit: str, native_unit: str, value: float)

Convert a value from its native unit to the preferred unit.

Parameters

preferred_unit : str: Preferred unit to be returned.
native_unit : str: Value's current native unit.
value : float: Value in its native unit.

Returns

value : float: Value in preferred unit.

def counter_format(n: int, zero_padding: bool = True) ‑> str

Create a default counter format for sequentially numbered files.

Parameters

n : int: Number of files, starting from zero.
zero_padding : bool: Are the files zero-padded from the left?

Returns

counter_format : str: Counter format string, e.g. '%05d' for n=20000 files. At least four digits will be assumed, even if n is smaller.

def divide_and_error(muA: float, muB: float, errA: float, errB: float) ‑> tuple[float, float]

Error propagation upon division; estimation of largest error.

def divide_and_gaussian_error(muA: float, muB: float, sigmaA: float, sigmaB: float) ‑> tuple[float, float]

Gaussian error propagation upon division.

def from_bool(value) ‑> bool

Convert value into a true Python boolean. (For example, 1 becomes True, and 0 becomes False.)

Parameters

value: Any value that can be checked with a Python if.

Returns

b : bool: True if the value evaluates to True, otherwise False.

def gaussian(x: float, mu: float, sigma: float, A: float) ‑> float

Gaussian function.

Parameters

x : float: Input value (x axis).
mu : float: Distribution's mean value.
sigma : float: Distribution's standard deviation.
A : float: Distribution's amplitude, i.e., the maximum value.

Returns

y : float: Output value (y axis). y = A * exp((x-mu)**2 / (2*sigma**2))

def get_value(dictionary: dict, keys: list, fail_value=None) ‑> float | str | bool | dict | list

Get the specific value of the parameter that is located at the given sequence of keys in the JSON dictionary.

If that element cannot be found or is set to null, return the fail_value.

Parameters

dictionary : dict: Dictionary (as from a JSON structure).
keys : list: List of keys that identify a location in the dictionary tree.
fail_value : float or str or bool or dict or list, optional: Value to return if the given list of keys cannot be found in the dictionary.

Returns

value : float or str or bool or dict or list: The entry in the dictionary, located by the sequence of keys or the fail_value if the entry cannot be found.

Raises

TypeError: If dictionary is not a Python dict.

def get_value_in_native_unit(native_unit: str, dictionary: dict, keys: list, fail_value=None) ‑> float | str | bool

Get a parameter value in the native_unit, located at a sequence of keys in a given dictionary.

Parameters

native_unit : str: The native unit into which the value will be converted. Possible values: None, "mm", "rad", "deg", "s", "mA", "kV", "g/cm^3", "lp/mm", "deg/s", "C", "bool", "string".
dictionary : dict: Dictionary representation of the JSON structure.
keys : list: List of strings that identify the location of the paramter in the dictionary.
fail_value : float or str or bool: The value that will be returned if nothing can be found at the given sequence of keys.

Returns

value_in_native_unit : float or str or bool: Converted value or fail_value if nothing could be found.

Raises

ValueError: If the unit given in the dictionary is not compatible with the requested native_unit. For example, the function cannot convert a length into a time. Also, if no valid value/unit pair is provided in the given value_and_unit dictionary.

def get_value_or_none(dictionary: dict, *keys: str) ‑> float | str | bool | dict | list

Get the dictionary value that is located at the given sequence of keys. If it cannot be found, return None.

Parameters

dictionary : dict: Dictionary (as from a JSON structure).
*keys : str: Sequence of keys that identify a location in the dictionary tree.

Returns

value : float or str or bool or dict or list: The entry in the dictionary, located by the sequence of keys, or None if the entry cannot be found.

Raises

TypeError: If dictionary is not a Python dict.

def in_celsius(value: float, unit: str) ‑> float

Convert a temperature to degree Celsius.

Parameters

value : float: The value to convert.
unit : str: The value's current unit. Options are: "C", "K", "F"

Returns

value_in_celsius : float: The value converted to degree Celsius, or 'None' if the original value was None.

Raises

ValueError: If the given unit is not a valid unit for temperature.

def in_deg(value: float, unit: str = 'rad') ‑> float

Convert an angle to degrees.

Parameters

value : float: The value to convert.
unit : str: The value's current unit. Options are: "rad", "deg"

Returns

value_in_deg : float: The value converted to degrees, or 'None' if the original value was None.

Raises

ValueError: If the given unit is not a valid angular unit.

def in_deg_per_s(value: float, unit: str) ‑> float

Convert an angular velocity to deg/s.

Parameters

value : float: The value to convert.
unit : str: The value's current unit. Options are: "rad/s", "rad/min", "rad/h", "deg/s", "deg/min", "deg/h"

Returns

value_in_deg_per_s : float: The value converted to degrees per second, or 'None' if the original value was None.

Raises

ValueError: If the given unit is not a valid unit of angular velocity.

def in_fahrenheit(value: float, unit: str) ‑> float

Convert a temperature to Fahrenheit.

Parameters

value : float: The value to convert.
unit : str: The value's current unit. Options are: "C", "K", "F"

Returns

value_in_fahrenheit : float: The value converted to Fahrenheit, or 'None' if the original value was None.

Raises

ValueError: If the given unit is not a valid unit for temperature.

def in_g_per_cm3(value: float, unit: str) ‑> float

Convert a mass density to g/cm³.

Parameters

value : float: The value to convert.
unit : str: The value's current unit. Options are: "kg/m^3", "g/cm^3"

Returns

value_in_g_per_cm3 : float: The value converted to grams per cubic centimeter, or 'None' if the original value was None.

Raises

ValueError: If the given unit is not a valid unit of mass density.

def in_kV(value: float, unit: str) ‑> float

Convert a voltage to kV.

Parameters

value : float: The value to convert.
unit : str: The value's current unit. Options are: "V", "kV", "MV"

Returns

value_in_kV : float: The value converted to kilovolts, or 'None' if the original value was None.

Raises

ValueError: If the given unit is not a valid unit of electric voltage.

def in_kelvin(value: float, unit: str) ‑> float

Convert a temperature to Kelvin.

Parameters

value : float: The value to convert.
unit : str: The value's current unit. Options are: "C", "K", "F"

Returns

value_in_kelvin : float: The value converted to Kelvin, or 'None' if the original value was None.

Raises

ValueError: If the given unit is not a valid unit for temperature.

def in_lp_per_mm(value: float, unit: str) ‑> float

Convert a resolution to line pairs per millimeter.

Parameters

value : float: The value to convert.
unit : str: The value's current unit. Options are: "lp/mm", "lp/cm", "lp/dm", "lp/m"

Returns

value_in_lp_per_mm : float: The value converted to line pairs per millimeter, or 'None' if the original value was None.

Raises

ValueError: If the given unit is not a valid unit for resolution.

def in_mA(value: float, unit: str) ‑> float

Convert an electric current to mA.

Parameters

value : float: The value to convert.
unit : str: The value's current unit. Options are: "uA", "mA", "A"

Returns

value_in_mA : float: The value converted to milliamps, or 'None' if the original value was None.

Raises

ValueError: If the given unit is not a valid unit of electric current.

def in_mm(value: float, unit: str) ‑> float

Convert a length to mm.

Parameters

value : float: The value to convert.
unit : str: The value's current unit. Options are: "nm", "um", "mm", "cm", "dm", "m"

Returns

value_in_mm : float: The value converted to millimeters, or 'None' if the original value was None.

Raises

ValueError: If the given unit is not a valid unit of length.

def in_mm_json(jsonVal: dict) ‑> float

Convert JSON value/unit pair to mm.

def in_rad(value: float, unit: str = 'deg') ‑> float

Convert an angle to radians.

Parameters

value : float: The value to convert.
unit : str: The value's current unit. Options are: "rad", "deg"

Returns

value_in_rad : float: The value converted to rad, or 'None' if the original value was None.

Raises

ValueError: If the given unit is not a valid angular unit.

def in_rad_json(jsonVal: dict) ‑> float

Convert JSON value/unit pair to radians.

def in_s(value: float, unit: str) ‑> float

Convert a time to seconds.

Parameters

value : float: The value to convert.
unit : str: The value's current unit. Options are: "ms", "s", "min", "h"

Returns

value_in_s : float: The value converted to seconds, or 'None' if the original value was None.

Raises

ValueError: If the given unit is not a valid unit of time.

def is_valid_native_unit(native_unit: str) ‑> bool

Check if given string is a valid native unit.

Parameters

native_unit : str: The string to check if it is a valid native unit.

Returns

is_valid : bool: True if the provided string is a valid native unit, False if not.

def is_version_supported(supported_version: dict, version_to_test: dict) ‑> bool

Test if the given version is supported (up to) by the toolbox.

Parameters

supported_version : dict: The version against which should be tested: a dictionary with the keys "major" and "minor". Pass the global variable ctsimu_supported_scenario_version or ctsimu_supported_metadata_version.
version_to_test : dict: The version to test if it is supported. Must be a dictionary with the keys "major" and "minor".

Returns

is_supported : bool: If the given version number is supported by the toolbox scenario module.

def join_dir_and_filename(directory: str, filename: str) ‑> str

Joins directory and filename into a meaningful path.

Parameters

directory : str: Directory part of the path. Set to None for no directory.
filename : str: Filename part of the path.

Returns

full_path : str: Fully joined path.

def json_convert_to_native_unit(native_unit: str, value_and_unit: dict, fallback_json_unit: str = None) ‑> float | str | bool

Convert a value/unit pair from a dictionary into the requested native_unit.

Works like the function convert_to_native_unit(), but takes a JSON object value_and_unit, i.e. a dictionary that must contain a value and an associated unit. Checks which native unit is requested, and converts the JSON value accordingly.

fallback_json_unit is used if the unit is not specified in the value_and_unit JSON object.

Parameters

native_unit : str: The native unit into which the value will be converted. Possible values: None, "mm", "rad", "deg", "s", "mA", "kV", "g/cm^3", "lp/mm", "deg/s", "C", "bool", "string".
value_and_unit : dict: Dictionary that specifies a "value" and a "unit", as imported from a CTSimU JSON parameter object.
fallback_json_unit : str, optional: The fallback unit to be used if the value_and_unit dictionary does not specify a unit.

Returns

value_in_native_unit : float or str or bool: Converted value.

Raises

ValueError: If the unit given in the dictionary is not compatible with the requested native_unit. For example, the function cannot convert a length into a time. Also, if no valid value/unit pair is provided in the given value_and_unit dictionary.

def json_exists(dictionary: dict, keys: list) ‑> bool

Check if the given key sequence can be found in the dictionary tree.

Parameters

dictionary : dict: Dictionary (as from a JSON structure).
keys : list: List of keys that identify a location in the dictionary tree.

Returns

exists : bool: True if the given key sequence identifies an object or value in the dictionary, False if nothing can be found at the given sequence of keys.

Raises

TypeError: If dictionary is not a Python dict.

def json_exists_and_not_null(dictionary: dict, keys: list) ‑> bool

Check if the value at the given key sequence exists and does not correspond to a JSON null.

Parameters

dictionary : dict: Dictionary (as from a JSON structure).
keys : list: List of keys that identify a location in the dictionary tree.

Returns

exists_and_not_null : bool: True if the given key sequence exists and does not identify a null value, False otherwise.

Raises

TypeError: If dictionary is not a Python dict.

def json_extract(dictionary: dict, keys: list) ‑> float | str | bool | dict | list

Get the JSON sub-object that is located at a given sequence of keys in the JSON dictionary.

Parameters

dictionary : dict: Dictionary (as from a JSON structure).
keys : list: List of keys that identify a location in the dictionary tree.

Returns

value : float or str or bool or dict or list: The value, object or array located at the given key sequence, None if nothing can be found at the given key sequence.

Raises

TypeError: If dictionary is not a Python dict.

def json_extract_from_possible_keys(dictionary: dict, key_lists: list)

Searches the JSON object for each key sequence in the given list of key sequences. The first sequence that exists will be used to extract and return the corresponding JSON object.

Parameters

dictionary : dict: Dictionary (as from a JSON structure).
key_lists : list: List of lists of keys that possibly specify a valid location in the dictionary tree.

Returns

value : float or str or bool or dict or list: The value, object or array located at the first valid key sequence, None if nothing can be found at any of the given key sequences.

Raises

TypeError: If dictionary is not a Python dict.

def json_from_pkg(filename: str) ‑> dict

Read a JSON file included in the package.

Parameters

filename : str: Filename of the JSON file.

Returns

dictionary : dict: Dictionary representation of the JSON structure.

def json_isnull(dictionary: dict, keys: list) ‑> bool

Check if the value at the given key sequence corresponds to a JSON null, or if the value cannot be found at all.

Parameters

dictionary : dict: Dictionary (as from a JSON structure).
keys : list: List of keys that identify a location in the dictionary tree.

Returns

is_null : bool: True if the given key sequence identifies a null value or if the value cannot be found at all. False otherwise.

Raises

TypeError: If dictionary is not a Python dict.

def list_mean(l: list) ‑> float

Mean value for a list of values.

Parameters

l : list: List of values, e.g. 'float'.

Returns

mean : float: The mean of the value list.

def list_mean_and_stddev(l: list) ‑> tuple[float, float]

Mean and standard deviation of a list of values.

Parameters

l : list: List of values, e.g. 'float'.

Returns

mean : float: The mean of the value list.
standard_deviation : float: Root mean square deviation (RMSD) of the value list.

def log(message: str)

Print an output message.

Parameters

message : str: Message to be printed.

def object_value_is_null(json_obj: dict) ‑> bool

Check if a CTSimU JSON parameter object represents a null value, either because its "value" property is set to a JSON null or because it does not have a "value" property at all.

Parameters

json_obj : dict: Dictionary (as from a JSON structure) to check.

Returns

is_null : bool: True if the object's "value" corresponds to a JSON null or if the object does not define a "value". False if the object value is something else.

Raises

TypeError: If json_obj is not a dictionary.

def object_value_is_null_or_zero(json_obj: dict) ‑> bool

Check if a CTSimU JSON parameter object represents null value or the numerical value 0, either because its "value" property is set to a JSON null or 0, or because it does not have a "value" property at all.

Parameters

json_obj : dict: Dictionary (as from a JSON structure) to check.

Returns

is_null_or_zero : bool: True if the object's "value" corresponds to a JSON null or if the object does not define a "value". False if the object value is something else.

Raises

TypeError: If json_obj is not a dictionary.

def pkg_scenario(filename: str, level: str = 'root') ‑> str

Return path to scenario file included in this package.

Parameters

filename : str

Filename of the JSON file.

level : str

From where the file needs to be reached.

Possible values: "root", "test"

Returns

scenario_path : dict: Path to the scenario within the package.

def poly4(x, a: float, b: float, c: float, d: float, e: float) ‑> float

Fourth order polynomial, used for smoothing.

Parameters

x : float: Input value (x axis).
a : float
b : float
c : float
d : float
e : float

Returns

y : float: Output value (y axis). y = ax^4 + bx^3 + cx^2 + dx + e

def ratios(values: list) ‑> list

Calculate ratio to preceding value, needed for step wedge evaluations.

def read_csv_file(filename: str) ‑> dict

Read a CSV file.

Parameters

filename : str: Filename of the CSV file to read.

Returns

data : list: Each item in the returned list contains the values of one column from the CSV file.

def read_json_file(filename: str) ‑> dict

Read a JSON file into a Python dictionary.

Parameters

filename : str: Filename of the JSON file.

Returns

dictionary : dict: Dictionary representation of the JSON structure.

def touch_directory(filename: str)

Create folder if it doesn't exist.

Parameters

filename : str: Complete path to a file. Can include filename.

def value_is_null(value) ‑> bool

Check if a specific JSON value is set to null.

Parameters

value: Value to check for nullness.

Returns

is_null : bool: True if the value corresponds to a JSON null, False if it is something else.

def value_is_null_or_zero(value) ‑> bool

Check if a specific value is set to null or 0.

Parameters

value: Value to check for nullness or zeroness.

Returns

is_null_or_zero : bool: True if the value corresponds to a JSON null or has the numerical value 0, False if it is something else.

def write_json_file(filename: str, dictionary: dict)

Write a JSON file from a given Python dictionary.

Parameters

filename : str: Filename of the JSON file.
dictionary : dict: Dictionary for the JSON file.