2.9.1.6. pycsamt.seg.heads#

Classes

`Head`([edi_header_list, verbose, logger])	EDI `>HEAD` block container.
`HeadMixin`()	Mixin that exposes `Head` helpers on a host class.
`Heads`([head, info, verbose, logger])	Convenience aggregator for `>HEAD` and `>INFO`.
`Info`([edi_info_list, verbose, logger, info_text])	EDI `>INFO` block container.
`InfoMixin`()	Mixin that exposes `Info` helpers on a host class.

class pycsamt.seg.heads.Head(edi_header_list=None, verbose=0, logger=None, **kwargs)[source]

Bases: EDIComponentBase

EDI >HEAD block container.

The Head class parses and serializes the header metadata of SEG-EDI files. It normalizes common variations in field names (for example LON → LONG) and supports latitude/longitude given either in decimal degrees or DMS strings (with or without cardinal letters).

Parameters:

edi_header_list (sequence of str, optional) – Raw lines that belong to the >HEAD section. If provided, they are parsed immediately via read().
**kwargs – Attribute overrides (for example dataid, acqby, coordsys). Unknown keys become dynamic attributes.
verbose (int)

Variables:

Location (Location) – Container for geographic coordinates. The Head.lat, Head.long and Head.elev properties delegate to this object.
fileby (dataid, acqby,) – Dataset identifier, acquisition contractor, and file author.
filedate (acqdate, enddate,) – Acquisition start/end dates and the file timestamp. filedate defaults to current UTC.
loc (country, state, county, prospect,) – Descriptive location metadata.
elev (lat, long,) – Coordinates as decimal degrees and elevation in the current Head.units. DMS inputs are converted to decimal when reading; writers emit DMS strings.
units ({'m', 'ft'}) – Elevation units (default 'm').
progdate (stdvers, progvers,) – EDI standard version, program version, and revision date. progvers defaults to pyCSAMT <version>.
coordsys (str) – Coordinate system description (default 'Geomagnetic North').
declination (float or None) – Geomagnetic declination in degrees.
datum (str) – Geodetic datum (default 'WGS84').
maxsect (int or None) – Maximum section count in file when present.
bindata (str or None) – Optional tag for external binary payload.
survey (project,) – Project and survey names if supplied.
empty (float) – Missing-value sentinel (default 1.0e32).
edi_header (list of str or None) – Normalized KEY=VALUE lines retained after parse.

Notes

Key names are normalized to lower case and stored in a canonical set (for example lon is exposed as Head.long).
Latitude and longitude accept DMS strings of the form 'DD:MM:SS' with optional decimals and optional cardinal letters. See pycsamt.gis.utils.
Writers quote some text fields to match common EDI formatting tools.

Examples

Read and access coordinates:

h = Head.from_file("E01.edi")
(h.lat, h.long, h.elev)

Create and serialize a header block:

h = Head(dataid="E1_2", acqby="ULTREM", units="m")
lines = h.write()
print("".join(lines))

See also

Info: Companion container for the >INFO block.
Heads: Aggregator that bundles Head and Info.
pycsamt.gis.utils.dms_to_decimal: Robust DMS → decimal converter.
pycsamt.gis.utils.decimal_to_dms: Decimal → DMS formatter.
pycsamt.seg.properties.IsEdi: File validator used by from_file().

References

[Head-1]

SEG MT/EMAP EDI specification (1987/2006). MTNet: https://www.mtnet.info/

head_keys: list[str] = ['dataid', 'acqby', 'fileby', 'acqdate', 'enddate', 'filedate', 'country', 'state', 'county', 'prospect', 'loc', 'lat', 'long', 'elev', 'chainage', 'declination', 'datum', 'units', 'stdvers', 'coordsys', 'progvers', 'progdate', 'maxsect', 'bindata', 'project', 'survey', 'empty']

property lat: float | None[source]

property long: float | None[source]

property lon: float | None[source]

property elev: float | None[source]

classmethod from_file(edi_fn)[source]

Extract and parse the >HEAD block from an EDI file path.

Parameters:: edi_fn (str | Path)
Return type:: Head

read(edi_header_list=None)[source]

Parse HEAD KV lines and set attributes.

Parameters:: edi_header_list (Sequence[str] | None)
Return type:: Head

write(head_list_infos=None, stamp=True)[source]

Build formatted >HEAD lines (including trailing blank line).

Parameters:

head_list_infos (Sequence[str] | None)
stamp (bool)

Return type:

list[str]

as_dict()[source]

Export known fields as a plain dict.

Return type:: dict

