2.11.1.9. 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

[JSiteProperty-1]

A. G. Jones (1994). Magnetotelluric data file J-format, version 2.0.

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

[JSiteProperty-from-file-1]

A. G. Jones (1994). Magnetotelluric data file J-format, version 2.0.

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

[JSiteProperty-from-lines-1]

A. G. Jones (1994). Magnetotelluric data file J-format, version 2.0.

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

[JSiteProperty-from-mapping-1]

A. G. Jones (1994). Magnetotelluric data file J-format, version 2.0.

asdict()[source]
Return type:

dict[str, float | None]

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