pycsamt.jones.heads#

Classes

Banner([top_lines, software, station, date, ...])

Parse and serialize the top provenance comment line.

Head([j_header_list, verbose])

Parse and serialize a single J-format head triple.

HeadMixin()

Mixin that provides a Head on host classes.

Heads([head, info, verbose])

Minimal container for one Head and one Info.

Info([j_info_list, verbose])

Parse and serialize the J-format information block.

InfoMixin()

Mixin that provides an Info on host classes.
class pycsamt.jones.heads.Head(j_header_list=None, *, verbose=0, **kwargs)[source]#

Bases: JComponentBase

Parse and serialize a single J-format head triple.

This lightweight component represents one data-block header consisting of the station line, the data-type line, and the row count. It provides a consistent constructor and the read / write round-trip expected by the package.

Parameters:

  • j_header_list (sequence of str, optional) – Three logical header lines. The sequence may be a clean triple [station, dtype, n] or a longer slice from a file; the parser will extract the first valid triple.

  • verbose (int, default=0) – Verbosity for warnings during parsing.

  • **kwargs – Accepted for API forwards-compatibility; ignored here.

Variables:

  • station (str or None) – Upper-cased station identifier. Trailing azimuth tokens on the same line are supported and ignored here (but see az_hint).

  • dtype (DataType or None) – Parsed data-type token (e.g., ZXY, RTE) with optional normalized units and a TE/TM tensor hint.

  • n (int or None) – Number of data rows that follow this header.

  • az_hint (float or None) – Optional azimuth extracted from the station line when present (e.g., KB0001  -30). This is not the same as site AZIMUTH from the info block.

  • path (pathlib.Path or None) – Source path when constructed via from_file().

  • encoding (str) – Text encoding used by from_file().

  • verbose (int) – Verbosity level inherited from JComponentBase.

from_file(j_fn, \*, verbose=0)[source]#

Read a file and return a Head. Only the first valid triple is parsed.

Parameters:
Return type:

Head

from_lines(j_header_list, \*, verbose=0)[source]#

Build a Head from an in-memory sequence. If the sequence is longer than three lines, the first valid triple is extracted.

Parameters:
Return type:

Head

read(j_header_list)[source]#

Parse the header triple into attributes and mark the instance as read (see __has_read__).

Parameters:

j_header_list (Sequence[str] | None)

Return type:

Head

write(head_list_infos=None)[source]#

Return a list of three strings representing the header triple. If head_list_infos is given, it is parsed first and then serialized.

Parameters:

head_list_infos (Sequence[str] | None)

Return type:

list[str]

Notes

The station regex accepts common field variants, including hyphens and underscores, and an optional numeric azimuth token after the station id. The data-type parser is liberal with whitespace and recognizes SI (S.I.) and FIELD units.

Examples

>>> Head().read(['KB0001  -30', 'ZXY SI', '29'])
Head(station='KB0001', n=29)
>>> h = Head.from_file('data/j/kb0-s001.txt')
>>> h.station
'KB0001'

See also

Info

Site information (>KEY=VALUE lines).

Heads

Container combining one Head and one Info.

JSiteProperty

Robust latitude/longitude parsing.

DataType

Structured token for kind / comp / units.

References

classmethod from_file(j_fn, *, verbose=0)[source]#
Parameters:
Return type:

Head

classmethod from_lines(j_header_list=None, *, verbose=0)[source]#
Parameters:
Return type:

Head

read(j_header_list=None)[source]#
Parameters:

j_header_list (Sequence[str] | None)

Return type:

Head

write(head_list_infos=None)[source]#
Parameters:

head_list_infos (Sequence[str] | None)

Return type:

list[str]

property kind: str | None[source]#
property comp: str | None[source]#
property units: str | None[source]#
property tensor_hint: str | None[source]#
property header: tuple[str, str, int] | None[source]#
class pycsamt.jones.heads.Info(j_info_list=None, *, verbose=0, **kwargs)[source]#

