Core Array Operations

def unique(
    labels: ArrayLike,
    return_index: bool = False,
    return_inverse: bool = False,
    return_counts: bool = False,
    axis: Union[int, None] = None
) -> Union[NDArray, tuple]:
    """
    Compute the sorted set of unique labels in the input array.
    
    Args:
        labels: The input array containing labels
        return_index: If True, return index of first occurrence of each label
        return_inverse: If True, return indices to reconstruct original array
        return_counts: If True, return unique label frequency
        axis: Axis along which to compute unique values
    
    Returns:
        NDArray or tuple of NDArrays depending on flags set
    """

import fastremap
import numpy as np

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

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

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

# With all return options
unique_vals, indices, inverse, counts = fastremap.unique(
    labels, return_index=True, return_inverse=True, return_counts=True
)

def remap(
    arr: ArrayLike,
    table: Union[dict[int, int], dict[float, float]],
    preserve_missing_labels: bool = False,
    in_place: bool = False
) -> NDArray:
    """
    Remap an input numpy array according to a dictionary mapping.
    
    Args:
        arr: Input N-dimensional numpy array
        table: Dictionary mapping old to new values
        preserve_missing_labels: Whether to leave unmapped values alone or throw KeyError
        in_place: Modify input array to reduce memory consumption
    
    Returns:
        The remapped array
    """

import fastremap
import numpy as np

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

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

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

def renumber(
    arr: NDArray,
    start: Union[int, float] = 1,
    preserve_zero: bool = True,
    in_place: bool = False
) -> tuple[NDArray, dict]:
    """
    Renumber an array starting from a specified value.
    
    Args:
        arr: Input numpy array
        start: Start renumbering from this value (default: 1)
        preserve_zero: Don't renumber zero (default: True)
        in_place: Perform renumbering in-place (default: False)
    
    Returns:
        Tuple of renumbered array and remapping dictionary
    """

import fastremap
import numpy as np

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

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

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

def refit(
    arr: NDArray,
    value: Union[int, float, None] = None,
    increase_only: bool = False,
    exotics: bool = False
) -> NDArray:
    """
    Resize array to smallest dtype of same kind that will fit the values.
    
    Args:
        arr: Input numpy array
        value: Value to fit array to (default: None uses array extrema)
        increase_only: Only resize if current dtype can't contain value
        exotics: Allow exotic dtypes like half precision floats
    
    Returns:
        The refitted array
    """

import fastremap
import numpy as np

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

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

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

ArrayLike = Union[np.ndarray, list, tuple]
NDArray = np.ndarray