magni.utils.validation._numeric module

Module providing the validate_numeric function.

Routine listings

validate_numeric(name, type, range_=’[-inf;inf]’, shape=(), precision=None,
ignore_none=False, var=None) Validate numeric objects.
magni.utils.validation._numeric.validate_numeric(name, type_, range_='[-inf;inf]', shape=(), precision=None, ignore_none=False, var=None)[source]

Validate numeric objects.

The present function is meant to valdiate the type or class of an object. Furthermore, if the object may only take on a connected range of values, the object can be validated against this range. Also, the shape of the object can be validated. Finally, the precision used to represent the object can be validated.

If the present function is called with name set to None, an iterable with the value ‘numeric’ followed by the remaining arguments passed in the call is returned. This is useful in combination with the validation function magni.utils.validation.validate_levels.

Parameters:
  • name (None) – The name of the variable to be validated.
  • type_ (None) – One or more references to groups of types.
  • range_ (None) – The range of accepted values. (the default is ‘[-inf;inf]’, which implies that all values are accepted)
  • shape (list or tuple) – The accepted shape. (the default is (), which implies that only scalar values are accepted)
  • precision (None) – One or more precisions.
  • ignore_none (bool) – A flag indicating if the variable is allowed to be none. (the default is False)
  • var (None) – The value of the variable to be validated.

See also

magni.utils.validation.validate_generic()
Validate non-numeric objects.
magni.utils.validation.validate_levels()
Validate contained objects.

Notes

name must refer to a variable in the parent scope of the function or method decorated by magni.utils.validation.decorate_validation which is closest to the top of the call stack. If name is a string then there must be a variable of that name in that scope. If name is a set-like object then there must be a variable having the first value in that set-like object as name. The remaining values are used as keys/indices on the variable to obtain the variable to be validated. For example, the name (‘name’, 0, ‘key’) refers to the variable “name[0][‘key’]”.

type_ is either a single value treated as a list with one value or a set-like object containing at least one value. Each value refers to a number of data types depending if the string value is ‘boolean’, ‘integer’, ‘floating’, or ‘complex’.

  • ‘boolean’ tests if the variable is a bool or has the data type numpy.bool8.
  • ‘integer’ tests if the variable is an int or has the data type numpy.int8, numpy.int16, numpy.int32, or numpy.int64.
  • ‘floating’ tests if the variable is a float or has the data type numpy.float16, numpy.float32, numpy.float64, or numpy.float128.
  • ‘complex’ tests if the variable is a complex or has the data type numpy.complex32, numpy.complex64, or numpy.complex128.

Because bool is a subclass of int, a bool will pass validation as an ‘integer’. This, however, is not the case for numpy.bool8.

range_ is either a list with two strings or a single string. In the latter case, the default value of the argument is used as the second string. The first value represents the accepted range of real values whereas the second value represents the accepted range of imaginary values. Each string consists of the following parts:

  • One of the following delimiters: ‘[‘, ‘(‘, ‘]’.
  • A numeric value (or ‘-inf’).
  • A semi-colon.
  • A numeric value (or ‘inf’).
  • One of the following delimiters: ‘]’, ‘)’, ‘[‘.

shape is either None meaning that any shape is accepted or a list of integers. In the latter case, the integer -1 may be used to indicate that the given axis may have any length.

precision is either an integer treated as a list with one value or a list or tuple containing at least one integer. Each value refers to an accepted number of bits used to store each value of the variable.

var can be used to pass the value of the variable to be validated. This is useful either when the variable cannot be looked up by name (for example, if the variable is a property of the argument of a function) or to remove the overhead of looking up the value.

Examples

Every public function and method of the present package (with the exception of the functions of this subpackage itself) validates every argument and keyword argument using the functionality of this subpackage. Thus, for examples of how to use the present function, browse through the code.

magni.utils.validation._numeric._check_precision(name, dtype, types_, precision)[source]

Check the precision of a variable.

Parameters:
  • name (None) – The name of the variable to be validated.
  • dtype (type) – The data type of the variable to be validated.
  • types_ (set-like) – The list of accepted types.
  • precision (None) – The accepted precision(s).
magni.utils.validation._numeric._check_range(name, bounds, range_)[source]

Check the range of a variable.

Parameters:
  • name (None) – The name of the variable to be validated.
  • bounds (list or tuple) – The bounds of the variable to be validated.
  • range_ (None) – The accepted range(s).
magni.utils.validation._numeric._check_shape(name, dshape, shape)[source]

Check the shape of a variable.

Parameters:
  • name (None) – The name of the variable to be validated.
  • dshape (list or tuple) – The shape of the variable to be validated.
  • shape (list or tuple) – The accepted shape.
magni.utils.validation._numeric._check_type(name, dtype, types_)[source]

Check the type of a variable.

Parameters:
  • name (None) – The name of the variable to be validated.
  • dtype (type) – The data type of the variable to be validated.
  • types_ (set-like) – The accepted types.
magni.utils.validation._numeric._examine_var(name, var)[source]

Examine a variable.

The present function examines the data type, the bounds, and the shape of a variable. The variable can be of a built-in type, a numpy type, or a subclass of the magni.utils.validation.types.MatrixBase class.

Parameters:
  • name (None) – The name of the variable to be validated.
  • var (None) – The value of the variable to be examined.
Returns:

  • dtype (type) – The data type of the examined variable.
  • bounds (tuple) – The bounds of the examined variable.
  • dshape (tuple) – The shape of the examined variable.