---

name: awkward-array description: Guidance for working with Awkward Array 2.0 jagged arrays and records in Python. Use when building or debugging awkward workflows, including record construction with ak.zip, adding fields with ak.with_field, filtering/aggregation, combinatorics (ak.cartesian/ak.combinations), argmin/argmax slicing, flattening, sorting, and NumPy interop or common Awkward pitfalls.

Awkward Array

Overview

Use this skill to apply Awkward 2.0 best practices for jagged arrays, especially in HEP-style event data models. Keep guidance lean in this file and load reference notes only when needed.

Core workflow

1. Build an event data model (records) with ak.zip.
2. Filter early at the event level.
3. Perform combinatorics or derived calculations.
4. Add derived fields back into the record with ak.with_field.
5. Repeat until the final values are present in the EDM.

Reference guide

Load only the reference files that matches the task:

• references/best-practices.md: use when setting overall approach or reminding about Awkward 2.0 usage and axes.
• references/records.md: use when building records or adding fields.
• references/filtering-aggregation.md: use for boolean masking, ak.sum/ak.count/ak.num, and axis guidance.
• references/sorting.md: use for ak.sort.
• references/combinatorics.md: use for pairings or n-way combinations (ak.cartesian, ak.combinations).
• references/argmin-argmax.md: use when selecting min/max elements in jagged lists.
• references/flattening.md: use for ak.flatten behavior and axis rules.
• references/numpy-interop.md: use when mixing NumPy operations with Awkward arrays.
• references/pitfalls.md: use for common API mistakes and missing functions.
• references/awkward-files.md: use for file I/O patterns (read/write) with Awkward arrays.

Constraints

• Use Awkward 2.0 APIs and syntax only.
• Avoid axis=None unless the function explicitly supports it.
• Ensure awkward is listed as a dependency in the active environment (venv plus pyproject.toml or requirements.txt).