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.
Motivating example
Given an array of objects with x, y fields and variable-length nested lists like
array = ak.Array([
[{"x": 1.1, "y": [1]}, {"x": 2.2, "y": [1, 2]}, {"x": 3.3, "y": [1, 2, 3]}],
[],
[{"x": 4.4, "y": {1, 2, 3, 4]}, {"x": 5.5, "y": [1, 2, 3, 4, 5]}]
])
the following slices out the y values, drops the first element from each inner list, and runs NumPy's np.square function on everything that is left:
output = np.square(array["y", ..., 1:])
The result is
[
[[], [4], [4, 9]],
[],
[[4, 9, 16], [4, 9, 16, 25]]
]
The equivalent using only Python is
output = []
for sublist in array:
tmp1 = []
for record in sublist:
tmp2 = []
for number in record["y"][1:]:
tmp2.append(np.square(number))
tmp1.append(tmp2)
output.append(tmp1)
Not only is the expression using Awkward Arrays more concise, using idioms familiar from NumPy, but it's much faster and uses less memory.
For a similar problem 10 million times larger than the one above (on a single-threaded 2.2 GHz processor),
- the Awkward Array one-liner takes 4.6 seconds to run and uses 2.1 GB of memory,
- the equivalent using Python lists and dicts takes 138 seconds to run and uses 22 GB of memory.
Speed and memory factors in the double digits are common because we're replacing Python's dynamically typed, pointer-chasing virtual machine with type-specialized, precompiled routines on contiguous data. (In other words, for the same reasons as NumPy.) Even higher speedups are possible when Awkward Array is paired with Numba.
Our presentation at SciPy 2020 provides a good introduction, showing how to use these arrays in a real analysis.
Installation
Awkward Array can be installed from PyPI using pip:
pip install awkward
You will likely get a precompiled binary (wheel), depending on your operating system and Python version. If not, pip attempts to compile from source (which requires a C++ compiler, make, and CMake).
Awkward Array is also available using conda, which always installs a binary:
conda install -c conda-forge awkward
If you have already added conda-forge as a channel, the -c conda-forge is unnecessary. Adding the channel is recommended because it ensures that all of your packages use compatible versions:
conda config --add channels conda-forge
conda update --all
Getting help
|
|
- Report bugs, request features, and ask for additional documentation on GitHub Issues.
- If you have a "How do I...?" question, ask about it on StackOverflow with the [awkward-array] tag. Be sure to include tags for any other libraries that you use, such as Pandas or PyTorch.
- To ask questions in real time, try the Gitter Scikit-HEP/awkward-array chat room.
1 maintainer
Release files for awkward1 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| awkward1-1.0.0.tar.gz | 817.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| awkward1-1.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 821.8 kB
Release files / awkward1-1.0.0.tar.gz
| Download URL | awkward1-1.0.0.tar.gz |
|---|---|
| Size | 817.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4e51fed29c3a3618cdc07719ff3d1cdd1d567643f9629532bd7d965f9fb76c50
|
|
BLAKE2b-256 checksum How to use checksums |
05e1de4607482cd18eb43bfb4c7381571ad0928f7ebf0ed5815f93b21cc5e46a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.2.0 pkginfo/1.6.1 requests/2.24.0 setuptools/49.6.0.post20201009 requests-toolbelt/0.9.1 tqdm/4.52.0 CPython/3.8.5
|
Release files / awkward1-1.0.0-py3-none-any.whl
| Download URL | awkward1-1.0.0-py3-none-any.whl |
|---|---|
| Size | 4.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
36e6cd64faf3246da030fa7a088ca23f60a5683ef57ab1068f22665599a578df
|
|
BLAKE2b-256 checksum How to use checksums |
801654835de4e8b154eee13fecc32f4ef22ee2fca734a01d74a63e12e367686c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.2.0 pkginfo/1.6.1 requests/2.24.0 setuptools/49.6.0.post20201009 requests-toolbelt/0.9.1 tqdm/4.52.0 CPython/3.8.5
|
