ntpstats.profiles¶
Declarative import profiles for instrument exports and other column files.
Test equipment (time-interval counters, PTP/SyncE testers, frequency counters) exports CSV files whose layout differs per vendor and firmware. A profile describes one layout in a few TOML lines, so a new instrument needs no Python code:
.. code-block:: toml
name = "my-tic"
description = "53230A time interval, DUT 1PPS minus REF 1PPS, one reading per line"
value_column = 0 # index or header name
units = "ns" # s, ms, us, ns, ps
quantity = "te" # te: local - reference; offset: reference - local
tau0 = 1.0 # sample interval when there is no time column
# optional
time_column = "Time" # index or header name
time_format = "unix" # unix | iso | mjd | elapsed (seconds from start)
time_units = "s" # for unix/elapsed
delimiter = "," # default: auto (comma, semicolon, tab or spaces)
comment = "#"
skip_rows = 0 # lines to skip before the header or data
header = "auto" # true | false | auto
extra_columns = ["MeanPathDelay"]
Use -f profile:NAME for a built-in profile or -f profile:path.toml
for your own. Built-ins cover generic layouts only; vendor-specific profiles
are added from sample exports that users contribute (issue #35).
Without a profile file, --columns (or -f columns:SPEC) maps the
columns inline, for example --columns time=Time:iso,value=TIE,units=ns
(see :func:columns_profile), and :func:guess_columns proposes a mapping
from the file itself (ntpstats columns FILE), which
:func:profile_toml saves as a profile.
load_profile(ref)
¶
A built-in profile name, or the path of a TOML profile file.
check_profile(prof)
¶
Validate a profile dictionary (raises ValueError) and return it.
columns_profile(spec)
¶
A profile from an inline column mapping.
spec is a comma-separated list of key=value pairs. Columns are
0-based indices or header names. Keys: time (optionally
time=NAME:FORMAT with FORMAT unix, iso, mjd or elapsed), value
(also offset= for reference - local or te= for local - reference,
which sets quantity), units, time_units, quantity,
tau0, delimiter (comma, semicolon, tab, space),
skip, header, comment and extra (several columns joined
with +). Example: time=Time:iso,te=TIE,units=ns,extra=Delay.
columns_spec(prof)
¶
The --columns spec of a profile (the inverse of :func:columns_profile).
profile_toml(prof)
¶
A profile as the TOML text that :func:load_profile reads back.
guess_columns(lines, max_rows=200)
¶
Propose a column mapping for a column file.
Returns {"profile": ..., "spec": ..., "columns": [...], "header": ...,
"rows": [...], "notes": [...]}: the proposed profile (validated), its
--columns spec, one entry per column (index, name, kind
among iso, unix, mjd, elapsed, number, text, and an example), the
header and the first rows as split, and notes on what was guessed and
should be checked (units and sign in particular).
parse_with_profile(lines, prof, name='data', tau0=None)
¶
Parse lines with a profile; returns a series in ntpstats convention (reference - local).