Skip to content

Utils

pynapple.core.utils

Utility functions

is_array_like 

is_array_like(obj)

Check if an object is array-like.

This function determines if an object has array-like properties. An object is considered array-like if it has attributes typically associated with arrays (such as .shape, .dtype, and .ndim), supports indexing, and is iterable.

Parameters:

Name Type Description Default
obj object

The object to check for array-like properties.

 required

Returns:

Type Description
bool

True if the object is array-like, False otherwise.
Notes

This function uses a combination of checks for attributes (shape, dtype, ndim), indexability, and iterability to determine if the given object behaves like an array. It is designed to be flexible and work with various types of array-like objects, including but not limited to NumPy arrays and JAX arrays. However, it may not be full proof for all possible array-like types or objects that mimic these properties without being suitable for numerical operations.

Source code in pynapple/core/utils.py 
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
def is_array_like(obj):
    """
    Check if an object is array-like.

    This function determines if an object has array-like properties.
    An object is considered array-like if it has attributes typically associated with arrays
    (such as `.shape`, `.dtype`, and `.ndim`), supports indexing, and is iterable.

    Parameters
    ----------
    obj : object
        The object to check for array-like properties.

    Returns
    -------
    bool
        True if the object is array-like, False otherwise.

    Notes
    -----
    This function uses a combination of checks for attributes (`shape`, `dtype`, `ndim`),
    indexability, and iterability to determine if the given object behaves like an array.
    It is designed to be flexible and work with various types of array-like objects, including
    but not limited to NumPy arrays and JAX arrays. However, it may not be full proof for all
    possible array-like types or objects that mimic these properties without being suitable for
    numerical operations.

    """
    # Check for array-like attributes
    has_shape = hasattr(obj, "shape")
    has_dtype = hasattr(obj, "dtype")
    has_ndim = hasattr(obj, "ndim")

    # Check for indexability (try to access the first element)
    try:
        obj[0]
        is_indexable = True
    except (TypeError, IndexError):
        is_indexable = False

    # Check for iterable property
    try:
        iter(obj)
        is_iterable = True
    except TypeError:
        is_iterable = False

    # not_tsd_type = not isinstance(obj, _AbstractTsd)

    return (
        has_shape
        and has_dtype
        and has_ndim
        and is_indexable
        and is_iterable
        # and not_tsd_type
    )

convert_to_numpy 

convert_to_numpy(array, array_name)

Convert an input array-like object to a NumPy array.

This function attempts to convert an input object to a NumPy array using np.asarray. If the input is not already a NumPy ndarray, it issues a warning indicating that a conversion has taken place and shows the original type of the input. This function is useful for ensuring compatibility with Numba operations in cases where the input might come from various array-like sources (for instance, jax.numpy.Array).

Parameters:

Name Type Description Default
array array_like

The input object to convert. This can be any object that np.asarray is capable of converting to a NumPy array, such as lists, tuples, and other array-like objects, including those from libraries like JAX or TensorFlow that adhere to the array interface.

 required
array_name str

The name of the variable that we are converting, printed in the warning message.

 required

Returns:

Type Description
ndarray

A NumPy ndarray representation of the input values. If values is already a NumPy ndarray, it is returned unchanged. Otherwise, a new NumPy ndarray is created and returned.
Warnings

A warning is issued if the input values is not already a NumPy ndarray, indicating that a conversion has taken place and showing the original type of the input.

Source code in pynapple/core/utils.py 
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
def convert_to_numpy(array, array_name):
    """
    Convert an input array-like object to a NumPy array.

    This function attempts to convert an input object to a NumPy array using `np.asarray`.
    If the input is not already a NumPy ndarray, it issues a warning indicating that a conversion
    has taken place and shows the original type of the input. This function is useful for
    ensuring compatibility with Numba operations in cases where the input might come from
    various array-like sources (for instance, jax.numpy.Array).

    Parameters
    ----------
    array : array_like
        The input object to convert. This can be any object that `np.asarray` is capable of
        converting to a NumPy array, such as lists, tuples, and other array-like objects,
        including those from libraries like JAX or TensorFlow that adhere to the array interface.
    array_name : str
        The name of the variable that we are converting, printed in the warning message.

    Returns
    -------
    ndarray
        A NumPy ndarray representation of the input `values`. If `values` is already a NumPy
        ndarray, it is returned unchanged. Otherwise, a new NumPy ndarray is created and returned.

    Warnings
    --------
    A warning is issued if the input `values` is not already a NumPy ndarray, indicating
    that a conversion has taken place and showing the original type of the input.

    """
    if (
        not isinstance(array, np.ndarray)
        and not nap_config.suppress_conversion_warnings
    ):
        original_type = type(array).__name__
        warnings.warn(
            f"Converting '{array_name}' to numpy.array. The provided array was of type '{original_type}'.",
            UserWarning,
        )
    return np.asarray(array)