Awkward 0.x Array

Common errors

• IndexError: index X is out of bounds for jagged min size 0

  cause Attempting to access an element in a jagged array where one or more inner lists at that position are shorter than the requested index.
  fix Use boolean masking or check `array.counts` to ensure inner lists have sufficient length before indexing, or use `array.flatten()` to remove jaggedness if appropriate. Example: `array[array.counts > 1, 1]`.

• AttributeError: 'JaggedArray' object has no attribute 'max'

  cause Applying an aggregation function (like `max()`, `min()`, `sum()`) directly to an Awkward array that is empty, or attempting to use a method that doesn't exist on a particular Awkward type.
  fix Always check if the array has elements before calling aggregation functions (e.g., `if array.size > 0: array.max()`). Ensure the method is applicable to the specific Awkward Array class.

• ValueError: operands could not be broadcast together with shapes (...) (...)

  cause Broadcasting rules for Awkward Arrays, especially for jagged dimensions, can differ from NumPy's standard broadcasting in some edge cases.
  fix Carefully review the shapes and structure of arrays involved in the operation. Awkward's broadcasting for jagged arrays tends to be 'left-broadcasting.' Reshape arrays or perform operations in a way that respects the jagged structure.

• RuntimeWarning: numpy.ndarray size changed, may indicate binary incompatibility. Expected X from C header, got Y from PyObject

  cause This warning (or a similar one about `np.str` or `np.bool` deprecation) often arises from using an older version of `awkward0` with a newer version of NumPy, where NumPy's internal API or type aliases have changed.
  fix Update `awkward0` to the latest 0.x version (0.15.5 fixed some `np.str` warnings). If the issue persists, ensure that both `awkward0` and `numpy` are installed from compatible sources and versions.

• ImportError: cannot import name 'xyz' from 'awkward'

  cause Attempting to import a symbol (e.g., `Array`, `fromiter`) from `awkward` when `pip install awkward0` was intended. The `awkward` package now refers to the 1.x series, which has a different API.
  fix Change your import statement to `import awkward0`. If you intended to use the newer library, install `awkward` (`pip install awkward`) and consult its documentation for correct import paths and API.

Warnings

• breaking The `awkward` package was renamed to `awkward0` starting with version 0.15.0 to avoid conflicts with the new, incompatible Awkward 1.x series (now simply `awkward`). Code using `import awkward` will now import the 1.x series and fail if expecting 0.x behavior.
  Fix: Always use `import awkward0` when intending to use this 0.x branch of the library. If migrating to the newer library, refer to `awkward` (1.x) documentation for new import paths and API changes.
• deprecated The entire `awkward0` library is deprecated and is no longer actively developed. Users are strongly encouraged to migrate to the `awkward` library (formerly `awkward1`) for ongoing development, new features, and improved performance.
  Fix: Plan a migration to the `awkward` package (`pip install awkward`). The newer library offers tools like `ak.from_awkward0` and `ak.to_awkward0` for gradual adoption.
• gotcha Direct saving/loading with `awkward0.save()` or `awkward0.load()` produces a custom format (essentially pickled ZIP archives) that is *not* compatible with the `awkward` (1.x) library. It also might not offer lazy loading for subfields as efficiently as other formats.
  Fix: If interoperability with `awkward` (1.x) or standard formats is needed, consider converting to/from `pyarrow` or `HDF5` using optional dependencies, or use `ak.to_awkward0`/`ak.from_awkward0` to convert to the newer library's format before saving/loading.
• gotcha NumPy 1.20+ introduced deprecation warnings for `np.str` and `np.bool`. While `awkward0` version 0.15.5 fixed the `np.str` warning, older `awkward0` versions might still show warnings when used with newer NumPy versions.
  Fix: Update `awkward0` to 0.15.5 or later. If updating is not possible, these are usually just warnings and do not break functionality, but indicate areas that might break in future NumPy versions.
• gotcha Awkward 0 arrays (like Awkward 1) are largely immutable in their structure. While some properties were mutable as a user convenience in Awkward 0, direct in-place modification of array layouts is generally not supported, which can be a shift for users accustomed to fully mutable Python lists or NumPy arrays.
  Fix: Operations typically return a *new* Awkward Array. If mutable behavior is critical, consider using `awkward0.fromiter` to rebuild or convert to Python lists for modification, then back to Awkward. Understand that this might incur performance costs.

Install

• pip install awkward0 Install Awkward0

Imports

• awkward0
  wrong:

  import awkward

  correct:

  import awkward0

  The original 'awkward' package was renamed to 'awkward0' starting with version 0.15.0 to differentiate it from the new 'awkward' (formerly 'awkward1') library. Importing 'awkward' will likely install and import the newer, incompatible version.

Quickstart

This quickstart demonstrates creating an `awkward0` array from nested Python lists, performing a vectorized NumPy operation on it, accessing elements using array slicing, and converting it back to a standard Python list of lists. `awkward0.fromiter` is a common way to initialize arrays from arbitrary Python structures, though it can be slow for large datasets.

import awkward0
import numpy as np

# Create a jagged array from a Python list of lists
array = awkward0.fromiter([[1.1, 2.2, None], [3.3], [4.4, 5.5, 6.6, None]])
print('Original array:')
print(array)

# Perform a vectorized operation (e.g., square root)
sqrt_array = np.sqrt(array)
print('\nSquare root of array:')
print(sqrt_array)

# Access elements using NumPy-like indexing
first_elements = array[:, 0]
print('\nFirst element of each sublist:')
print(first_elements)

# Convert back to a Python list of lists
list_representation = array.tolist()
print('\nList representation:')
print(list_representation)