Validation¶

The validation module provides a set of functions used internally to validate and format inputs throughout mellon. These functions ensure that data meets the required standards and formats, promoting consistency and reliability within the package. They are made accessible here to assist developers in implementing custom features in mellon, such as those within a Jupyter notebook.

mellon.validation.validate_1d(x)View on GitHub ¶

Validates that x can be cast to a JAX array with exactly 1 dimension and float data type.

Parameters:: x (array-like or scalar) – The input data to be validated and cast.
Returns:: The validated and cast data. If x is a scalar, it is transformed into a 1D array with a single element.
Return type:: array-like
Raises:: ValueError – If x cannot be cast to a JAX array with exactly 1 dimension.

mellon.validation.validate_array(iterable, name, optional=False, ndim=None)View on GitHub ¶

Validates and converts an iterable to a numpy array of type float. Allows Jax’s JVPTracer objects and avoids explicit conversion in these cases.

Parameters:

iterable (iterable or None) – The iterable to be validated and converted. If optional=True, can also be None.
name (str) – The name of the variable, used in error messages.
optional (bool, optional) – If True, ‘iterable’ can be None and the function will return None in this case. If False and ‘iterable’ is None, a TypeError is raised. Defaults to False.
ndim (int or tuple of ints, optional) – The number of dimensions the array must have. If specified and the number of dimensions of ‘iterable’ is not in ‘ndim’, a ValueError is raised.

Returns:

The input iterable converted to a numpy array of type float, or the input JVPTracer.

Return type:

numpy.ndarray or jax._src.interpreters.ad.JVPTracer

Raises:

TypeError – If ‘iterable’ is not iterable and not None, or if ‘iterable’ is None and optional=False.
ValueError – If ‘iterable’ can’t be converted to a numpy array of type float, or if the number of dimensions of ‘iterable’ is not in ‘ndim’.

mellon.validation.validate_bool(value, name, optional=False)View on GitHub ¶

Validates whether a given value is a boolean.

Parameters:

value (any) – The value to be validated.
name (str) – The name of the parameter to be used in the error message.
optional (bool, optional) – If True, ‘value’ can be None and the function will return None in this case. If False and ‘value’ is None, a TypeError is raised. Defaults to False.

Returns:

The validated value as a boolean.

Return type:

bool

Raises:

TypeError – If the value is not of type bool.

mellon.validation.validate_float(value, param_name, optional=False)View on GitHub ¶

Validates if the input is a float or can be converted to a float.

Parameters:

value (object) – Input to be checked.
param_name (str) – Name of the input parameter, used for error messaging.
optional (bool, optional) – If True and the input is None, None will be returned. Otherwise, if the input is None, it raises an error. By default, False.

Returns:

The input converted to float.

Return type:

float

Raises:

ValueError – If the input is not a float, integer, or a one-element array, or if the input is None and optional=False.

mellon.validation.validate_float_or_int(value, param_name, optional=False)View on GitHub ¶

Validates whether a given value is a float or an integer, and not nan.

Parameters:

value (float, int, or string, or None) – The value to be validated. It should be a float, integer, or convertible to a float.
param_name (str) – The name of the parameter to be used in the error message.
optional (bool, optional) – Whether the value is optional. If optional and value is None, returns None. Default is False.

Returns:

The validated value as float or int.

Return type:

float or int

Raises:

ValueError – If the value is not float, int, convertible to float, and not None when not optional.

mellon.validation.validate_float_or_iterable_numerical(value, name, optional=False, positive=False)View on GitHub ¶

Validates whether a given value is a float, integer, or iterable of numerical values, with an option to check for non-negativity.

Parameters:

value (int, float, Iterable or None) – The value to be validated.
name (str) – The name of the parameter to be used in the error message.
optional (bool, optional) – Whether the value is optional. If optional and value is None, returns None. Default is False.
positive (bool, optional) – Whether to validate that the value is non-negative. Default is False.

Returns:

The validated value as a float or a numeric array.

Return type:

float or ndarray

Raises:

TypeError – If the value is not of type int, float or iterable.
ValueError – If the value could not be converted to a numeric array (if iterable) or if the value is negative (if positive is True).

mellon.validation.validate_nn_distances(nn_distances, optional=False)View on GitHub ¶

Validates and corrects nearest neighbor distances. Ensures all distances are positive and handles invalid values.

Parameters:

nn_distances (array-like or None) – The input nearest neighbor distances to be validated and corrected. If None and optional is True, the function returns None.
optional (bool, optional) – If True, the function accepts nn_distances as None and returns None.

Returns:

The validated and corrected nearest neighbor distances. Identical or invalid cells have their distances set to the minimum positive distance found. Returns None if nn_distances is None and optional is True.

Return type:

array-like or None

Raises:

ValueError – If all instances/cells are found to be identical or invalid.

mellon.validation.validate_positive_float(value, param_name, optional=False)View on GitHub ¶

Validates whether a given value is a positive float, and non-NaN.

Parameters:

value (float, int, or string, or None) – The value to be validated. It should be a positive float or convertible to a positive float.
param_name (str) – The name of the parameter to be used in the error message.
optional (bool, optional) – Whether the value is optional. If optional and value is None, returns None. Default is False.

Returns:

The validated value as a positive float.

Return type:

float

Raises:

ValueError – If the value is not a positive float, not convertible to a positive float, NaN, and not None when not optional.

mellon.validation.validate_positive_int(value, param_name, optional=False)View on GitHub ¶

Validates whether a given value is a positive integer.

Parameters:

value (int or None) – The value to be validated. It should be a positive integer.
param_name (str) – The name of the parameter to be used in the error message.
optional (bool, optional) – Whether the value is optional. If optional and value is None, returns None. Default is False.

Returns:

The validated value as a positive integer, or None if the value is optional and None.

Return type:

int or None

Raises:

ValueError – If the value is not a positive integer and not None when not optional.

mellon.validation.validate_string(value, name, choices=None)View on GitHub ¶

Validates whether a given value is a string and optionally whether it is in a set of choices.

Parameters:

value (any) – The value to be validated.
name (str) – The name of the parameter to be used in the error message.
choices (list of str, optional) – A list of valid string choices. If provided, the value must be one of these choices.

Returns:

The validated value as a string.

Return type:

str

Raises:

TypeError – If the value is not of type str.
ValueError – If the value is not one of the choices (if provided).

mellon.validation.validate_time_x(x, times=None, n_features=None, cast_scalar=False)View on GitHub ¶

Validates and concatenates ‘x’ and ‘times’ if ‘times’ is provided.

If ‘times’ is provided, the function reshapes it if necessary and checks for matching number of samples in ‘x’ and ‘times’, before concatenating.

If ‘n_features’ is provided, the function checks if ‘x’ has the correct number of features.

Parameters:

x (array-like) – The training instances for which the density function will be estimated. Shape must be (n_samples, n_features).
times (array-like, optional) – An array encoding the time points associated with each cell/row in ‘x’. Shape must be either (n_samples,) or (n_samples, 1).
n_features (int, optional) – The expected number of features in ‘x’ including ‘times’ if it is provided.
cast_scalar (bool, optional) – If true and ‘times’ is a scalar, it will be cast to a 1D array with a length equal to the number of samples in ‘x’.

Returns:

The concatenated array of ‘x’ and ‘times’ (if provided), or ‘x’ if ‘times’ is not provided.

Return type:

array-like

Raises:

ValueError – If ‘times’ is not a 1D or 2D array with 1 column, or ‘x’ and ‘times’ don’t have the same number of samples, or ‘x’ does not have the expected number of features.