Ndindex

Warnings

• gotcha ndindex objects assume that indexing will not raise an `IndexError`. Operations like `reduce()` and transformations do not validate against array bounds; they assume the index is valid for *some* array. Users must handle `IndexError` when applying `ndindex.raw` to an actual NumPy array. [1, 4, 6, 8]
  Fix: Always use `try-except IndexError` blocks when applying `idx.raw` to a NumPy array if out-of-bounds indexing is a possibility. Perform explicit bounds checking if needed before constructing the `ndindex` object if strict validation is required.
• gotcha By default, `ndindex` class constructors (e.g., `Slice(None, 10)`) only perform basic type checking and do not canonicalize the index. This means `Slice(None, 10)` is not strictly equal to `Slice(0, 10, 1)` by default. [1, 4, 8]
  Fix: To canonicalize an index or reduce it to its simplest equivalent form, you must explicitly call the `.reduce()` method on the `ndindex` object (e.g., `Slice(None, 10).reduce()`). If comparing two indices for equivalence over a specific array shape, use `idx1.reduce(shape) == idx2.reduce(shape)` rather than `idx1 == idx2`. [1, 4]
• gotcha Direct `==` comparison between `ndindex` objects performs exact equality checking, which might not reflect if two indices actually refer to the same elements in an array. For instance, `Slice(0, 10)` and `Slice(None, 10)` are not equal with `==`. [1]
  Fix: To check if two `ndindex` objects are equivalent in terms of the elements they would select from an array, first call their `.reduce()` method, optionally with an array `shape` argument if the context is known. Then compare the reduced objects: `idx1.reduce(shape) == idx2.reduce(shape)`. [1]

Install

• pip install ndindex Install stable version

Imports

• ndindex

  from ndindex import ndindex

  The primary API entry point is the `ndindex()` function, usually imported directly to convert Python index objects to ndindex objects. Direct `import ndindex` requires prefixing all calls, which is less common for this library's typical usage.
• Slice

  from ndindex import Slice

  Classes like `Slice`, `Integer`, `Tuple` are typically imported directly for convenience, or accessed via `ndindex.Slice` if `ndindex` is imported as a module.

Quickstart

This quickstart demonstrates creating `ndindex` objects from basic Python indices, canonicalizing slices (both generally and for a specific array shape), and converting an `ndindex` object back into a raw Python index suitable for use with NumPy arrays. It highlights the `reduce()` method for canonicalization and `raw` attribute for NumPy compatibility.

import numpy as np
from ndindex import ndindex, Slice, Tuple

# Create an ndindex object from a Python slice
idx_slice = ndindex(slice(1, 10, 2))
print(f"Ndindex from slice: {idx_slice}")

# Canonicalize a slice (reduce to simplest form)
canonical_slice = Slice(None, 10).reduce()
print(f"Canonical slice: {canonical_slice}")

# Canonicalize for a specific array shape
shaped_slice = Slice(-5, 10, 2).reduce(12)
print(f"Slice reduced for shape 12: {shaped_slice}")

# Manipulate a tuple index
tuple_idx = Tuple(0, slice(0, 5), None, 1)
print(f"Tuple index: {tuple_idx}")

# Get the raw Python index to use with NumPy
np_array = np.arange(20).reshape(2, 10)
raw_index = tuple_idx.raw
print(f"Raw Python index: {raw_index}")

# Use the raw index with a NumPy array
try:
    indexed_array = np.arange(100).reshape(10, 10)[raw_index] # Example with a 2D array
    print(f"Indexed array shape: {indexed_array.shape}")
except IndexError as e:
    print(f"Indexing with {raw_index} failed due to: {e}")