check_shape

pybear.base.check_shape(X, min_features=1, max_features=None, min_samples=1, sample_check=None, allowed_dimensionality=(1, 2))

Check the shape of a data-bearing object against user-defined criteria.

X must have a ‘shape’ method.

The number of samples in X must be greater than or equal to min_samples.

If sample_check is not None (must be an integer greater than or equal to min_samples), the number of samples in X must equal sample_check.

The number of features in X must be greater than or equal to min_features.

If max_features is not None (must be an integer greater than or equal to min_features), then number of features in X cannot exceed max_features.

The dimensionality of X must be one of the allowed values in allowed_dimensionality.

Parameters:

XXContainer of shape (n_samples, n_features) or (n_samples,)

The data-bearing object for which to get and validate the shape. Must have a ‘shape’ attribute.

min_featuresint

The minimum number of features required in X; must be greater than or equal to zero.

max_featuresint | None

The maximum number of features allowed in X; if not None, must be greater than or equal to min_features. If None, then there is no restriction on the maximum number of features in X.

min_samplesint

The minimum number of samples required in X; must be greater than or equal to zero. Ignored if sample_check is not None.

sample_checkint | None

The exact number of samples allowed in X. If not None, must be a non-negative integer. Use this to check, for example, that the number of samples in y equals the number of samples in X. If None, this check is not performed.

allowed_dimensionalitySequence[int]

The allowed dimensionalities of X. All entries must be greater than zero and less than or equal to two.

Returns:

shapetuple[int, …]

The shape of X.

Raises:

ValueError:

The number of dimensions of X is not allowed.

The number of samples in X does not match sample_check.

The number of samples in X is below min_samples.

The number of features in X is below min_features.

The number of features in X is above max_features.

Notes

Type Aliases

NumpyTypes:

numpy.ndarray

PandasTypes:

pandas.Series | pandas.DataFrame

PolarsTypes:

polars.Series | polars.DataFrame

ScipySparseTypes:

ss.csc_matrix | ss.csc_array | ss.csr_matrix | ss.csr_array | ss.coo_matrix | ss.coo_array | ss.dia_matrix | ss.dia_array | ss.lil_matrix | ss.lil_array | ss.dok_matrix | ss.dok_array | ss.bsr_matrix | ss.bsr_array

XContainer:

NumpyTypes | PandasTypes | PolarsTypes | ScipySparseTypes

Examples

>>> from pybear.base import check_shape
>>> import numpy as np
>>> X = np.random.randint(0, 10, (5, 3))
>>> kwargs = {'min_features': 1, 'max_features': None, 'min_samples': 1,
...     'sample_check': None, 'allowed_dimensionality': (2, )}
>>>
>>> # Demonstrate a valid container passes and returns the shape
>>> print(check_shape(X, **kwargs))
(5, 3)
>>>
>>> # Demonstrate an invalid container raises ValueError
>>> X = np.random.randint(0, 10, (5,))
>>> try:
...     check_shape(X, **kwargs)
... except Exception as e:
...     print(repr(e))
ValueError('The dimensionality of the passed object must be in (2,). Got 1.')