0
# Advanced Remapping
1

2
Specialized remapping functions using arrays instead of dictionaries, and component mapping for hierarchical label relationships. These functions provide high-performance alternatives for specific remapping scenarios and connectomics workflows.
3

4
## Capabilities
5

6
### Array-Based Remapping
7

8
Remap array using values array where the index corresponds to the label, providing faster remapping for dense label ranges.
9

10
```python { .api }
11
def remap_from_array(
12
    arr: NDArray[np.uint],
13
    vals: NDArray[np.uint],
14
    in_place: bool = True
15
) -> NDArray:
16
    """
17
    Remap array using values array where index corresponds to label.
18
    
19
    Args:
20
        arr: Input N-dimensional numpy array
21
        vals: Array of values to remap to
22
        in_place: Modify input array to reduce memory consumption
23
    
24
    Returns:
25
        The remapped array
26
    """
27
```
28

29
**Usage Example:**
30

31
```python
32
import fastremap
33
import numpy as np
34

35
# Original array with labels 0-4
36
arr = np.array([0, 1, 2, 3, 4, 1, 2])
37

38
# Remapping array: index=old_label, value=new_label
39
vals = np.array([100, 200, 300, 400, 500])  # 0->100, 1->200, etc.
40

41
# Remap using array
42
remapped = fastremap.remap_from_array(arr, vals)
43
# Result: [100, 200, 300, 400, 500, 200, 300]
44

45
# In-place operation (default)
46
fastremap.remap_from_array(arr, vals, in_place=True)
47
```
48

49
### Key-Value Array Remapping
50

51
Remap array using separate keys and values arrays, providing flexibility for sparse remapping patterns.
52

53
```python { .api }
54
def remap_from_array_kv(
55
    arr: NDArray[np.integer],
56
    keys: NDArray[np.integer],
57
    vals: NDArray[np.integer],
58
    preserve_missing_labels: bool = True,
59
    in_place: bool = True
60
) -> NDArray:
61
    """
62
    Remap array using separate keys and values arrays.
63
    
64
    Args:
65
        arr: Input N-dimensional numpy array
66
        keys: Array of keys to remap from
67
        vals: Array of values to remap to
68
        preserve_missing_labels: Whether to leave unmapped values alone or throw KeyError
69
        in_place: Modify input array to reduce memory consumption
70
    
71
    Returns:
72
        The remapped array
73
    """
74
```
75

76
**Usage Example:**
77

78
```python
79
import fastremap
80
import numpy as np
81

82
# Original array
83
arr = np.array([10, 20, 30, 40, 50, 20, 30])
84

85
# Separate key and value arrays
86
keys = np.array([10, 30, 50])      # Labels to remap
87
vals = np.array([100, 300, 500])   # New values
88

89
# Remap using key-value arrays
90
remapped = fastremap.remap_from_array_kv(arr, keys, vals, preserve_missing_labels=True)
91
# Result: [100, 20, 300, 40, 500, 20, 300]
92
# Labels 20 and 40 are preserved (not in keys array)
93

94
# Strict remapping (will error on missing labels)
95
# remapped = fastremap.remap_from_array_kv(arr, keys, vals, preserve_missing_labels=False)
96
```
97

98
### Component to Parent Mapping
99

100
Generate mapping from connected components to their parent labels, useful for hierarchical segmentation analysis.
101

102
```python { .api }
103
def component_map(
104
    component_labels: ArrayLike,
105
    parent_labels: ArrayLike
106
) -> Union[dict[int, int], dict[float, float]]:
107
    """
108
    Generate mapping from connected components to their parent labels.
109
    
110
    Args:
111
        component_labels: Array containing component labels
112
        parent_labels: Array containing parent labels
113
    
114
    Returns:
115
        Component to parent mapping dictionary
116
    """
117
```
118

119
**Usage Example:**
120

