0
# Core Array Operations
1

2
Essential array manipulation functions that form the foundation of fastremap's high-performance array processing capabilities. These functions provide faster alternatives to common numpy operations and support automatic data type optimization.
3

4
## Capabilities
5

6
### Unique Value Detection
7

8
Compute the sorted set of unique labels in arrays. Significantly faster than `np.unique` for large arrays, with flexible return options.
9

10
```python { .api }
11
def unique(
12
    labels: ArrayLike,
13
    return_index: bool = False,
14
    return_inverse: bool = False,
15
    return_counts: bool = False,
16
    axis: Union[int, None] = None
17
) -> Union[NDArray, tuple]:
18
    """
19
    Compute the sorted set of unique labels in the input array.
20
    
21
    Args:
22
        labels: The input array containing labels
23
        return_index: If True, return index of first occurrence of each label
24
        return_inverse: If True, return indices to reconstruct original array
25
        return_counts: If True, return unique label frequency
26
        axis: Axis along which to compute unique values
27
    
28
    Returns:
29
        NDArray or tuple of NDArrays depending on flags set
30
    """
31
```
32

33
**Usage Example:**
34

35
```python
36
import fastremap
37
import numpy as np
38

39
labels = np.array([1, 3, 1, 5, 3, 5, 5])
40

41
# Basic unique values
42
unique_vals = fastremap.unique(labels)
43
# Result: [1, 3, 5]
44

45
# With counts
46
unique_vals, counts = fastremap.unique(labels, return_counts=True)
47
# Result: ([1, 3, 5], [2, 2, 3])
48

49
# With all return options
50
unique_vals, indices, inverse, counts = fastremap.unique(
51
    labels, return_index=True, return_inverse=True, return_counts=True
52
)
53
```
54

55
### Value Remapping
56

57
Remap array values according to a dictionary mapping. Essential for relabeling operations in image processing and data analysis.
58

59
```python { .api }
60
def remap(
61
    arr: ArrayLike,
62
    table: Union[dict[int, int], dict[float, float]],
63
    preserve_missing_labels: bool = False,
64
    in_place: bool = False
65
) -> NDArray:
66
    """
67
    Remap an input numpy array according to a dictionary mapping.
68
    
69
    Args:
70
        arr: Input N-dimensional numpy array
71
        table: Dictionary mapping old to new values
72
        preserve_missing_labels: Whether to leave unmapped values alone or throw KeyError
73
        in_place: Modify input array to reduce memory consumption
74
    
75
    Returns:
76
        The remapped array
77
    """
78
```
79

80
**Usage Example:**
81

82
```python
83
import fastremap
84
import numpy as np
85

86
arr = np.array([1, 2, 3, 4, 5])
87
mapping = {1: 100, 3: 300, 5: 500}
88

89
# Remap with missing label preservation
90
remapped = fastremap.remap(arr, mapping, preserve_missing_labels=True)
91
# Result: [100, 2, 300, 4, 500]
92

93
# In-place remapping to save memory
94
fastremap.remap(arr, mapping, preserve_missing_labels=True, in_place=True)
95
```
96

97
### Array Renumbering
98

99
Renumber arrays starting from a specified value, automatically optimizing data type to fit the new value range. Reduces memory usage significantly for sparse label arrays.
100

101
```python { .api }
102
def renumber(
103
    arr: NDArray,
104
    start: Union[int, float] = 1,
105
    preserve_zero: bool = True,
106
    in_place: bool = False
107
) -> tuple[NDArray, dict]:
108
    """
109
    Renumber an array starting from a specified value.
110
    
111
    Args:
112
        arr: Input numpy array
113
        start: Start renumbering from this value (default: 1)
114
        preserve_zero: Don't renumber zero (default: True)
115
        in_place: Perform renumbering in-place (default: False)
116
    
117
    Returns:
118
        Tuple of renumbered array and remapping dictionary
119
    """
120
```
121

122
**Usage Example:**
123

124
```python
125
import fastremap
126
import numpy as np
127

128
# Large sparse labels
129
arr = np.array([283732875, 439238823, 283732875, 182812404, 0], dtype=np.int64)
130

131
# Renumber preserving zero
132
renumbered, mapping = fastremap.renumber(arr, preserve_zero=True)
133
# Result: renumbered = [1, 2, 1, 3, 0] (uint8), mapping = {0: 0, 283732875: 1, ...}
134

135
# Renumber without preserving zero
136
renumbered, mapping = fastremap.renumber(arr, preserve_zero=False)
137
# Result: renumbered = [1, 2, 1, 3, 4] (uint8), mapping = {0: 4, 283732875: 1, ...}
138
```
139

140
### Data Type Optimization
141

142
Resize arrays to the smallest data type that can contain the values, reducing memory usage without data loss.
143

144
```python { .api }
145
def refit(
146
    arr: NDArray,
147
    value: Union[int, float, None] = None,
148
    increase_only: bool = False,
149
    exotics: bool = False
150
) -> NDArray:
151
    """
152
    Resize array to smallest dtype of same kind that will fit the values.
153
    
154
    Args:
155
        arr: Input numpy array
156
        value: Value to fit array to (default: None uses array extrema)
157
        increase_only: Only resize if current dtype can't contain value
158
        exotics: Allow exotic dtypes like half precision floats
159
    
160
    Returns:
161
        The refitted array
162
    """
163
```
164

165
**Usage Example:**
166

167
```python
168
import fastremap
169
import numpy as np
170

171
# Array with small values in large dtype
172
arr = np.array([1, 2, 3, 255], dtype=np.int64)
173

174
# Refit to smallest suitable dtype
175
refitted = fastremap.refit(arr)
176
# Result: uint8 array, significant memory savings
177

178
# Refit to accommodate a specific value
179
arr = np.array([1, 2, 3], dtype=np.uint8)
180
refitted = fastremap.refit(arr, value=500)
181
# Result: uint16 array to accommodate 500
182
```
183

184
## Types
185

186
```python { .api }
187
ArrayLike = Union[np.ndarray, list, tuple]
188
NDArray = np.ndarray
189
```