vcti-nputils 1.0.0

NumPy structured array utilities — joining, flattening, field views, enum mapping, and position arrays

NumPy Utils

NumPy structured array utilities — joining, flattening, field views, enum mapping, and position arrays.

Installation

pip install vcti-nputils>=1.0.0

In pyproject.toml dependencies

dependencies = [
    "vcti-nputils>=1.0.0",
]

---

Quick Start

import numpy as np
from vcti.nputils import (
    join_struct_arrays,
    flatten_record_dtype,
    fields_view,
    drop_fields,
    rename_fields,
    name_array,
    position_array,
    as_ndarray,
)

# Join structured arrays horizontally
dt1 = np.dtype([('id', 'i4'), ('value', 'f8')])
dt2 = np.dtype([('name', 'U10')])
arr1 = np.array([(1, 1.5), (2, 2.5)], dtype=dt1)
arr2 = np.array([('Alice',), ('Bob',)], dtype=dt2)
joined = join_struct_arrays([arr1, arr2])
# dtype: [('id', 'i4'), ('value', 'f8'), ('name', 'U10')]

# Create a zero-copy view with selected fields
view = fields_view(joined, ['id', 'name'])

# Drop fields from a structured array (zero-copy)
clean = drop_fields(joined, ['value'])
# dtype: [('id', 'i4'), ('name', 'U10')]

# Rename fields in a dtype
new_dt = rename_fields(dt1, {'id': 'node_id', 'value': 'temperature'})
# dtype: [('node_id', 'i4'), ('temperature', 'f8')]

# Flatten array fields into individual columns
dt = np.dtype([('id', 'i4'), ('coords', 'f8', (3,))])
flat_dt, cols = flatten_record_dtype(dt)
# cols: ['id', 'coord_0', 'coord_1', 'coord_2']

# Map numeric enum values to names
enum_dict = {1: 'ACTIVE', 2: 'INACTIVE', 3: 'PENDING'}
names = name_array(np.array([1, 2, 1, 3]), enum_dict)

# Convert counts to cumulative offsets
offsets = position_array(np.array([3, 2, 4, 1]))
# array([0, 3, 5, 9, 10])

# Safely coerce inputs to ndarray
arr = as_ndarray([1, 2, 3], dtype=np.float64)
empty = as_ndarray(None)  # array([], dtype=float64)

---

Functions

Function	Purpose
join_struct_arrays(arrays)	Join structured arrays horizontally by combining fields
fields_view(sa, fields)	Zero-copy view with selected fields only
drop_fields(sa, exclude)	Zero-copy view with specified fields excluded
rename_fields(dt, mapping)	Return a new dtype with fields renamed
flatten_record_dtype(dt)	Expand array fields into individual scalar fields
name_array(nparray, enum_dict)	Map numeric values to string names
position_array(counts, dtype)	Convert count array to cumulative offset array
as_ndarray(value, dtype)	Coerce None, list, or ndarray to ndarray

---

Dependencies

• numpy (>=1.24)