121
```python
122
import fastremap
123
import numpy as np
124

125
# Component labels (fine-grained segmentation)
126
components = np.array([1, 2, 3, 4])
127

128
# Parent labels (coarse-grained grouping)
129
parents = np.array([5, 5, 6, 7])
130

131
# Generate component-to-parent mapping
132
mapping = fastremap.component_map(components, parents)
133
# Result: {1: 5, 2: 5, 3: 6, 4: 7}
134

135
# Use case: mapping fine segmentation to cell types
136
cell_segments = np.array([101, 102, 103, 201, 202])
137
cell_types = np.array([1, 1, 1, 2, 2])  # Type 1 and Type 2 cells
138
type_mapping = fastremap.component_map(cell_segments, cell_types)
139
# Result: {101: 1, 102: 1, 103: 1, 201: 2, 202: 2}
140
```
141

142
### Inverse Component Mapping
143

144
Generate mapping from parent labels to their constituent connected components, enabling hierarchical analysis from coarse to fine levels.
145

146
```python { .api }
147
def inverse_component_map(
148
    parent_labels: ArrayLike,
149
    component_labels: ArrayLike
150
) -> Union[dict[int, list], dict[float, list]]:
151
    """
152
    Generate mapping from parent labels to connected components.
153
    
154
    Args:
155
        parent_labels: Array containing parent labels
156
        component_labels: Array containing component labels
157
    
158
    Returns:
159
        Parent to components mapping dictionary
160
    """
161
```
162

163
**Usage Example:**
164

165
```python
166
import fastremap
167
import numpy as np
168

169
# Parent labels (grouped regions)
170
parents = np.array([1, 2, 1, 3])
171

172
# Component labels (individual segments)
173
components = np.array([4, 4, 5, 6])
174

175
# Generate parent-to-components mapping
176
mapping = fastremap.inverse_component_map(parents, components)
177
# Result: {1: [4, 5], 2: [4], 3: [6]}
178

179
# Use case: finding all cell segments within tissue regions
180
tissue_regions = np.array([1, 1, 2, 2, 2])
181
cell_ids = np.array([101, 102, 201, 202, 203])
182
region_to_cells = fastremap.inverse_component_map(tissue_regions, cell_ids)
183
# Result: {1: [101, 102], 2: [201, 202, 203]}
184
```
185

186
## Use Case Examples
187

188
### Connectomics Workflow
189

190
```python
191
import fastremap
192
import numpy as np
193

194
# Common connectomics pipeline
195
# 1. Start with oversegmented image
196
overseg = np.array([1, 1, 2, 2, 3, 3, 4, 4])
197

198
# 2. Create agglomeration mapping (components to neurons)
199
neuron_mapping = {1: 100, 2: 100, 3: 200, 4: 300}  # Merge 1,2 into neuron 100
200

201
# 3. Apply remapping
202
neurons = fastremap.remap(overseg, neuron_mapping)
203
# Result: [100, 100, 100, 100, 200, 200, 300, 300]
204

205
# 4. Generate component map for analysis
206
comp_map = fastremap.component_map([1, 2, 3, 4], [100, 100, 200, 300])
207
# Result: {1: 100, 2: 100, 3: 200, 4: 300}
208
```
209

210
### Dense Label Remapping Performance
211

212
```python
213
import fastremap
214
import numpy as np
215

216
# For dense, sequential labels, array-based remapping is faster
217
labels = np.random.randint(0, 1000, size=(1000, 1000))
218
remap_array = np.arange(1000) * 2  # Double each label
219

220
# Fast array-based remapping
221
remapped = fastremap.remap_from_array(labels, remap_array)
222

223
# Compare to dictionary-based approach (slower for dense labels)
224
# remap_dict = {i: i*2 for i in range(1000)}
225
# remapped = fastremap.remap(labels, remap_dict)  # slower
226
```
227

228
## Types
229

230
```python { .api }
231
ArrayLike = Union[np.ndarray, list, tuple]
232
NDArray = np.ndarray
233
```