tsdive.init_tag_meta ¶

init_tag_meta(
    source: str | Path,
    *,
    out: str | Path,
    timestamp_col: str = "timestamp",
    value_col: str = "value",
    quality_col: str = "quality",
    overwrite: bool = False,
    sep: str | None = None,
    decimal: str | None = None,
    encoding: str | None = None,
) -> Path

Write a metadata template for a single-tag export and return its path.

The template holds every key of tsdive.meta in schema order, and a _comments object saying what each key means and which columns of the export were found. identity, name and unit_raw are left null for the caller: nothing about the tag is read off the data. When quality_col exists, quality_codes lists each raw code found in it, mapped to a severity only where the code spells GOOD, UNCERTAIN or BAD itself; every other code stays null. A value column that holds numbers and strings, such as PI digital states, adds each string to quality_codes as null. read_meta_json refuses the file until the identity, the name and every code are filled. The file is read as ingest reads it, sep, decimal and encoding included.

Raises:

Type	Description
`SchemaError`	unreadable input, or a missing timestamp or value column.
`FileExistsError`	`out` exists and `overwrite` is False.

Examples:

>>> import pandas as pd
>>> import tsdive
>>> pd.DataFrame({"ts": ["2024-03-01T00:00:00Z", "2024-03-01T00:01:00Z"],
...               "v": [61.0, 62.0], "q": ["Good", "Questionable"]}
...              ).to_csv("fic101.csv", index=False)
>>> path = tsdive.init_tag_meta("fic101.csv", out="fic101.json", timestamp_col="ts",
...                             value_col="v", quality_col="q")
>>> import json
>>> template = json.loads(path.read_text(encoding="utf-8"))
>>> template["identity"], template["unit_raw"], template["quality_codes"]
({'source_id': None, 'point_id': None}, None, {'Good': 'GOOD', 'Questionable': None})
>>> template["_comments"]["columns"]
"timestamp 'ts', value 'v', quality 'q'; the export has ts, v, q"