Data Module¶

penred data module

pyPenred.data.configFile2YAML(arg0: str) → str¶

Reads a configuration file and returns a YAML string with the read information.

Parameters:: filename (str) – File to be read.
Returns:: String containing the information in YAML format

pyPenred.data.dict2SectionString(conf: dict) → str¶

Converts a dictionary to a compatible penRed configuration section string.

Parameters:: conf (dict) – configuration dictionary to be converted.
Returns:: String containing the converted dictionary

pyPenred.data.printResults(filename: str, values: Annotated[numpy.typing.ArrayLike, numpy.float64], sigma: Annotated[numpy.typing.ArrayLike, numpy.float64], info: list, value_header: str = 'Value', print_sigmas: SupportsInt | SupportsIndex = 2, print_coordinates: bool = True, print_bins: bool = True) → None¶

Print the provided data as standard penRed’s results file.

Parameters:

filename (str) – Results filename.
values (vector) – Numpy vector with the values to be saved
sigma (vector) – Numpy vector with the uncertainty of each value corresponding to one sigma
info (list) – List of tuples where each element contains the information of the corresponding dimension. Each element must use the following format: (min, max, header), where min and max are the minimum and maximum grid value for this dimension, respectively, and header the text header for dimension’s column.
value_header (str) – Header assigned to values. An example for a energetic spectrum could be ‘E (eV)’.
print_sigmas (int) – Specify the number of printed sigmas, i.e. the uncertainties column will be transformed as print_sigmas*sigma
print_coordinates (bool) – If enabled, the coordinates of each dimension will be printed
print_bins (bool) – If enabled, the bin number of each dimension will be printed

Returns:

None

Raises:

TypeError – Incompatible types have been provided.
ValueError – Dimensions mismatch or incompatible values have been provided.
RuntimeError – Unable to open output file

pyPenred.data.readResults(filename: str, extract_info: bool = False) → tuple¶

Reads a penRed standard results file and convert it to numpy arrays.

Parameters:

filename (str) – Results filename.
extract_info (bool) – If enabled, the information of each dimension will be read as well. Defaults to false.

Returns:

A tuple containing the data, uncertainties and, if enabled, information of each dimension (lower grid limit, upper grid limits, dimension header), value header, file description

Results classes¶

The module exposes the following classes with different maximum dimensionality:

Class	Stored data
`results1D`	1-dimensional buffer
`results2D`	2-dimensional buffer
`results3D`	3-dimensional buffer
`results4D`	4-dimensional buffer
`results5D`	5-dimensional buffer
`results6D`	6-dimensional buffer
`results7D`	7-dimensional buffer
`results8D`	8-dimensional buffer
`results9D`	9-dimensional buffer
`results10D`	10-dimensional buffer
`results`	buffer with maximum dimensions available (30)

They all share the same interface; only the dimensionality of the underlying buffer differs. See results below for the full method reference.

class pyPenred.data.results¶

Bases: pybind11_object

Results container for a maximum of 30D data.

Stores values and their uncertainties on a 30-dimensional grid.

__init__(self: results) → None¶

bins(self: results, dimension: SupportsInt | SupportsIndex = 31) → int¶

Parameters:: dimension (int) – The dimension for which the number of bins is requested. If this value exceeds the maximum number of dimensions, or it is not provided, the total number of bins across all dimensions is returned instead.
Returns:: The number of bins in the specified dimension, or the total number of bins if the dimension is out of bounds.
Return type:: int
Raises:: None –

data(self: results) → tuple¶

Extract result’s data as numpy arrays

Parameters:: None
Returns:: A tuple containing three elements. First, two numpy arrays with the values and uncertainties respectivelly, and then a list with the dimension’s information.
Raises:: ValueError – If transformation fails. If that happens, please, report the error.

description(self: results) → str¶

Reads the results’ description

Parameters:: None
Returns:: A string containing the results’ description
Raises:: None –

extractSpectrum1D(self: results, spectrum_dim: SupportsInt | SupportsIndex, positions: Annotated[Sequence[SupportsFloat | SupportsIndex], 'FixedSize(29)']) → tuple¶

Creates a 1D spectrum for the specified dimension and position within the grid interpolation values and uncertainties in each dimension

Parameters:

spectrum_dim (int) – Dimension to extract the spectrum from.
positions (list) – Positions for the remaining dimensions. The spectrum dimension is not included. Therefore, the position list must have nDim-1 elements, where nDim is the maximum dimensions for the current results object.