update(**kwargs)[source]

Update fields (accepts both known and unknown keys).

Return type:: Head

compute_chainage(origin, azimuth, *, set_attr=True)[source]

Compute chainage (meters) along a profile defined by an origin and azimuth, using a local flat metric.

Chainage is positive in the forward profile direction and negative behind the origin.

Parameters:

origin (tuple of float) – (lat0, lon0) in decimal degrees (WGS84 assumed).
azimuth (float) – Profile azimuth in degrees. North = 0, East = 90.
set_attr (bool, optional) – If True, store the computed value into self.chainage.

Returns:

Chainage in meters. Returns nan if coordinates are missing.

Return type:

float

class pycsamt.seg.heads.Info(edi_info_list=None, *, verbose=0, logger=None, info_text=None, **kwargs)[source]

Bases: EDIComponentBase

EDI >INFO block container.

The Info class collects survey-level metadata and processing provenance. It supports both classic KEY=VALUE blocks and spectra-style free-text INFO blocks. Non-KV lines are preserved in Info.info_text and are written back unmodified.

Parameters:

edi_info_list (sequence of str, optional) – Raw KEY=VALUE lines for the INFO block. If provided, they are parsed immediately via read(). Non-KV lines should be passed via Info.info_text or supplied through from_file().
verbose (int, optional) – Verbosity level forwarded to the base component.
logger (logging.Logger, optional) – Logger instance to use for diagnostics.
info_text (sequence of str, optional) – Free-text lines from spectra-style INFO blocks that should be preserved.
**kwargs – Attribute overrides; unknown keys are accepted.

Variables:

maxinfo (int) – Maximum number of textual entries (default 999).
Source (Source) – Survey provenance (project, survey, site name, and creation date).
Processing (Processing) – Processing meta-information (software, run list, sign convention, etc.).
Copyright (Copyright) – Optional copyright container.
filter (str or None) – Optional filter tag.
ediinfo (list of str) – Normalized KV lines retained after parse.
info_text (list of str) – Free-form text preserved and written back.

Notes

Known keys are routed into nested containers (for example processedby → Info.Processing).
If an INFO block contains no KV lines, parse is still successful; fields remain at defaults and Info.info_text carries the original text.

Examples

Parse INFO from file with mixed content:

i = Info.from_file("15125A_spe.edi")
i.Source.project
len(i.info_text)  # free-text lines preserved

Build and write a KV-only INFO block:

i = Info()
i.Source.project = "Demo"
i.Processing.processedby = "pyCSAMT"
print("".join(i.write()))

See also

Head: Header metadata companion.
Heads: Aggregator that bundles Head and Info.

pycsamt.seg.property.Source, pycsamt.seg.property.Processing, pycsamt.seg.property.Copyright

References

[Info-1]

SEG MT/EMAP EDI specification (1987/2006). MTNet: https://www.mtnet.info/

infokeys = ['maxinfo', 'project', 'survey', 'creationdate', 'processedby', 'processingsoftware', 'processingtag', 'sitename', 'runlist', 'remoteref', 'remotesite', 'signconvention']

ediinfo: list[str] | None

info_text: list[str]

filter: str | None

maxinfo: int

classmethod from_file(edi_fn)[source]

Extract and parse the >INFO block from an EDI file.

Works for both KV-style INFO and free-text INFO blocks.

Parameters:: edi_fn (str | Path)
Return type:: Info

read(edi_info_list=None)[source]

Parse an INFO key-value list and set attributes.

If there are no KEY=VALUE items (e.g., spectra-style free-text INFO), this method simply leaves metadata at defaults and returns without error. Any non-KV lines should be provided via info_text (from_file handles this).

Parameters:: edi_info_list (Sequence[str] | None)
Return type:: Info

write(edi_info_list=None)[source]

Build formatted >INFO lines ready to write to an EDI file.

If edi_info_list is provided, it is normalized and written.
Otherwise, current attributes are serialized in canonical order, followed by any preserved free-text lines stored in info_text.

Parameters:: edi_info_list (Sequence[str] | None)
Return type:: list[str]

as_dict()[source]

Flattened INFO dictionary (KV items only).

Return type:: dict

update(**kwargs)[source]

Update INFO fields (routes to nested containers where appropriate).

Return type:: Info

class pycsamt.seg.heads.Heads(head=None, info=None, verbose=0, logger=None)[source]

Bases: EDIComponentBase

Convenience aggregator for >HEAD and >INFO.

The Heads helper wraps a parsed Head and Info pair and provides simple I/O helpers to extract or write both blocks together. It is useful when a workflow wants to treat the top matter of an EDI file as a single unit.

