Field Set
A lightweight container for named columnar fields with lazy NumExpr expressions, scoped metadata, and pluggable field sources.
Overview
FieldSet holds named, row-aligned columnar fields and computed expressions over
them. Each field is obtained through a field source — an eager in-memory numpy
array by default, or a lazy provider such as a computed array, a memory-mapped
file, or a vcti-datanode DataNode —
so large or deferred data is loaded only when it is actually read. Expressions
like "strain = stress / youngs_modulus" are parsed and evaluated lazily via
NumExpr and cached, avoiding intermediate arrays. Row operations —
fs.rows().where(...).sort_by(...).head(...).select() — filter, sort, slice, and
group rows lazily into a new FieldSet, folding the chain into one index instead
of copying a table per step. Scoped metadata keeps system settings (components)
and user attributes (units, labels) in separate namespaces,
and an optional [dataframe] extra exports to pandas with MultiIndex columns.
The required core stays small (numpy, numexpr, vcti-cache); heavier integrations
are optional extras.
Installation
pip install vcti-fieldset>=1.4.0
For pandas DataFrame support:
pip install vcti-fieldset[dataframe]>=1.4.0
For binding vcti-datanode DataNodes as fields:
pip install vcti-fieldset[datanode]>=1.4.0
In pyproject.toml dependencies
dependencies = [
"vcti-fieldset>=1.4.0",
]
# or, with DataFrame support:
dependencies = [
"vcti-fieldset[dataframe]>=1.4.0",
]
Quick Start
import numpy as np
from vcti.fieldset import FieldSet
# Create from named arrays
fs = FieldSet(
stress=np.array([100.0, 200.0, 150.0]),
displacement=np.array([0.1, 0.2, 0.15]),
)
# Column operations — expressions compute new columns (lazy)
fs.add_expression("strain = stress / 200000")
fs.get_values("strain") # array([0.0005, 0.001, 0.00075])
# Row operations — filter/sort/slice rows into a new FieldSet
high = fs.rows().where("stress > 120").sort_by("stress", descending=True).select()
high["stress"] # array([200., 150.])
# Metadata — user attributes and system settings
fs.set_property("units", "MPa", field="stress")
fs.set_property("units", "mm", field="displacement")
# Components for multi-dimensional fields
fs = FieldSet(velocity=np.array([[1, 2, 3], [4, 5, 6]]))
fs.set_components("velocity", ["x", "y", "z"])
# Generate pandas DataFrame with MultiIndex columns
df = fs.create_dataframe()
Core API
FieldSet
| Method | Description |
|---|---|
add_data(*args, **kwargs) |
Add structured or named arrays (atomic) |
add_field(name, source) |
Add a field from a FieldSource (e.g. a lazy provider) |
get_values(name) / fs[name] |
Get field array or evaluate expression |
add_expression(expr) |
Register lazy expression (e.g., "c = a + b") |
rows() |
Deferred row-op builder: .where().sort_by().head().slice().select() / .group_by() |
materialize(name) |
Convert expression to permanent field |
remove_field(name) |
Remove a stored field |
remove_expression(name) |
Remove a registered expression |
list_fields() |
List all fields and expressions |
load_from_npz(path) |
Load arrays from .npz file |
set_property(name, value, field) |
Set user attribute or system setting |
get_property(name, field, default) |
Get metadata value |
set_components(field, components) |
Set component names for a field |
get_components(field) |
Get component names |
create_dataframe(fields) |
Generate pandas DataFrame (requires [dataframe]) |
shape |
(rows, total_fields) tuple |
name in fs |
Check if field or expression exists |
for name in fs |
Iterate over field and expression names |
copy.copy(fs) / copy.deepcopy(fs) |
Shallow / deep copy |
Metadata
Pluggable key-value storage with hierarchical key resolution:
| Class | Key format | Use case |
|---|---|---|
DefaultKeyMapper |
a.b.c (separator-joined) |
Simple paths |
ScopedKeyMapper |
system.col.setting / user.col.attr |
System + user scopes |
ConfigKeyMapper |
col.setting |
System-only config |
Dependencies
- numpy (>=1.24)
- numexpr (>=2.8)
- vcti-cache (>=1.0.0) — ObjectCache for expression results
Optional
- pandas (>=2.0) — required for
create_dataframe(), install viavcti-fieldset[dataframe]
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file vcti_fieldset-1.4.0.tar.gz.
File metadata
- Download URL: vcti_fieldset-1.4.0.tar.gz
- Upload date:
- Size: 42.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c6f703e3b2fb9ffdb28c27cec676836f467254a7164d60c40b3a83cd23774be2
|
|
| MD5 |
c6ebf7bcc5954a841f9160be85248df8
|
|
| BLAKE2b-256 |
28adeeb9e87feeb4697be34c8c4b2e62855341aa7c28c86e5f10d1e2a297215e
|
Provenance
The following attestation bundles were made for vcti_fieldset-1.4.0.tar.gz:
Publisher:
publish.yml on vcollab/vcti-python-fieldset
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
vcti_fieldset-1.4.0.tar.gz -
Subject digest:
c6f703e3b2fb9ffdb28c27cec676836f467254a7164d60c40b3a83cd23774be2 - Sigstore transparency entry: 2064139260
- Sigstore integration time:
-
Permalink:
vcollab/vcti-python-fieldset@602e91f57f943e1ada8421440a8538960322f812 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/vcollab
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@602e91f57f943e1ada8421440a8538960322f812 -
Trigger Event:
workflow_dispatch
-
Statement type:
File details
Details for the file vcti_fieldset-1.4.0-py3-none-any.whl.
File metadata
- Download URL: vcti_fieldset-1.4.0-py3-none-any.whl
- Upload date:
- Size: 33.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
746da6844bfa3accb01843cdf7f04eb369f2b237b3ee524d65f33812be51cec4
|
|
| MD5 |
85094679881a7cc7e6f058961b4f3f38
|
|
| BLAKE2b-256 |
52634e28e23a4c21efcff705f255e642f47c6b828fbd15cc129b1d1a78ad4d99
|
Provenance
The following attestation bundles were made for vcti_fieldset-1.4.0-py3-none-any.whl:
Publisher:
publish.yml on vcollab/vcti-python-fieldset
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
vcti_fieldset-1.4.0-py3-none-any.whl -
Subject digest:
746da6844bfa3accb01843cdf7f04eb369f2b237b3ee524d65f33812be51cec4 - Sigstore transparency entry: 2064139283
- Sigstore integration time:
-
Permalink:
vcollab/vcti-python-fieldset@602e91f57f943e1ada8421440a8538960322f812 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/vcollab
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@602e91f57f943e1ada8421440a8538960322f812 -
Trigger Event:
workflow_dispatch
-
Statement type:
