xhydro.extreme_value_analysis.structures package¶

Python and Julia structures used in the extreme value analysis and their conversion rules.

Submodules¶

xhydro.extreme_value_analysis.structures.conversions module¶

Conversion functions between Julia and Python objects.

xhydro.extreme_value_analysis.structures.conversions.jl_matrix_tuple_to_py_list(jl_matrix_tuple) → list[tuple][source]¶

Convert a julia matrix of tuples to a python list of tuples.

Parameters¶

jl_matrix_tuplejulia.Matrix[Tuple]: The julia.Matrix[Tuple] object to convert.

Returns¶

list[tuple]: The converted list[tuple] object.

xhydro.extreme_value_analysis.structures.conversions.jl_vector_to_py_list(jl_vector) → list[source]¶

Convert a Julia vector to a python list.

Parameters¶

jl_vectorjulia.Vector: The julia.Vector object to convert.

Returns¶

list: The converted list object.

xhydro.extreme_value_analysis.structures.conversions.jl_vector_tuple_to_py_list(jl_vector_tuple) → list[source]¶

Convert a julia vector containing a single tuple (i.e. [(1,2,3)]) to a python list (i.e. [1,2,3]).

Parameters¶

jl_vector_tuplejulia.Vector[Tuple]: The julia.Vector object to convert.

Returns¶

list: The converted list object.

xhydro.extreme_value_analysis.structures.conversions.py_list_to_jl_vector(py_list: list)[source]¶

Convert a python list to a Julia Vector object.

Parameters¶

py_listlist: The list object to convert.

Returns¶

julia.Vector: The converted Julia Vector object.

Raises¶

ValueError: If the list contains mixed types that are not all strings or numbers. If the list contains unsupported types/complex structures such that it cannot be converted to a Julia Vector.

xhydro.extreme_value_analysis.structures.conversions.py_str_to_jl_symbol(string: str)[source]¶

Convert a python string to a Julia Symbol object.

Parameters¶

stringstr: The string object to convert.

Returns¶

julia.Symbol: The converted Julia Symbol object.

xhydro.extreme_value_analysis.structures.conversions.py_variable_to_jl_variable(py_var: Variable)[source]¶

Convert a python Variable object to a Julia Variable object.

Parameters¶

py_varVariable: The Variable object to convert.

Returns¶

julia.Extremes.Variable: The converted Julia Variable object.

xhydro.extreme_value_analysis.structures.dataitem module¶

DataItem, Variable and VariableStd classes. Python equivalents to classes of the same names in Extremes.jl.

class xhydro.extreme_value_analysis.structures.dataitem.DataItem[source]¶

Bases : object

Abstract base class for Variable and VariableStd classes.

class xhydro.extreme_value_analysis.structures.dataitem.Variable(name: str, value: list[float])[source]¶

Bases : DataItem

Variable class.

Parameters¶

namestr: Name of the Variable.
valuelist of float: Values of the Variable.

name: str¶

value: list[float]¶

class xhydro.extreme_value_analysis.structures.dataitem.VariableStd(name: str, value: list[float], offset: float, scale: float)[source]¶

Bases : DataItem

VariableStd class.

Parameters¶

namestr: Name of the VariableStd.
valuelist of float: Values of the VariableStd.
offsetfloat: Offset applied to the values of the VariableStd.
scalefloat: Scale factor applied to the values of the VariableStd.

name: str¶

offset: float¶

scale: float¶

value: list[float]¶

xhydro.extreme_value_analysis.structures.util module¶

Utility functions for parameter estimation.

xhydro.extreme_value_analysis.structures.util.create_nan_mask(*nested_lists) → list[source]¶

Create a mask indicating NaN positions across multiple nested lists.

Parameters¶

*nested_liststuple of list of lists # noqa: RST213: Any number of nested lists (lists of lists).

Returns¶

mask :: A single list mask with True where NaNs are present for all the nested lists. Example: np.array([True, False, True, True, False]).

Notes¶

This function is useful when the fitting data and covariates contains NaNs and needs to be pruned. To ensure that the covariate data remains aligned with the fitting data, the function returns a mask with True values where there is at least one NaN either in the data or in the covariates.

Examples¶

>>> fitting_data = [1, 2, np.nan, 4, 5]
>>> loc_covariate = [6, 5, 7, 8, 9]
>>> shape_covariate = [9, 7, 6, 5, np.nan]
>>> match_length(fitting_data, [loc_covariate, shape_covariate])
>>> [False, False, True, False, True]

xhydro.extreme_value_analysis.structures.util.exponentiate_logscale(params: ndarray, dist: str, n_loccov: int, n_scalecov: int) → ndarray[source]¶

Exponentiate the logscale parameter along with covariates to obtain actual scale parameter.

Parameters¶