Bases: JComponentBase

Parse and serialize the J-format information block.

This component collects >KEY=VALUE records along with leading comment lines. It exposes a small set of convenience properties derived from JSiteProperty.

Parameters:

  • j_info_list (sequence of str, optional) – A sequence containing the comment and information records. The parser stops at the first non-info, non-comment, non-blank line.

  • verbose (int, default=0) – Verbosity for warnings during parsing.

  • **kwargs – Accepted for API forwards-compatibility; ignored here.

Variables:

  • items (dict of (str -> str)) – Mapping of upper-cased keys to unmodified string values.

  • comments (list of str) – Preserved leading comment lines (starting with #).

  • site (JSiteProperty) – Lazily parsed view providing normalized latitude, longitude, azimuth and elevation (see properties below).

  • latitude (float or None) – Decimal degrees; hemisphere and DMS tolerated.

  • longitude (float or None) – Decimal degrees in [-180, 180).

  • azimuth (float or None) – Site X-axis azimuth (degrees, true north).

  • elevation (float or None) – Elevation in metres.

  • path (pathlib.Path or None) – Source path when constructed via from_file().

  • encoding (str) – Text encoding used by from_file().

  • verbose (int) – Verbosity level inherited from JComponentBase.

from_file(j_fn, \*, verbose=0)[source]#

Read only the comment/info header from a file.

Parameters:
Return type:

Info

from_lines(j_info_list, \*, verbose=0)[source]#

Build from an in-memory sequence.

Parameters:
Return type:

Info

read(j_info_list)[source]#

Parse the header and mark the instance as read.

Parameters:

j_info_list (Sequence[str] | None)

Return type:

Info

write(j_info_list=None)[source]#

Render comments and >KEY = VALUE lines.

Parameters:

j_info_list (Sequence[str] | None)

Return type:

list[str]

Notes

Unknown keys are preserved verbatim. Coordinate and azimuth values are normalized via JSiteProperty, which handles ranges, hemispheres and DMS.

Examples

>>> info = Info.from_file('data/j/kb0-s001.txt')
>>> info.latitude, info.longitude
(41.9782, 140.8958)
>>> lines = info.write()
>>> Info.from_lines(lines).azimuth == info.azimuth
True

See also

Head

One data-block header (station / dtype / count).

Heads

Combined view with convenience properties.

JSiteProperty

Robust parsing used by this class.

References

classmethod from_file(j_fn, *, verbose=0)[source]#
Parameters:
Return type:

Info

classmethod from_lines(j_info_list=None, *, verbose=0)[source]#
Parameters:
Return type:

Info

write(j_info_list=None)[source]#
Parameters:

j_info_list (Sequence[str] | None)

Return type:

list[str]

read(j_info_list=None)[source]#
Parameters:

j_info_list (Sequence[str] | None)

Return type:

Info

property site: JSiteProperty[source]#
property latitude: float | None[source]#
property longitude: float | None[source]#
property azimuth: float | None[source]#
property elevation: float | None[source]#
get(key, default=None)[source]#
Parameters:

  • key (str)

  • default (str | None)

Return type:

str | None

keys()[source]#
Return type:

tuple[str, …]

values()[source]#
Return type:

tuple[str, …]

items_map()[source]#
Return type:

dict[str, str]

property lat: float | None[source]#
property lon: float | None[source]#
class pycsamt.jones.heads.Heads(head=None, info=None, *, verbose=0)[source]#

Bases: JComponentBase

Minimal container for one Head and one Info.

The class provides convenient accessors for station and site-level properties, and a small banner recorder for the top provenance line (#WRITTEN BY ...). It is intended as the lightest useful representation of a single J header section.

Parameters:

  • head (Head, optional) – Existing head to attach. If omitted, an empty Head is created.

  • info (Info, optional) – Existing info to attach. If omitted, an empty Info is created.

  • verbose (int, default=0) – Verbosity for warnings during parsing.

Variables:

  • head (Head) – The parsed header triple.

  • info (Info) – The parsed site information block.

  • banner (Banner) – Parsed top comment provenance. The writer defaults the software field to PYSCAMT if missing.

  • n (int) – 0 or 1 depending on whether a head has been parsed.

  • station (str or None) – Shortcut to head.station.

  • azimuth (latitude, longitude, elevation,) – Shortcuts to values provided by info. azimuth falls back to head.az_hint when the info block does not contain AZIMUTH.

from_file(j_fn, \*, verbose=0)[source]#

Read the file then delegate to read().

Parameters:
Return type:

Heads

from_lines(lines, \*, verbose=0)[source]#

Build from an in-memory line sequence.

Parameters:
Return type:

Heads

read(text_or_lines)[source]#

Extract info + head lists and parse both.

Parameters:

text_or_lines (str | Sequence[str])

Return type:

Heads

write()[source]#

Serialize banner, head and info back-to-back.

Return type:

list[str]

Notes

This class does not parse the subsequent data rows. It is focused on fast, dependency-free header discovery to support scanning tasks and metadata extraction.

Examples

>>> h = Heads.from_file('data/j/kb0-s001.txt')
>>> h.station, h.latitude, h.software
('KB0001', 41.9782, 'GEOTOOLS')

See also

Head

Single data-block header.

Info

Site-level header.

Banner

Top provenance line handler.

References

read(text_or_lines)[source]#
Parameters:

text_or_lines (str | Sequence[str])

Return type:

Heads

write(include_origin=False)[source]#
Return type:

list[str]

classmethod from_lines(lines, *, verbose=0)[source]#
Parameters:
Return type:

Heads

classmethod from_file(j_fn, *, verbose=0)[source]#
Parameters:
Return type:

Heads

property n: int[source]#
property station: str | None[source]#
property latitude: float | None[source]#
property longitude: float | None[source]#
property elevation: float | None[source]#
property azimuth: float | None[source]#
property software: str | None[source]#
class pycsamt.jones.heads.HeadMixin[source]#

Bases: object

Mixin that provides a Head on host classes.

The mixin offers class-level and instance-level helpers that delegate to Head while keeping a single copy of the header on the host.

Variables:

head (Head) – Lazily created and cached on first use.

from_file(edi_fn)[source]#

Class method that returns Head.from_file(edi_fn).

Parameters:

edi_fn (str | Path)

Return type:

Head

read(j_header_list=None)[source]#

Ensure a Head exists on the host, parse into it, and return it.

Parameters:

j_header_list (Sequence[str] | None)

Return type:

Head

write(head_list_infos=None)[source]#

Serialize the host’s Head to three header lines.

Parameters:

head_list_infos (Sequence[str] | None)

Return type:

list[str]

Examples

>>> class Host(HeadMixin):
...     pass
>>> Host.from_file('file.j')
Head(...)
head: Head#
classmethod from_file(edi_fn)[source]#
Parameters:

edi_fn (str | Path)

Return type:

Head

read(j_header_list=None)[source]#
Parameters:

j_header_list (Sequence[str] | None)

Return type:

Head

write(head_list_infos=None)[source]#
Parameters:

head_list_infos (Sequence[str] | None)

Return type:

list[str]

class pycsamt.jones.heads.InfoMixin[source]#

Bases: object

Mixin that provides an Info on host classes.

The mixin mirrors HeadMixin but for the information block. It centralizes parsing and writing of >KEY=VALUE lines.

Variables:

info (Info) – Lazily created and cached on first use.

from_file(edi_fn)[source]#

Class method that returns Info.from_file(edi_fn).

Parameters:

edi_fn (str | Path)

Return type:

Info

read(j_info_list=None)[source]#

Ensure an Info exists on the host, parse into it, and return it.

Parameters:

j_info_list (Sequence[str] | None)

Return type:

Info

write(j_info_list=None)[source]#

Serialize the host’s Info to comment and info lines.

Parameters:

j_info_list (Sequence[str] | None)

Return type:

list[str]

Examples

>>> class Host(InfoMixin):
...     pass
>>> Host().read(['>LATITUDE=10'])
Info(items=1)
info: Info#
classmethod from_file(edi_fn)[source]#
Parameters:

edi_fn (str | Path)

Return type:

Info

read(j_info_list=None)[source]#
Parameters:

j_info_list (Sequence[str] | None)

Return type:

Info

write(j_info_list=None)[source]#
Parameters:

j_info_list (Sequence[str] | None)

Return type:

list[str]

class pycsamt.jones.heads.Banner(top_lines=None, *, software=None, station=None, date=None, note=None, verbose=0)[source]#

Bases: JComponentBase

Parse and serialize the top provenance comment line.

This helper targets lines such as:

#WRITTEN BY GEOTOOLS: kb0-s001 10/06/95 RAW RECS

It extracts the producer software name, an optional station hint, a free-form date token, and an optional trailing note. The writer defaults the software field to PYSCAMT when none is provided.

Parameters:

  • top_lines (sequence of str, optional) – An initial slice of file lines. The constructor scans these lines and parses the first matching banner.

  • software (str, optional) – Producer software name (e.g., 'GEOTOOLS'). When omitted and the banner is not present, the writer uses 'PYSCAMT' as a default.

  • station (str, optional) – Station identifier hint found in the banner. This does not replace the station found in the Head.

  • date (str, optional) – Free-form date token as found in the banner line.

  • note (str, optional) – Extra text following the date token on the same line.

  • verbose (int, default=0) – Verbosity for warnings during parsing.

Variables:

  • software (str or None) – Producer software parsed from the banner or provided by the user.

  • station_hint (str or None) – Station token parsed from the banner; may differ from the station found in the Head.

  • date (str or None) – Banner date token as text; not parsed into a datetime.

  • note (str or None) – Trailing free-form text after the date token.

  • path (pathlib.Path or None) – Source path when constructed via from_file().

  • encoding (str) – Text encoding used by from_file().

  • verbose (int) – Verbosity level inherited from JComponentBase.

from_file(j_fn, \*, verbose=0)[source]#

Read a file, scan the top lines, and return a parsed Banner.

Parameters:
Return type:

Banner

from_lines(lines, \*, verbose=0)[source]#

Build a Banner from an in-memory sequence of lines.

Parameters:
Return type:

Banner

read(top_lines)[source]#

Parse the first matching banner from the given lines and mark the instance as read.

Parameters:

top_lines (Sequence[str] | None)

Return type:

Banner

write()[source]#

Render a banner line. Defaults the software field to PYSCAMT if missing.

Parameters:
Return type:

list[str]

Notes

The banner parser is intentionally liberal: it ignores leading whitespace, is case-insensitive on the WRITTEN BY marker, and preserves the raw text of the trailing note. It does not validate dates or enforce a specific date format.

Examples

>>> b = Banner().read([
...   '#WRITTEN BY GEOTOOLS: kb0-s001 10/06/95 RAW RECS'
... ])
>>> b.software, b.station_hint, b.date
('GEOTOOLS', 'kb0-s001', '10/06/95')
>>> Banner().write()[0].startswith('#WRITTEN BY PYSCAMT:')
True

See also

Head

Station / data-type / count header triple.

Info

Site information (>KEY=VALUE records).

Heads

Minimal container that includes a Banner.

References

classmethod from_file(j_fn, *, verbose=0)[source]#
Parameters:
Return type:

Banner

classmethod from_lines(lines, *, verbose=0)[source]#
Parameters:
Return type:

Banner

read(top_lines=None)[source]#
Parameters:

top_lines (Sequence[str] | None)

Return type:

Banner

write(*, new=True, include_origin=False)[source]#
Parameters:
Return type:

list[str]

property software: str | None[source]#
property date_parsed: datetime | None[source]#