Metadata-Version: 2.4
Name: fletchr-measurand
Version: 0.0.1rc4
Summary: Arrow-native bit-fragment extraction and engineering-unit decoding for binary protocol data.
Project-URL: Homepage, https://github.com/fletchr-labs/fletchr
Project-URL: Repository, https://github.com/fletchr-labs/fletchr
Project-URL: Issues, https://github.com/fletchr-labs/fletchr/issues
Project-URL: Specification, https://github.com/fletchr-labs/fletchr/blob/main/fletchr-measurand/SPEC-decode.md
Author-email: Jonathan Olsten <jolsten@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: arrow,bit-fragment,decoding,engineering-units,protocol,pyarrow
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: antlr4-python3-runtime>=4.13.2
Requires-Dist: attrs>=22.1.0
Requires-Dist: byteforge>=0.0.6
Requires-Dist: eval-type-backport>=0.2.0; python_version < '3.10'
Requires-Dist: fletchr-uintn>=0.0.1rc2
Requires-Dist: lark>=1.3.1
Requires-Dist: numpy>=2.0
Requires-Dist: pyarrow>=16
Requires-Dist: varuintarray>=1.3.0
Description-Content-Type: text/markdown

# fletchr-measurand

Arrow-native bit-fragment extraction and engineering-unit decoding for
binary protocol data. Parses parameter and measurand spec strings into
evaluable objects; runs them against `pa.Table`s whose data columns are
[`fletchr.uintn`](https://github.com/fletchr-labs/fletchr/tree/main/fletchr-uintn)
extension arrays.

## Why?

Bit-packed protocol data routinely needs two things:

- **Bit-fragment extraction** — "this value is word 3 concatenated with
  word 4 as a 16-bit value." Done by hand, it's masking and shifting;
  done at scale, it's bugs.
- **Engineering-unit decoding** — "raw × 0.1 + (-273.15)" for a scaled
  measurement.

`fletchr-measurand` makes both declarative. `Parameter("[1+2]")` extracts
word 1 concatenated with word 2; `Measurand(parameter=..., encoding="2c",
euc=EUC(...))` adds decoding (two's complement, float, etc.) and scaling.

## Features

- **Parameter DSL** — `[1]` (single word), `[1+2]` (multi-word, MSB
  first), `[1-3]` (range), `[1+3+5]` (non-contiguous concatenation); plus
  generator / iteration patterns for repeated bit-fragments at successive
  column offsets.
- **Level 1 encodings via [byteforge](https://github.com/jolsten/byteforge)** —
  unsigned, sign-magnitude, one's-complement, two's-complement,
  offset-binary, IEEE 754 (32/64), MIL-STD-1750A (32/48), packed BCD,
  Gray code, IBM/DEC/TI floats.
- **Level 2 EUC** — linear scaling (`scale_factor`, `data_bias`,
  `scaled_bias`) and arbitrary callable transforms.
- **Arrow-native build chain** — `Parameter.build` and `Measurand.build`
  consume `pa.Table` directly and return `pa.ExtensionArray` /
  `MeasurandResult`. Validity bitmaps propagate through both decode
  levels.
- **Field-metadata convention** — the `fletchr.encoding` /
  `fletchr.scale_factor` / `fletchr.data_bias` / `fletchr.scaled_bias`
  keys defined in
  [SPEC-decode.md](https://github.com/fletchr-labs/fletchr/blob/main/fletchr-measurand/SPEC-decode.md)
  give a language-neutral wire format for decode rules attached to Arrow
  column metadata.

## Install

```bash
uv add fletchr-measurand        # or: pip install fletchr-measurand
```

Requires Python 3.9+. Pulls in `fletchr-uintn`, `pyarrow >= 16`,
`numpy >= 2.0`, `byteforge`, `lark`, and `antlr4-python3-runtime`.

## Quickstart

```python
import pyarrow as pa
from fletchr_uintn import uintn_array
from fletchr_measurand import EUC, Measurand, parameter_parser

# A FrameArray-shaped pa.Table: one column per word position (c0..cN),
# each a fletchr.uintn column. Real users get this from fletchr-core's
# FrameArray; constructed manually here for illustration.
table = pa.table({
    "c0": uintn_array([0x12, 0x34, 0x56], bits=8),
    "c1": uintn_array([0xFF, 0x80, 0x00], bits=8),
    "c2": uintn_array([0x10, 0x20, 0x30], bits=8),
})

# Parameter spec is 1-based: [2] selects word 2 (column c1). Decode it as
# signed two's-complement, then linear-scale to Celsius from a centikelvin
# raw representation.
m = Measurand(
    parameter=parameter_parser.parse("[2]"),
    encoding="2c",
    euc=EUC(scale_factor=0.1, scaled_bias=-273.15),
)

result = m.build(table)
result.dns.to_pylist()        # [255, 128, 0]       — raw 8-bit DNs
result.decoded.to_pylist()    # [-1, -128, 0]       — Level 1: two's-complement
result.values.to_pylist()     # [-273.25, -285.95, -273.15]  — Level 2: scale + bias
```

Multi-word values use `+` to concatenate, MSB first:

```python
# Words 2 and 3 as a single 16-bit unsigned value (c1 high, c2 low).
m16 = Measurand(parameter=parameter_parser.parse("[2+3]"))
m16.build(table).values.to_pylist()    # [65296, 32800, 48]
```

See [SPEC-decode.md](https://github.com/fletchr-labs/fletchr/blob/main/fletchr-measurand/SPEC-decode.md)
for the full encoding registry and the field-metadata convention.

## Public API

```python
from fletchr_measurand import (
    # Parameter / Measurand DSL
    Parameter, ParameterSpec, parameter_parser,
    Measurand, MeasurandSpec, measurand_parser,
    resolve_parameter, resolve_measurand,
    # Result + Level 2 transform
    MeasurandResult,
    EUC, SamplingStrategy,
    # Calculator parser (for the SPEC's expression-mode hook)
    calculator_parser,
)
```

## Status

The runtime data model (`Parameter`, `Measurand`, `MeasurandResult`,
`EUC`) is stable. The wire-format convention in `SPEC-decode.md` is
**draft v0.5** — the encoding registry is locked, but one open question
remains (the expression-mode allow-list) before incrementing to v1.0.
Field-metadata read/write helpers that round-trip the SPEC keys onto
`pa.Field.metadata` are tracked as future work.

## Links

- Source: <https://github.com/fletchr-labs/fletchr>
- Issues: <https://github.com/fletchr-labs/fletchr/issues>
- Decode metadata spec: [SPEC-decode.md](https://github.com/fletchr-labs/fletchr/blob/main/fletchr-measurand/SPEC-decode.md)

## License

MIT.