paramsnp.ndarray: The fitted parameters, including covariates.
diststr or rv_continuous: The univariate distribution to fit, either as a string or as a distribution object. Supported distributions include genextreme, gumbel_r, genpareto.
n_loccovint: Number of covariates for the location parameter.
n_scalecovint: Number of covariates for the scale parameter.

Returns¶

np.ndarray: Updated list with the exponential of the logscale parameter and covariates.

xhydro.extreme_value_analysis.structures.util.insert_covariates(param_names: list[str], covariates: list[str], param_name: str) → list[str][source]¶

Insert appropriate covariate names in the parameter names list.

Parameters¶

param_nameslist[str]: List of parameter names in which to insert the covariate names.
covariateslist[str]: List of covariate names to insert in the parameter names.
param_namestr: Name of the parameter (such as « loc », « shape », « scale ») after which the covariates are inserted.

Returns¶

list[str]: Updated list of parameter names with the appropriate covariates in the right place.

Examples¶

>>> insert_covariates(["shape", "loc", "scale"], ["temperature", "year"], "loc")
>>> ["shape", "loc", "loc_temperature_covariate", "loc_year_covariate", "scale"]

xhydro.extreme_value_analysis.structures.util.jl_variable_fit_parameters(covariate_list: list[list]) → Any[source]¶

Transform a list of lists into a julia.Vector of julia.Extremes.Variable objects.

Parameters¶

covariate_listlist[list]: Covariates” data for a single parameter.

Returns¶

julia.Vector[julia.Extremes.Variables]: The sequence of julia Variables to be used in non-stationary parameter estimation.

Notes¶

This function is necessary for non-stationary parameter estimation: see example at extreme_value_analysis/parameterestimation.gevfit().

xhydro.extreme_value_analysis.structures.util.param_cint(jl_model: Any, method: str, confidence_level: float = 0.95) → list[ndarray][source]¶

Return a list of parameters and confidence intervals for a given Julia fitted model.

Parameters¶

jl_modelJulia.Extremes.AbstractExtremeValueModel: Fitted Julia model.
method{« ML », « PWM », « BAYES »}: The fitting method, which can be maximum likelihood (ML), probability weighted moments (PWM), or Bayesian inference (BAYES).
confidence_levelfloat: The confidence level for the confidence interval of each parameter. Defaults to 0.95.

Returns¶

list[np.ndarray]: A list containing NumPy arrays for the estimated parameters, and upper bounds for the confidence interval of each parameter.

xhydro.extreme_value_analysis.structures.util.recover_nan(mask: ndarray | list[bool], lists: ndarray | list[list[float]]) → list[list[float]][source]¶

Recover the original length of lists by filling NaN in masked positions.

Parameters¶

masknp.ndarray: A masked array indicating positions of valid data. Example: np.array([True, False, True, True, False]).
listsnp.ndarray or list[list[float]]: A list of arrays to be recovered.

Returns¶

list[list[float]]: A list of lists with NaNs filled in the original masked positions.

xhydro.extreme_value_analysis.structures.util.remove_nan(mask: array, covariates: list[list]) → list[list][source]¶

Remove entries from a list of lists based on a boolean mask.

Parameters¶

masknp.array: Array containing the True and False values.
covariateslist[list]: List of lists from which values will be removed according to the mask.

Returns¶

list[list]: A new list containing the list without the masked values.

xhydro.extreme_value_analysis.structures.util.return_level_cint(jl_model, dist: str, method: str, confidence_level: float = 0.95, return_period: float = 100, threshold_pareto: float | None = None, nobs_pareto: int | None = None, nobsperblock_pareto: int | None = None) → dict[str, list[float]][source]¶

Return a list of return levels and confidence intervals for a given Julia fitted model.

Parameters¶

jl_modelJulia.Extremes.AbstractExtremeValueModel: Fitted Julia model.
diststr or rv_continuous: Distribution, either as a string or as a distribution object. Supported distributions include genextreme, gumbel_r, genpareto.
method{« ML », « PWM », « BAYES »}: The fitting method, which can be maximum likelihood (ML), probability weighted moments (PWM), or Bayesian inference (BAYES).
confidence_levelfloat: The confidence level (between 0 and 1) for the confidence interval of the return level. Defaults to 0.95.
return_periodfloat: Return period used to compute the return level.
threshold_paretofloat: Threshold. Required when dist=genpareto.
nobs_paretoint: Number of total observation. Required when dist=genpareto.
nobsperblock_paretoint: Number of observation per block. Required when dist=genpareto.

Returns¶

dict[str, list[float]]: A dictionary containing the estimated parameters and the lower and upper bounds for the confidence interval of each parameter.

xhydro.extreme_value_analysis.structures.util.return_nan(length: int) → list[ndarray][source]¶

Return a list of three lists, each containing NaN values of the specified length.

Parameters¶

lengthint: The length of each list.

Returns¶

list[np.ndarray]: A list containing three lists, each of which contains NaN values of the given length.