Returns:

A tuple containing the interpolated spectrum values and uncertainties.

Raises:

ValueError – If the interpolation fails.

extractValue(self: results, position: Annotated[Sequence[SupportsFloat | SupportsIndex], 'FixedSize(30)']) → tuple¶

Interpolate the value within the grid at the specified position in each dimension

Parameters:: position (list) – List of positions for each dimension within the grid.
Returns:: A tuple containing the interpolated value and uncertainty.
Raises:: ValueError – If the interpolation fails.

fill(self: results, values: Annotated[numpy.typing.ArrayLike, numpy.float64], sigma: Annotated[numpy.typing.ArrayLike, numpy.float64], info: list, value_header: str = 'Value') → None¶

Fills the results object with the provided data.

Parameters:

values (vector) – Numpy vector with the values to be saved
sigma (vector) – Numpy vector with the uncertainty of each value corresponding to one standard deviation
info (list) – List of tuples where each element contains the information of the corresponding dimension. Each element must use the following format: (min, max, header), where min and max are the minimum and maximum grid value for this dimension, respectively, and header the text header for dimension’s column.
value_header (str) – Header assigned to values. An example for a energetic spectrum could be ‘E (eV)’.

Returns:

None

Raises:

TypeError – Incompatible types have been provided.
ValueError – Dimensions mismatch or incompatible values have been provided.

load(self: results, filename: str) → None¶

Load results from a text file

Parameters:: filename (str) – Data file.
Returns:: None
Raises:: ValueError – If file parsing fails or the fail is unrecheable.

maxDim(self: results) → int¶

Parameters:: None
Returns:: The maximum number of dimensions
Raises:: None –

save(self: results, filename: str, print_sigmas: SupportsInt | SupportsIndex = 2, print_coordinates: bool = True, print_bins: bool = True) → None¶

Writes the stored data as standard penRed’s results file.

Parameters:

filename (str) – Results filename.
print_sigmas (int) – Specify the number of printed sigmas, i.e. the uncertainties column will be transformed as print_sigmas*sigma
print_coordinates (bool) – If enabled, the coordinates of each dimension will be printed
print_bins (bool) – If enabled, the bin number of each dimension will be printed

Returns:

None

Raises:

ValueError – If file parsing fails or the fail is unrecheable.

title(self: results) → str¶

Reads the results’ title

Parameters:: None
Returns:: A string containing the results title
Raises:: None –

Dimension-specific methods¶

`results1D`¶

class pyPenred.data.results1D¶

Bases: pybind11_object

Results container for a maximum of 1D data.

Stores values and their uncertainties on a 1-dimensional grid.

__init__(self: results1D) → None¶

extractValue1D(self: results1D, x: SupportsFloat | SupportsIndex) → tuple¶

Interpolate the value within the 1D grid at the specified position

Parameters:: x (float) – Positions within the grid.
Returns:: A tuple containing the interpolated value and uncertainty.
Raises:: ValueError – If the interpolation fails.

`results2D`¶

class pyPenred.data.results2D¶

Bases: pybind11_object

Results container for a maximum of 2D data.

Stores values and their uncertainties on a 2-dimensional grid.

__init__(self: results2D) → None¶

extractValue2D(self: results2D, x: SupportsFloat | SupportsIndex, y: SupportsFloat | SupportsIndex) → tuple¶

Interpolate the value within the 2D grid at the specified position

Parameters:

x (float) – Positions within the grid for the first dimension.
y (float) – Positions within the grid for the second dimension.

Returns:

A tuple containing the interpolated value and uncertainty.

Raises:

ValueError – If the interpolation fails.

`results3D`¶

class pyPenred.data.results3D¶

Bases: pybind11_object

Results container for a maximum of 3D data.

Stores values and their uncertainties on a 3-dimensional grid.

__init__(self: results3D) → None¶

extractValue3D(self: results3D, x: SupportsFloat | SupportsIndex, y: SupportsFloat | SupportsIndex, z: SupportsFloat | SupportsIndex) → tuple¶

Interpolate the value within the 3D grid at the specified position

Parameters:

x (float) – Positions within the grid for the first dimension.
y (float) – Positions within the grid for the second dimension.
z (float) – Positions within the grid for the third dimension.

Returns:

A tuple containing the interpolated value and uncertainty.

Raises:

ValueError – If the interpolation fails.