Skip to content

Selector Module

sensingpy.selector provides tools for selecting and compositing array subsets based on value intervals and aggregation methods.

interval_choice

interval_choice 

interval_choice(array: ndarray, size: int, intervals: Iterable, replace=True) -> np.ndarray

Generates a random sample from the given array based on the provided intervals.

Args: array (np.ndarray): array to be sampled size (int): size for each interval intervals (Iterable): intervals to be sampled from

        e.g. [(0, 1), (1, 2), (2, 3)]
replace (bool, optional): np.choice sample argument. Defaults to True.

Returns: np.ndarray: Random sample from the given array based on the provided intervals.

Source code in sensingpy/selector.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
def interval_choice(
    array: np.ndarray, size: int, intervals: Iterable, replace=True
) -> np.ndarray:
    """Generates a random sample from the given array based on the provided intervals.

    Args:
        array (np.ndarray): array to be sampled
        size (int): size for each interval
        intervals (Iterable): intervals to be sampled from

                e.g. [(0, 1), (1, 2), (2, 3)]
        replace (bool, optional): np.choice sample argument. Defaults to True.

    Returns:
        np.ndarray: Random sample from the given array based on the provided intervals.
    """

    limit_masks = _get_limit_masks(array, pairwise(intervals))
    return np.array(
        [
            np.random.choice(array[in_limits], size, replace=replace)
            for in_limits in limit_masks
        ]
    ).ravel()

sample_indices_by_interval

sample_indices_by_interval 

sample_indices_by_interval(array: ndarray, size: int, intervals: Iterable, replace=True) -> np.ndarray

Get indices of a random sample from the array based on value intervals.

Args: array (np.ndarray): array to be sampled size (int): number of samples per interval intervals (Iterable): value intervals to sample from

        e.g. [(0, 1), (1, 2), (2, 3)]
replace (bool, optional): whether to sample with replacement. Defaults to True.

Returns: np.ndarray: Indices of the random sample from the given array.

Examples: >>> # Sample 10 indices from each depth interval >>> depths = np.array([0.5, 1.5, 2.5, 3.5, 4.5]) >>> indices = sample_indices_by_interval(depths, 10, [0, 2, 4, 6])

Source code in sensingpy/selector.py 
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
def sample_indices_by_interval(
    array: np.ndarray, size: int, intervals: Iterable, replace=True
) -> np.ndarray:
    """Get indices of a random sample from the array based on value intervals.

    Args:
        array (np.ndarray): array to be sampled
        size (int): number of samples per interval
        intervals (Iterable): value intervals to sample from

                e.g. [(0, 1), (1, 2), (2, 3)]
        replace (bool, optional): whether to sample with replacement. Defaults to True.

    Returns:
        np.ndarray: Indices of the random sample from the given array.

    Examples:
        >>> # Sample 10 indices from each depth interval
        >>> depths = np.array([0.5, 1.5, 2.5, 3.5, 4.5])
        >>> indices = sample_indices_by_interval(depths, 10, [0, 2, 4, 6])
    """

    indexes = np.arange(array.size)
    limit_masks = _get_limit_masks(array, pairwise(intervals))
    return np.array(
        [
            np.random.choice(indexes[in_limits], size, replace=replace)
            for in_limits in limit_masks
        ]
    ).ravel()

arginterval_choice

arginterval_choice 

arginterval_choice(array: ndarray, size: int, intervals: Iterable, replace=True) -> np.ndarray

Generates the indexes of a random sample from the given array based on the provided intervals.

.. deprecated:: 2.1.0 Use :func:sample_indices_by_interval instead. This function will be removed in version 3.0.0.

Args: array (np.ndarray): array to be sampled size (int): size for each interval intervals (Iterable): intervals to be sampled from

        e.g. [(0, 1), (1, 2), (2, 3)]
replace (bool, optional): np.choice sample argument. Defaults to True.

Returns: np.ndarray: The indexes of a random sample from the given array based on the provided intervals.

Source code in sensingpy/selector.py 
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
def arginterval_choice(
    array: np.ndarray, size: int, intervals: Iterable, replace=True
) -> np.ndarray:
    """Generates the indexes of a random sample from the given array based on the provided intervals.

    .. deprecated:: 2.1.0
        Use :func:`sample_indices_by_interval` instead. This function will be removed in version 3.0.0.

    Args:
        array (np.ndarray): array to be sampled
        size (int): size for each interval
        intervals (Iterable): intervals to be sampled from

                e.g. [(0, 1), (1, 2), (2, 3)]
        replace (bool, optional): np.choice sample argument. Defaults to True.

    Returns:
        np.ndarray: The indexes of a random sample from the given array based on the provided intervals.
    """
    import warnings
    warnings.warn(
        "arginterval_choice is deprecated and will be removed in version 3.0.0. "
        "Use sample_indices_by_interval instead.",
        DeprecationWarning,
        stacklevel=2
    )
    return sample_indices_by_interval(array, size, intervals, replace)

