Awkward Array is a library for nested, variable-sized data, including arbitrary-length lists, records, mixed types, and missing data, using NumPy-like idioms.

Arrays are dynamically typed, but operations on them are compiled and fast. Their behavior coincides with NumPy when array dimensions are regular and generalizes when they're not.

How-to documentation for data analysts

How-it-works tutorials for developers

Python API reference C++ API reference

Installation

Awkward Array can be installed from PyPI using pip:

pip install awkward1

Most users will get a precompiled binary (wheel) for your operating system and Python version. If not, the above attempts to compile from source.

• Report bugs, request features, and ask for additional documentation on GitHub Issues. If you have a general "How do I…?" question, we'll answer it as a new example in the tutorial.
• If you have a problem that's too specific to be new documentation or it isn't exclusively related to Awkward Array, it might be more appropriate to ask on StackOverflow with the [awkward-array] tag. Be sure to include tags for any other libraries that you use, such as Pandas or PyTorch.
• The Gitter Scikit-HEP/community is a way to get in touch with all Scikit-HEP developers and users.

Installation for developers

Be sure to clone this repository recursively to get the header-only C++ dependencies.

git clone --recursive https://github.com/scikit-hep/awkward-1.0.git

You can install it on your system with pip, which uses exactly the same procedure as deployment. This is recommended if you do not expect to change the code.

pip install .[test,dev]

Or you can build it locally for incremental development. The following reuses a local directory so that you only recompile what you've changed. This is recommended if you do expect to change the code.

python localbuild.py --pytest tests

• Continuous integration and continuous deployment are hosted by Azure Pipelines.
• Release history (changelog) is hosted by ReadTheDocs.
• CONTRIBUTING.md provides more information on how to contribute.
• The LICENSE is BSD-3.

Using Awkward Array as a dependency

Python projects can simply import awkward1.

C++ projects can link against the shared libraries libawkward-cpu-kernels.so and libawkward.so or their static library equivalents. These libraries are shipped, along with the include files, as part of pip's installation.

• See the dependent-project directory for examples.

Papers and talks about Awkward Array

• Original motivations document from July 2019, now out-of-date.
• StrangeLoop talk on September 14, 2019.
• PyHEP talk on October 17, 2019.
• CHEP talk on November 7, 2019.
• CHEP 2019 proceedings (to be published in EPJ Web of Conferences).
• Demo for Coffea developers on December 20, 2019.
• Demo for Numba developers on January 22, 2020.
• Summary poster on February 27, 2020.
• Demo for Electron Ion Collider users (video) on April 8, 2020.

Acknowledgements

Support for this work was provided by NSF cooperative agreement OAC-1836650 (IRIS-HEP), grant OAC-1450377 (DIANA/HEP) and PHY-1520942 (US-CMS LHC Ops).

Thanks especially to the gracious help of awkward-array contributors (including the original repository).

Jim Pivarski 💻 📖 🚇 🚧	Ianna Osborne 💻	Pratyush Das 💻	Anish Biswas 💻	glass-ships 💻 ⚠️	Henry Schreiner 💻 🚇	Nicholas Smith 💻 ⚠️
Lindsey Gray 💻 ⚠️	Ellipse0934 ⚠️	Dmitry Kalinkin 🚇	Charles Escott 💻	Mason Proffitt 💻	Michael Hedges 💻	Jonas Rembser 💻
Jaydeep Nandi 💻	benkrikler 💻	bfis 💻	Doug Davis 💻	Joosep Pata 🤔	Martin Durant 🤔	Gordon Watts 🤔

💻: code, 📖: documentation, 🚇: infrastructure, 🚧: maintainance, ⚠: tests that drive development, 🤔: foundational ideas.