Parameters:

head (Head, optional) – Parsed header. One will be created by from_file() when reading from disk.
info (Info, optional) – Parsed INFO. One will be created by from_file() when reading from disk.
verbose (int)

Variables:

head (Head) – Header container.
info (Info) – INFO container.

Notes

from_file() validates the input via IsEdi, then slices the two blocks and delegates to Head and Info.
write() serializes in canonical order (>HEAD first, then >INFO), preserving free-text INFO content when present.

Examples

Read both blocks at once and re-emit them:

hs = Heads.from_file("000CSA_csamt.edi")
lines = hs.write()
open("out.edi", "w", encoding="utf-8").writelines(lines)

Access nested objects directly:

hs.head.dataid, hs.info.Source.project

See also

Head, Info

pycsamt.seg.properties.IsEdi: Validator used at read time.

References

[Heads-1]

SEG MT/EMAP EDI specification (1987/2006). MTNet: https://www.mtnet.info/

head: Head

info: Info

classmethod from_file(edi_fn)[source]

Load >HEAD and >INFO from EDI path and return an aggregate container.

Parameters:: edi_fn (str | Path)
Return type:: Heads

read(text_or_lines)[source]

Parse >HEAD and >INFO from provided content (string or list of lines).

Parameters:: text_or_lines (str | Sequence[str])
Return type:: Heads

write()[source]

Serialize >HEAD + >INFO blocks back-to-back.

Return type:: list[str]

to_text()[source]

Return concatenated HEAD+INFO text.

Return type:: str

class pycsamt.seg.heads.HeadMixin[source]

Bases: object

Mixin that exposes Head helpers on a host class.

HeadMixin adds convenience constructors for reading the >HEAD block without forcing the host to inherit from Head directly. This is primarily used by higher-level SEG components that contain a header but are not themselves Head objects.

from_file(edi_fn)[source]

Return a new Head parsed from edi_fn.

Parameters:: edi_fn (str | Path)
Return type:: Head

read(lines)[source]

Shortcut to Head.read().

Parameters:: edi_header_list (Sequence[str] | None)
Return type:: Head

write(...)[source]

Shortcut to Head.write().

Parameters:: head_list_infos (Sequence[str] | None)
Return type:: list[str]

Notes

The mixin does not own any state; it simply forwards to Head.

Examples

Use the mixin inside a host container:

class Host(HeadMixin):
    pass

h = Host.from_file("E01.edi")
print(h.dataid)

See also

Head, InfoMixin

head: Head

classmethod from_file(edi_fn)[source]

Return a parsed Head instance from EDI path.

Parameters:: edi_fn (str | Path)
Return type:: Head

read(edi_header_list=None)[source]

Parse HEAD KV lines into self.head and return it.

Parameters:: edi_header_list (Sequence[str] | None)
Return type:: Head

write(head_list_infos=None)[source]

Serialize the host’s head as >HEAD lines.

Parameters:: head_list_infos (Sequence[str] | None)
Return type:: list[str]

class pycsamt.seg.heads.InfoMixin[source]

Bases: object

Mixin that exposes Info helpers on a host class.

InfoMixin adds convenience constructors for reading the >INFO block while keeping the host class focused on its domain logic. It forwards calls to Info and returns an Info instance.

from_file(edi_fn)[source]

Return a new Info parsed from edi_fn.

Parameters:: edi_fn (str | Path)
Return type:: Info

read(lines)[source]

Shortcut to Info.read().

Parameters:: edi_info_list (Sequence[str] | None)
Return type:: Info

write(...)[source]

Shortcut to Info.write().

Parameters:: edi_info_list (Sequence[str] | None)
Return type:: list[str]

Notes

Free-text INFO blocks (for example spectra-style RUN INFORMATION) are supported transparently by Info. The mixin needs no special handling.

Examples

Mix in the helpers:

class Host(InfoMixin):
    pass

info = Host.from_file("15125A_spe.edi")
len(info.info_text)  # preserved text lines

See also

Info, HeadMixin

info: Info

classmethod from_file(edi_fn)[source]

Return a parsed Info instance from EDI path.

Parameters:: edi_fn (str | Path)
Return type:: Info

read(edi_info_list=None)[source]

Parse INFO KV lines into self.info and return it.

Parameters:: edi_info_list (Sequence[str] | None)
Return type:: Info

write(edi_info_list=None)[source]

Serialize the host’s info as >INFO lines.

Parameters:: edi_info_list (Sequence[str] | None)
Return type:: list[str]