composite

composite 

composite(arrays: ndarray, method: Callable | ndarray = np.nanmax) -> np.ndarray

Generates a synthetic array based on the provided method.

Args: arrays (np.ndarray): a list of arrays to be composed method (Callable | np.ndarray, optional): numpy funcion or list of indexes to compose the final array. Defaults to np.nanmax.

Returns: np.ndarray: a synthetic array based on the provided method.

Source code in sensingpy/selector.py 
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
def composite(
    arrays: np.ndarray, method: Callable | np.ndarray = np.nanmax
) -> np.ndarray:
    """Generates a synthetic array based on the provided method.

    Args:
        arrays (np.ndarray): a list of arrays to be composed
        method (Callable | np.ndarray, optional): numpy funcion or list of indexes to compose the final array. Defaults to np.nanmax.

    Returns:
        np.ndarray: a synthetic array based on the provided method.
    """

    if isinstance(method, np.ndarray):
        m, n = method.shape
        i, j = np.ogrid[:m, :n]
        return arrays[method, i, j]

    else:
        return method(arrays, axis=0)

composite_indices

composite_indices 

composite_indices(arrays: ndarray, method: Callable = np.argmax) -> np.ndarray

Get indices of optimal values across multiple arrays for compositing.

Finds which array contains the optimal value (e.g., maximum, minimum) at each position, returning an index array that can be used with the composite() function.

Args: arrays (np.ndarray): stack of arrays with shape (n_arrays, height, width) method (Callable, optional): numpy argmax/argmin function to determine optimal values. Defaults to np.argmax.

Returns: np.ndarray: 2D array of indices indicating which input array has the optimal value at each position.

Examples: >>> # Create max NDVI composite >>> ndvi_stack = np.array([img1_ndvi, img2_ndvi, img3_ndvi]) >>> best_indices = composite_indices(ndvi_stack, np.argmax) >>> max_ndvi_composite = composite(image_stack, best_indices)

Source code in sensingpy/selector.py 
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
def composite_indices(arrays: np.ndarray, method: Callable = np.argmax) -> np.ndarray:
    """Get indices of optimal values across multiple arrays for compositing.

    Finds which array contains the optimal value (e.g., maximum, minimum) at each position,
    returning an index array that can be used with the composite() function.

    Args:
        arrays (np.ndarray): stack of arrays with shape (n_arrays, height, width)
        method (Callable, optional): numpy argmax/argmin function to determine optimal values.
            Defaults to np.argmax.

    Returns:
        np.ndarray: 2D array of indices indicating which input array has the optimal value
            at each position.

    Examples:
        >>> # Create max NDVI composite
        >>> ndvi_stack = np.array([img1_ndvi, img2_ndvi, img3_ndvi])
        >>> best_indices = composite_indices(ndvi_stack, np.argmax)
        >>> max_ndvi_composite = composite(image_stack, best_indices)
    """

    nans = np.isnan(arrays).all(axis=0)
    arrays[:, nans] = np.inf
    indexes = method(arrays, axis=0)
    arrays[:, nans] = np.nan
    return indexes

argcomposite

argcomposite 

argcomposite(arrays: ndarray, method: Callable = np.argmax) -> np.ndarray

Generates the indexes of a synthetic array based on the provided method.

.. deprecated:: 2.1.0 Use :func:composite_indices instead. This function will be removed in version 3.0.0.

Args: arrays (np.ndarray): the array to be composed method (Callable, optional): a numpy method such as argmax. Defaults to np.argmax.

Returns: np.ndarray: The indexes of a synthetic array

Source code in sensingpy/selector.py 
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
def argcomposite(arrays: np.ndarray, method: Callable = np.argmax) -> np.ndarray:
    """Generates the indexes of a synthetic array based on the provided method.

    .. deprecated:: 2.1.0
        Use :func:`composite_indices` instead. This function will be removed in version 3.0.0.

    Args:
        arrays (np.ndarray): the array to be composed
        method (Callable, optional): a numpy method such as argmax. Defaults to np.argmax.

    Returns:
        np.ndarray: The indexes of a synthetic array
    """
    import warnings
    warnings.warn(
        "argcomposite is deprecated and will be removed in version 3.0.0. "
        "Use composite_indices instead.",
        DeprecationWarning,
        stacklevel=2
    )
    return composite_indices(arrays, method)