Utilities#
In this section you find the reference documentation of the modules contained in the util module.
general#
General functions useful across different parts of the code.
- utils.general.change_dict_keys_case(data_dict, lower_case=True)[source]#
Change keys of a dictionary to lower or upper case recursively.
- Parameters:
- data_dict: dict
Dictionary to be converted.
- lower_case: bool
Change keys to lower (upper) case if True (False).
- Returns:
- dict
Dictionary with keys converted to lower or upper case.
- utils.general.collect_data_from_file_or_dict(file_name, in_dict, allow_empty=False)[source]#
Collect input data from file or dictionary.
- Parameters:
- file_name: str
Name of the yaml/json/ascii file.
- in_dict: dict
Data as dict.
- allow_empty: bool
If True, an error won’t be raised in case both file_name and dict are None.
- Returns:
- data: dict or list
Data as dict or list.
- Raises:
- AttributeError
If no input has been provided (neither by file, nor by dict).
- utils.general.collect_final_lines(file, n_lines)[source]#
Collect final lines.
- Parameters:
- file: str or Path
File to collect the lines from.
- n_lines: int
Number of lines to be collected.
- Returns:
- str
Final lines collected.
- utils.general.collect_kwargs(label, in_kwargs)[source]#
Collect kwargs of the type label_* and return them as a dict.
- Parameters:
- label: str
Label to be collected in kwargs.
- in_kwargs: dict
kwargs.
- Returns:
- dict
Dictionary with the collected kwargs.
- utils.general.get_log_excerpt(log_file, n_last_lines=30)[source]#
Get an excerpt from a log file, namely the n_last_lines of the file.
- Parameters:
- log_file: str or Path
Log file to get the excerpt from.
- n_last_lines: int
Number of last lines of the file to get.
- Returns:
- str
Excerpt from log file with header/footer
- utils.general.get_log_level_from_user(log_level)[source]#
Map between logging level from the user to logging levels of the logging module.
- Parameters:
- log_level: str
Log level from the user.
- Returns:
- logging.LEVEL
The requested logging level to be used as input to logging.setLevel().
- utils.general.remove_substring_recursively_from_dict(data_dict, substring='\n')[source]#
Remove substrings from all strings in a dictionary.
Recursively crawls through the dictionary This e.g., allows to remove all newline characters from a dictionary.
- Parameters:
- data_dict: dict
Dictionary to be converted.
- substring: str
Substring to be removed.
- Raises:
- AttributeError:
if input is not a proper dictionary.
geometry#
A collection of functions related to geometrical transformations.
- utils.geometry.convert_2d_to_radial_distr(hist_2d, xaxis, yaxis, bins=50, max_dist=1000)[source]#
Convert a 2d histogram of positions, e.g. photon positions on the ground, to a 1D distribution.
- Parameters:
- hist_2d: numpy.ndarray
The histogram counts.
- xaxis: numpy.array
The values of the x axis (histogram bin edges) on the ground.
- yaxis: numpy.array
The values of the y axis (histogram bin edges) on the ground.
- bins: float
Number of bins in distance.
- max_dist: float
Maximum distance to consider in the 1D histogram, usually in meters.
- Returns:
- np.array
The values of the 1D histogram with size = int(max_dist/bin_size).
- np.array
The bin edges of the 1D histogram with size = int(max_dist/bin_size) + 1.
- utils.geometry.rotate(x, y, rotation_around_z_axis, rotation_around_y_axis=0)[source]#
Rotate the x and y coordinates of the telescopes.
The two rotations are:
rotation_angle_around_z_axis gives the rotation on the observation plane (x, y)
rotation_angle_around_y_axis allows to rotate the observation plane in space.
The function returns the rotated x and y values in the same unit given. The direction of rotation of the elements in the plane is counterclockwise, i.e., the rotation of the coordinate system is clockwise.
- Parameters:
- x: numpy.array or list
x positions of the entries (e.g. telescopes), usually in meters.
- y: numpy.array or list
y positions of the entries (e.g. telescopes), usually in meters.
- rotation_angle_around_z_axis: astropy.units.rad
Angle to rotate the array in the observation plane (around z axis) in radians.
- rotation_angle_around_y_axis: astropy.units.rad
Angle to rotate the observation plane around the y axis in radians.
- Returns:
- 2-tuple of list
x and y positions of the rotated entry (e.g. telescopes) positions.
- Raises:
- TypeError:
If type of x and y parameters are not valid.
- RuntimeError:
If the length of x and y are different.
- UnitsError:
If the unit of x and y are different.
names#
Validation of names.
- utils.names.generate_file_name(file_type, suffix, site, telescope_model_name, zenith_angle, azimuth_angle=None, off_axis_angle=None, source_distance=None, mirror_number=None, label=None, extra_label=None)[source]#
Generate a file name for output, config, or plotting.
Used e.g., to generate camera-efficiency and ray-tracing output files.
- Parameters:
- file_type: str
Type of file (e.g., config, output, plot)
- suffix: str
File suffix
- site: str
South or North.
- telescope_model_name: str
LSTN-01, MSTS-01, …
- zenith_angle: float
Zenith angle (deg).
- azimuth_angle: float
Azimuth angle (deg).
- off_axis_angle: float
Off-axis angle (deg).
- source_distance: float
Source distance (km).
- mirror_number: int
Mirror number.
- label: str
Instance label.
- extra_label: str
Extra label.
- Returns:
- str
File name.
- utils.names.get_array_element_type_from_name(name)[source]#
Get array element type from name, e.g. “LSTN”, “MSTN”.
- Parameters:
- name: str
Array element name
- Returns:
- str
Array element type.
- utils.names.get_site_from_array_element_name(name)[source]#
Get site name from array element name.
- Parameters:
- name: str
Array element name.
- Returns:
- str
Site name (South or North).
- utils.names.layout_telescope_list_file_name(name, label)[source]#
File name for files required at the RayTracing class.
- Parameters:
- name: str
Name of the array.
- label: str
Instance label.
- Returns:
- str
File name.
- utils.names.sanitize_name(name)[source]#
Sanitize name to be a valid Python identifier.
Replaces spaces with underscores
Converts to lowercase
Removes characters that are not alphanumerics or underscores
If the name starts with a number, prepend an underscore
- Parameters:
- name: str
name to be sanitized.
- Returns:
- str:
Sanitized name.
- Raises:
- ValueError:
if the string name can not be sanitized.
- utils.names.simtel_config_file_name(site, model_version, array_name=None, telescope_model_name=None, label=None, extra_label=None)[source]#
sim_telarray config file name for a telescope.
- Parameters:
- site: str
South or North.
- telescope_model_name: str
LST-1, MST-FlashCam, …
- model_version: str
Version of the model.
- label: str
Instance label.
- extra_label: str
Extra label in case of multiple telescope config files.
- Returns:
- str
File name.
- utils.names.simtel_single_mirror_list_file_name(site, telescope_model_name, model_version, mirror_number, label)[source]#
sim_telarray mirror list file with a single mirror.
- Parameters:
- site: str
South or North.
- telescope_model_name: str
North-LST-1, South-MST-FlashCam, …
- model_version: str
Version of the model.
- mirror_number: int
Mirror number.
- label: str
Instance label.
- Returns:
- str
File name.
- utils.names.validate_array_element_id_name(name)[source]#
Validate array element ID.
Allowed IDs are - design (for design array elements or testing) - array element ID (e.g., 1, 5, 15) - test (for testing)
- Parameters:
- name: str or int
Array element ID name.
- Returns:
- str
Validated array element ID (added leading zeros, e.g., 1 is converted to 01).
- Raises:
- ValueError
If name is not valid.
value_conversion#
Value and quantity conversion.
- utils.value_conversion.extract_type_of_value(value) str[source]#
Extract the string representation of the the type of a value.
For example, for a string, it returns ‘str’ rather than ‘<class ‘str’>’. Take into account also the case where the value is a numpy type.
- utils.value_conversion.get_value_as_quantity(value, unit)[source]#
Get a value as a Quantity with a given unit. If value is a Quantity, convert to the given unit.
- Parameters:
- value:
value to get a unit. It can be a float, int, or a Quantity (convertible to ‘unit’).
- unit: astropy.units.Unit
Unit to apply to ‘quantity’.
- Returns:
- astropy.units.Quantity
Quantity of value ‘quantity’ and unit ‘unit’.
- Raises:
- u.UnitConversionError
If the value cannot be converted to the given unit.
- utils.value_conversion.get_value_unit_type(value, unit_str=None)[source]#
Get the value, unit and type of a value.
The value is stripped of its unit and the unit is returned in its string form (i.e., to_string()). The type is returned as a string representation of the type. For example, for a string, it returns ‘str’ rather than ‘<class ‘str’>’. An additional unit string can be given and the return value is converted to this units.
Note that Quantities are always floats, even if the original value is represented as an int.
- Parameters:
- value: str, int, float, bool, u.Quantity
Value to be parsed.
- unit_str: str
Unit to be used for the value.
- Returns:
- type of value, str, str
Value, unit in string representation (to_string())), and string representation of the type of the value.
- utils.value_conversion.split_value_and_unit(value)[source]#
Split a value into its value and unit.
Takes into account the case where the value is a Quantity, a number, or a simtools-type string encoding a list of values and units.
- Parameters:
- value: str, int, float, bool, u.Quantity
Value to be parsed.
- Returns:
- value, str
Value and units as (value, unit), or lists of values and unites
constants#
Project wide constants.