Utils Module

firescipy.utils.calculate_RMSE(residuals)[source]

Compute the Root Mean Squared Error (RMSE) from residuals.

RMSE is the square root of the average of the squared residuals. It provides an estimate of the standard deviation of the prediction errors and is commonly used to quantify the accuracy of a model.

Parameters

residuals (array-like) – The residuals (differences between observed and predicted values).

Returns

The RMSE value, representing the standard deviation of residual errors.

Return type

float

firescipy.utils.calculate_R_squared(residuals, data_y)[source]

Calculate the coefficient of determination (R-squared) for a set of data.

R-squared is defined as:

\[R^2 = 1 - (SS_{res} / SS_{tot})\]

where SS_res is the sum of squares of residuals (the differences between the observed and predicted values) and SS_tot is the total sum of squares (the differences between the observed values and their mean). This metric indicates the proportion of the variance in the dependent variable that is explained by the model.

Parameters

  • residuals (array-like) – The residuals (errors) from the fitted model, typically computed as (observed - predicted).

  • data_y (array-like) – The observed data values.

Returns

The R-squared value. Higher values indicate a better fit. Note: R² can be negative if the model performs worse than a constant mean.

Return type

float

firescipy.utils.calculate_residuals(data_y, fit_y)[source]

Compute the residuals between observed data and fitted values.

Residuals are calculated as the difference between actual values (data_y) and predicted values (fit_y). Useful for evaluating the quality of regression or curve fitting results.

Parameters

  • data_y (array-like) – The observed data values.

  • fit_y (array-like) – The predicted or fitted values.

Returns

The residuals, calculated as data_y - fit_y.

Return type

np.ndarray

firescipy.utils.ensure_nested_dict(nested_dict, keys)[source]

Ensures a nested dictionary structure exists the given sequence of keys.

Parameters

  • nested_dict (dict) – The dictionary to operate on. It will be modified in place to include the full nested structure.

  • keys (Sequence) – Sequence of keys representing the path of nested dictionaries to create.

Returns

The final nested dictionary at the end of the path.

Return type

dict

firescipy.utils.gaussian(x, mu, sigma, a=1.0)[source]

Compute the Gaussian (normal) distribution function.

The Gaussian function is defined as shown below.

\[f(x) = \frac{a}{\sigma \sqrt{2\pi}} \exp\left( -\frac{1}{2} \left( \frac{x - \mu}{\sigma} \right)^2 \right)\]
Parameters

  • x (float or ndarray) – The input value(s) where the Gaussian function is evaluated.

  • mu (float) – The mean (center) of the Gaussian distribution.

  • sigma (float) – The standard deviation (spread) of the Gaussian distribution. Must be positive.

  • a (float) – A scaling factor of the Gaussian distribution, default: 1.0.

Returns

The computed value(s) of the Gaussian function at x.

Return type

float or ndarray

firescipy.utils.get_nested_value(nested_dict, keys)[source]

Retrieve a value from a nested dictionary, using a sequence of keys.

Parameters

  • nested_dict (dict) – The nested dictionary to traverse.

  • keys (Sequence) – A sequence of keys (e.g., list or tuple) specifying the path to the data.

Returns

The data at the specified location in the nested dictionary.

Return type

Any

firescipy.utils.linear_model(x, m, b)[source]

Linear model function: y = mx + b.

firescipy.utils.series_to_numpy(data: Union[numpy.ndarray, pandas.core.series.Series]) → numpy.ndarray[source]

Helper function that converts a Pandas Series to a NumPy array if necessary.

Parameters

data (np.ndarray or pd.Series) – Input data to be converted. If already a NumPy array, it is returned unchanged.

Returns

The input data as a NumPy array.

Return type

np.ndarray

firescipy.utils.store_in_nested_dict(nested_dict, new_data, keys)[source]

Stores data in a nested dictionary structure, for the given keys. Intermediate levels will be created if they do not already exist.

Parameters

  • nested_dict (dict) – The dictionary to operate on. It will be modified in place

  • new_data (Any) – Data to store at the specified nested location.

  • keys (Sequence) – Sequence of keys representing the nested path.

Returns

The nested dictionary is changed in place.

Return type

None