pycsamt.jones.property#

Site‑level properties parsed from the J‑format information block.

This module defines a lightweight container for the metadata exposed in lines beginning with >KEY=VALUE in A.G. Jones J files. It focuses on robust parsing and normalization (e.g., azimuth wrapping, latitude/longitude hemispheres, and missing sentinels).

Classes

JSiteProperty([azimuth, latitude, ...])

Container for site properties parsed from J-format info.

class pycsamt.jones.property.JSiteProperty(azimuth=None, latitude=None, longitude=None, elevation=None, extra=<factory>, verbose=0, strict=False)[source]#

Bases: object

Container for site properties parsed from J-format info.

This class stores site-level metadata such as latitude, longitude, azimuth, and elevation that are declared in the J-format information block as >KEY=VALUE lines.

Parameters:

azimuth (float or None, optional) – Site X-axis azimuth in degrees, referenced to true north. Values are wrapped to [0, 360) when parsed.
latitude (float or None, optional) – Latitude in decimal degrees. Inputs may include DMS or hemisphere suffixes and are normalized to [-90, 90].
longitude (float or None, optional) – Longitude in decimal degrees. Inputs may include DMS or hemisphere suffixes and are normalized to [-180, 180).
elevation (float or None, optional) – Elevation in metres. Missing sentinels are mapped to None.
extra (dict of (str -> str), optional) – Unrecognized >KEY=VALUE pairs preserved verbatim.
verbose (int or bool, default 0) – Verbosity for non-fatal parsing warnings.
strict (bool, default False) – If True, out-of-range coordinates raise errors instead of being coerced to valid bounds.

Variables:

location (tuple of (float, float) or None) – Convenience property returning (lat, lon) when both are available, else None.
azimuth_rad (float or None) – Azimuth converted to radians when available.

Notes

Parsing leverages robust coordinate helpers that accept DMS, hemisphere letters, and free whitespace. Longitudes are normalized into the half-open interval [-180, 180).

Examples

>>> lines = [\">LATITUDE = 41.9782\", \">LONGITUDE = 140.8958\"]\n
>>> prop = JSiteProperty.from_lines(lines)\n
>>> prop.location\n
(41.9782, 140.8958)

See also

Info: High-level container of the information block which can be used to build a JSiteProperty.

References

azimuth: float | None = None#

latitude: float | None = None#

longitude: float | None = None#

elevation: float | None = None#

extra: dict[str, str]#

verbose: int | bool = 0#

strict: bool = False#

classmethod from_file(obj, *, encoding='utf-8', strict=False, verbose=0)[source]#

Build a JSiteProperty from a J file path or file-like object.

Only the initial information block is consumed. Later station or data sections are ignored by this method.

Parameters:

obj (str or pathlib.Path or TextIO) – Path to a J file or an open text stream positioned at the beginning of the file.
encoding (str, default 'utf-8') – Text encoding used when reading from a file path.
strict (bool, default False) – If True, invalid coordinates raise. If False, out-of-range values are coerced with a warning.
verbose (int or bool, default 0) – Verbosity for non-fatal parsing warnings.

Returns:

Parsed site properties.

Return type:

JSiteProperty

Notes

This method stops at the first line that is not a comment, not blank, and not a >KEY=VALUE record.

Examples

>>> prop = JSiteProperty.from_file(\"data/j/kb0-s001.txt\")\n
>>> prop.azimuth is None or 0.0 <= prop.azimuth < 360.0\n
True

See also

from_lines: Parse from an in-memory sequence of lines.
from_mapping: Quick constructor from a dict of keys and values.

References

classmethod from_lines(lines, *, strict=False, verbose=0)[source]#

Build a JSiteProperty from an iterable of lines.

The parser reads sequentially and collects >KEY=VALUE pairs as long as lines are comments, blanks, or info records. It stops at the first non-conforming line.

Parameters:

lines (iterable of str) – Lines that include the information block content.
strict (bool, default False) – If True, invalid coordinates raise. If False, out-of-range values are coerced with a warning.
verbose (int or bool, default 0) – Verbosity for non-fatal parsing warnings.

Returns:

Parsed site properties.

Return type:

JSiteProperty

Notes

Latitude and longitude accept flexible text including DMS and hemisphere tokens. Longitudes are normalized into [-180, 180).

Examples

>>> from pycsamt.
>>> lines = [\n
...   \">AZIMUTH = -30.0\", \">LATITUDE = 41.9782\",\n
...   \">LONGITUDE = 140.8958\", \">ELEVATION = 0.0\",\n
... ]\n
>>> prop = JSiteProperty.from_lines(lines)\n
>>> prop.location[0] == 41.9782\n
True

See also

from_file: Parse from a file path or open stream.
from_mapping: Quick constructor from a dict of keys and values.

References

classmethod from_mapping(mapping, *, strict=False, verbose=0)[source]#

Build a JSiteProperty from a dict of key-value pairs.

Keys can be any case and will be normalized to the upper case tokens used by J files. Values can be strings or numbers. Unknown keys are preserved in extra.

Parameters:

mapping (Mapping[str, Any]) – Pairs like {\"latitude\": 41.9, \"longitude\": 140.8}.
strict (bool, default False) – If True, invalid coordinates raise. If False, out-of-range values are coerced with a warning.
verbose (int or bool, default 0) – Verbosity for non-fatal parsing warnings.

Returns:

Parsed site properties.

Return type:

JSiteProperty

Notes

This is a convenience front-end that converts the mapping to synthetic >KEY=VALUE lines and forwards the work to from_lines().

Examples

>>> prop = JSiteProperty.from_mapping({\n
...   'azimuth': 370, 'latitude': '41:58N',\n
...   'longitude': '140:54E', 'elevation': 0,\n
... })\n
>>> 0.0 <= (prop.azimuth or 0.0) < 360.0\n
True

See also

from_lines: Parse from an in-memory sequence of lines.
from_file: Parse from a file path or open stream.

References

asdict()[source]#

Return type:: dict[str, float | None]

property location: tuple[float, float] | None[source]#

property azimuth_rad: float | None[source]#