| Name | np-struct JSON |
| Version |
0.0.3
JSON |
| download |
| home_page | None |
| Summary | Interface for NumPy structured arrays |
| upload_time | 2025-08-17 01:18:22 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | None |
| keywords |
numpy
structured array
struct
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# np-struct
`np-struct` is a user friendly interface to NumPy structured arrays, with added support for transferring arrays across interfaces.
The `Struct` type is designed to mirror the struct typedef in C, but can be used for any complicated data structure. They behave similar to the standard `ndarray`, but support mixed data types, bitfields, labeling, and variable length arrays. Arrays are easily written or loaded from disk in the standard `.npy` binary format.
## Installation
```bash
pip install np-struct
```
## Usage
```python
import np_struct
from np_struct import Struct
import numpy as np
```
### Structures
Create a C-style structure with Numpy types.
```python
class example(Struct):
data1 = np.uint32()
data2 = np.complex128([0]*3)
```
Structures can be initialized with arbitrary shapes by using the `shape` kwarg:
```python
ex = example(shape = (3,), byte_order='>')
ex[0].data2 = 1 + 2j
```
```python
>>> ex
Struct example: (3,)
[
data1: uint32[0]
data2: complex128[1.+2.j 1.+2.j 1.+2.j]
]
...
[
data1: uint32[0]
data2: complex128[0.+0.j 0.+0.j 0.+0.j]
]
```
Members can also be initialized by passing in their name to the constructor with an initial value.
```python
>>> example(data2 = np.zeros(shape=(3,2)))
Struct example:
data1: uint32[0]
data2: complex128[[0.+0.j 0.+0.j]
[0.+0.j 0.+0.j]
[0.+0.j 0.+0.j]]
```
The structure inherits from np.ndarray and supports all math functions that a normal structured array does.
To cast as a standard numpy structured array,
```python
>>> ex.view(np.ndarray)
array([([0], [0.+0.j, 0.+0.j, 0.+0.j]), ([0], [0.+0.j, 0.+0.j, 0.+0.j]),
([0], [0.+0.j, 0.+0.j, 0.+0.j])],
dtype=[('data1', '<u4', (1,)), ('data2', '<c16', (3,))])
```
Nested structures are also supported,
```python
class nested(Struct):
field1 = example()
field2 = example()
n = nested()
n.field1.data2 += 1j*np.pi
```
```bash
>>> n
Struct nested:
field1: Struct example:
data1: uint32[0]
data2: complex128[0.+3.14159265j 0.+3.14159265j 0.+3.14159265j]
field2: Struct example:
data1: uint32[0]
data2: complex128[0.+0.j 0.+0.j 0.+0.j]
```
To save to disk,
```python
n = nested(shape=2)
n[1].field2.data1 = 3
np.save("test.npy", n)
n_disk = nested(np.load("test.npy"))
```
```python
>>> n_disk.field2.data1
array([[[0]],
[[3]]], dtype=uint32)
```
### Labeled Arrays
`np-struct` implements a very scaled down version of [Xarray](https://docs.xarray.dev/en/stable/) DataArrays.
`ldarray` behaves exactly the same as standard numpy arrays (no need to use .values to avoid errors), can be
written to disk in the standard `.npy` binary format, and supports indexing with coordinates.
Math operations that change the coordinates or array shape (i.e. sum or transpose) silently revert the labeled array
to a standard numpy array without coordinates. `np-struct` leaves it up to the user to re-cast the array as an
`ldarray` with the appropriate coordinates.
```python
>>> from np_struct import ldarray
>>> coords = dict(a=[1,2], b=['data1', 'data2', 'data3'])
>>> ld = ldarray([[10, 11, 12],[13, 14, 15]], coords=coords, dtype=np.float64)
>>> ld
ldarray([[10, 11, 12],
[13, 14, 15]])
Coordinates: (2, 3)
a: [1 2]
b: ['data1' 'data2' 'data3']
```
Arrays can be set or indexed with slices,
```python
>>> coords = dict(a=['data1', 'data2'], b=np.arange(0, 20, 0.2))
>>> data = np.arange(200).reshape(2, 100)
>>> ld = ldarray(data, coords=coords)
>>> ld
ldarray([[ 0, 1, ... 98, 99],
[100, 101, ... 198, 199]])
Coordinates: (2, 100)
a: ['data1' 'data2']
b: [ 0. 0.2 ... 19.6 19.8]
```
Coordinate indexing with slices is inclusive on the endpoint:
```python
>>> ld.sel(b=slice(15, 16), a="data1")
ldarray([75, 76, 77, 78, 79, 80])
Coordinates: (6,)
b: [15. 15.2 ... 15.8 16. ]
```
Setting arrays with coordinates work similar to xarray, where dictionaries can be used as indices
```python
>>> ld[dict(b = 0.2)] = 77
>>> ld.sel(b = 0.2)
ldarray([77, 77])
Coordinates: (2,)
a: ['data1' 'data2']
```
Real or complex-valued arrays can be written to disk uses the normal numpy methods if the coordinates are not needed,
or, to keep the coords, use `ldarray.save()` and `load()`. Array is stored as a structured array in the usual
`.npy` binary format.
```python
ld.save("ld_file.npy")
ldarray.load("ld_file.npy")
```
## Examples
[Struct example](./examples/structures.ipynb)
## License
np-struct is licensed under the MIT License.
Raw data
{
"_id": null,
"home_page": null,
"name": "np-struct",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "numpy, structured array, struct",
"author": null,
"author_email": "Rick Lyon <rlyon14@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/3d/41/3b8722bd22dda405b71c4ec207908b34cbda4e10a29ca6a2ab3dfaa1da96/np_struct-0.0.3.tar.gz",
"platform": null,
"description": "# np-struct\n\n`np-struct` is a user friendly interface to NumPy structured arrays, with added support for transferring arrays across interfaces.\n \nThe `Struct` type is designed to mirror the struct typedef in C, but can be used for any complicated data structure. They behave similar to the standard `ndarray`, but support mixed data types, bitfields, labeling, and variable length arrays. Arrays are easily written or loaded from disk in the standard `.npy` binary format.\n\n## Installation\n\n```bash\npip install np-struct\n```\n\n## Usage\n\n```python\nimport np_struct \nfrom np_struct import Struct\nimport numpy as np\n```\n\n### Structures\n\nCreate a C-style structure with Numpy types.\n\n```python\nclass example(Struct):\n data1 = np.uint32()\n data2 = np.complex128([0]*3)\n```\n\nStructures can be initialized with arbitrary shapes by using the `shape` kwarg:\n```python\nex = example(shape = (3,), byte_order='>')\nex[0].data2 = 1 + 2j\n```\n```python\n>>> ex\nStruct example: (3,)\n[\n data1: uint32[0]\n data2: complex128[1.+2.j 1.+2.j 1.+2.j]\n]\n...\n[\n data1: uint32[0]\n data2: complex128[0.+0.j 0.+0.j 0.+0.j]\n]\n```\n\nMembers can also be initialized by passing in their name to the constructor with an initial value. \n```python\n>>> example(data2 = np.zeros(shape=(3,2)))\nStruct example: \n data1: uint32[0]\n data2: complex128[[0.+0.j 0.+0.j]\n\t [0.+0.j 0.+0.j]\n\t [0.+0.j 0.+0.j]]\n```\n\nThe structure inherits from np.ndarray and supports all math functions that a normal structured array does.\nTo cast as a standard numpy structured array,\n\n```python\n>>> ex.view(np.ndarray)\narray([([0], [0.+0.j, 0.+0.j, 0.+0.j]), ([0], [0.+0.j, 0.+0.j, 0.+0.j]),\n ([0], [0.+0.j, 0.+0.j, 0.+0.j])],\n dtype=[('data1', '<u4', (1,)), ('data2', '<c16', (3,))])\n```\n\nNested structures are also supported,\n```python\nclass nested(Struct):\n field1 = example()\n field2 = example()\n\nn = nested()\nn.field1.data2 += 1j*np.pi\n```\n```bash\n>>> n\nStruct nested: \n field1: Struct example: \n data1: uint32[0]\n data2: complex128[0.+3.14159265j 0.+3.14159265j 0.+3.14159265j]\n field2: Struct example: \n data1: uint32[0]\n data2: complex128[0.+0.j 0.+0.j 0.+0.j]\n```\n\nTo save to disk,\n```python\nn = nested(shape=2)\nn[1].field2.data1 = 3\nnp.save(\"test.npy\", n)\nn_disk = nested(np.load(\"test.npy\"))\n```\n```python\n>>> n_disk.field2.data1\narray([[[0]],\n\n [[3]]], dtype=uint32)\n```\n\n### Labeled Arrays\n\n`np-struct` implements a very scaled down version of [Xarray](https://docs.xarray.dev/en/stable/) DataArrays. \n`ldarray` behaves exactly the same as standard numpy arrays (no need to use .values to avoid errors), can be\nwritten to disk in the standard `.npy` binary format, and supports indexing with coordinates. \n\nMath operations that change the coordinates or array shape (i.e. sum or transpose) silently revert the labeled array \nto a standard numpy array without coordinates. `np-struct` leaves it up to the user to re-cast the array as an\n`ldarray` with the appropriate coordinates.\n\n\n```python\n>>> from np_struct import ldarray\n\n>>> coords = dict(a=[1,2], b=['data1', 'data2', 'data3'])\n>>> ld = ldarray([[10, 11, 12],[13, 14, 15]], coords=coords, dtype=np.float64)\n>>> ld\nldarray([[10, 11, 12],\n [13, 14, 15]])\nCoordinates: (2, 3)\n a: [1 2]\n b: ['data1' 'data2' 'data3']\n```\n\nArrays can be set or indexed with slices,\n\n```python\n>>> coords = dict(a=['data1', 'data2'], b=np.arange(0, 20, 0.2))\n>>> data = np.arange(200).reshape(2, 100)\n>>> ld = ldarray(data, coords=coords)\n>>> ld\nldarray([[ 0, 1, ... 98, 99],\n [100, 101, ... 198, 199]])\nCoordinates: (2, 100)\n a: ['data1' 'data2']\n b: [ 0. 0.2 ... 19.6 19.8]\n```\n\nCoordinate indexing with slices is inclusive on the endpoint:\n```python\n>>> ld.sel(b=slice(15, 16), a=\"data1\")\nldarray([75, 76, 77, 78, 79, 80])\nCoordinates: (6,)\n b: [15. 15.2 ... 15.8 16. ]\n```\n\nSetting arrays with coordinates work similar to xarray, where dictionaries can be used as indices\n```python\n>>> ld[dict(b = 0.2)] = 77\n>>> ld.sel(b = 0.2)\nldarray([77, 77])\nCoordinates: (2,)\n a: ['data1' 'data2']\n```\n\nReal or complex-valued arrays can be written to disk uses the normal numpy methods if the coordinates are not needed, \nor, to keep the coords, use `ldarray.save()` and `load()`. Array is stored as a structured array in the usual \n`.npy` binary format.\n```python\nld.save(\"ld_file.npy\")\nldarray.load(\"ld_file.npy\")\n```\n\n## Examples\n\n[Struct example](./examples/structures.ipynb) \n\n\n## License\n\nnp-struct is licensed under the MIT License.\n",
"bugtrack_url": null,
"license": null,
"summary": "Interface for NumPy structured arrays",
"version": "0.0.3",
"project_urls": {
"repository": "https://github.com/ricklyon/np_struct"
},
"split_keywords": [
"numpy",
" structured array",
" struct"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a43d88749facff8fd56640f5092ebbcb4977295959295f402d5d4fc0241bfb8e",
"md5": "2b2a389065b79d9a7549cc79a87e0238",
"sha256": "b07932608597e9dab278da05cfb2d24581dc869a80201b883962dd9ec8966704"
},
"downloads": -1,
"filename": "np_struct-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2b2a389065b79d9a7549cc79a87e0238",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 17963,
"upload_time": "2025-08-17T01:18:21",
"upload_time_iso_8601": "2025-08-17T01:18:21.338587Z",
"url": "https://files.pythonhosted.org/packages/a4/3d/88749facff8fd56640f5092ebbcb4977295959295f402d5d4fc0241bfb8e/np_struct-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3d413b8722bd22dda405b71c4ec207908b34cbda4e10a29ca6a2ab3dfaa1da96",
"md5": "e543fd4f86e2636b1c3c2fdf93f8c414",
"sha256": "9d6b968b27fdd8034fa593b39f09de1e6b9c3ff9a239a4acc751266a068a11ac"
},
"downloads": -1,
"filename": "np_struct-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "e543fd4f86e2636b1c3c2fdf93f8c414",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 20531,
"upload_time": "2025-08-17T01:18:22",
"upload_time_iso_8601": "2025-08-17T01:18:22.526059Z",
"url": "https://files.pythonhosted.org/packages/3d/41/3b8722bd22dda405b71c4ec207908b34cbda4e10a29ca6a2ab3dfaa1da96/np_struct-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-17 01:18:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ricklyon",
"github_project": "np_struct",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "np-struct"
}
