Utilities (labtoolbox.utils)#

Utilities for LabToolbox.

Includes formatting helpers, safe conversions, and color map utilities.

labtoolbox.utils.PrintResult(value, err, name='', unit='')[source]#

Prints a formatted mean ± sigma representation with sigma rounded to two significant figures.

Parameters:

  • value (scalar or array-like) – Central value(s).

  • err (scalar or array-like) – Uncertainty value(s), must match value shape when array-like.

  • name (str or list of str, optional) – Variable name(s) used as prefix. Defaults to "".

  • unit (str or list of str, optional) – Unit symbol(s) appended to the result. Defaults to "".

Returns:

Output is printed to stdout.

Return type:

None

Raises:

  • TypeError – If inputs are not numeric or incompatible with each other.

  • ValueError – If uncertainty is non-positive or values contain non-finite entries.

labtoolbox.utils.convert(value, from_unit, to_unit)[source]#

Converts a physical quantity between units, supporting SI prefixes, non-SI units and compound units.

Parameters:

  • value (float or or array-like) – Numerical value to be converted.

  • from_unit (str or list of str) – Unit of the i_nput quantity (e.g., ‘erg’, ‘km/s’, ‘eV/Å^3’).

  • to_unit (str or list of str) – Desired target unit (e.g., ‘J’, ‘m/s’, ‘GeV/fm^3’).

Raises:

  • TypeError – If value has invalid type or units are improperly specified.

  • ValueError – If units cannot be parsed or converted.

  • ImportError – If astropy is not installed.

Returns:

Value converted to the target unit.

Return type:

float or numpy.ndarray

labtoolbox.utils.format_str(data, err)[source]#

Formats data and uncertainties into LaTeX strings of the form “$data pm data_err$”.

Parameters:

  • data (float or array-like) – Central values.

  • err (float or array-like) – Uncertainties (must be same shape as data).

Returns:

LaTeX strings like “$data pm data_err$” with proper rounding.

Return type:

list of str

Raises:

  • TypeError – If elements in data or err are not real numbers.

  • ValueError – If shapes of data and err do not match, or if arrays are empty or contain non-finite values.

labtoolbox.utils.genspace(start, stop, num, f, endpoint=True)[source]#

Generate an array of points with spacing determined by a callable function.

Similar to numpy.linspace, but the spacing between points is defined by the function f(x), which specifies the density of points.

Parameters:

  • start (float) – The starting value of the sequence.

  • stop (float) – The end value of the sequence.

  • num (int) – Number of points to generate. Must be positive.

  • f (callable) – A function f(x) that defines the density of points. Must take a float and return a positive float. Higher values of f(x) result in denser points around x.

  • endpoint (bool, optional) – If True, stop is the last point. Otherwise, it is excluded. Defaults to True.

Returns:

A 1D array of num points from start to stop, spaced according to func.

Return type:

numpy.ndarray

Examples

>>> import numpy as np
>>> from labtoolbox.special import genspace
>>> # Linear spacing (equivalent to np.linspace)
>>> x = genspace(0, 1, 5, lambda x: 1.0)
>>> print(x)  # [0.   0.25 0.5  0.75 1.  ]
>>> # Denser points near x=0 with f(x) = 1/x
>>> x = genspace(0.1, 1, 5, lambda x: 1/x)
>>> print(x)  # Points closer together near 0.1
labtoolbox.utils.latex_table(data, header, filename, caption='', label='', align='c')[source]#

Writes a LaTeX-formatted table to file with caption, label, and custom styling.

Parameters:

  • data (list of array-like) – The content of the table, organized as a list of columns (i.e., data[i][j] is value j of column i).

  • header (list of str) – List of column names to appear in the header of the table.

  • filename (str) – Path to the output .tex file (e.g., ‘table.tex’).

  • caption (str, optional) – Caption text of the table.

  • label (str, optional) – Label used for referencing the table in LaTeX.

  • align (str, optional) – Column alignment string (e.g., “lcr”). If a single character (“l”, “c”, or “r”) is given, it is repeated for all columns.

Raises:

  • ValueError – If length of header does not match number of columns in data.

  • TypeError – If data is not a list of numpy arrays, header is not a list of strings, or caption, label, align are not scalars.

Notes

  • Assumes all elements of data and header are convertible to string.

  • Does not escape LaTeX special characters.

  • Assumes data is column-oriented (i.e., each sublist is a column).