2.11.1.2. pycsamt.jones.blocks#

Classes

`JBlock`([head, rows, verbose])	Abstract base for J-format data blocks.
`JBlocks`([blocks, verbose])	Container for a sequence of parsed J data blocks.
`RBlock`([head, rows, verbose])	Resistivity/phase (R/S) block implementation.
`RRow`(period, rho, pha, rhomax, rhomin, ...)	One parsed resistivity/phase row of a J R/S block.
`TFBlock`([head, rows, verbose])	Transfer-function (Z/Q/C/T) block implementation.
`TFRow`(period, real, imag, error, weight[, rej])	One parsed transfer-function row of a J Z/Q/C/T block.

class pycsamt.jones.blocks.RRow(period, rho, pha, rhomax, rhomin, phamax, phamin, wrho, wpha, rej=False)[source]

Bases: object

One parsed resistivity/phase row of a J R/S block.

The row stores period (s), apparent resistivity (Ω·m), phase (deg), their 1σ bounds, and per-column weights. A derived boolean flag rej marks a row as rejected according to the J-format rules.

Parameters:

period (float) – Period in seconds. If input stored frequency (Hz) as a negative number, it is normalized to a positive period.
rho (float) – Apparent resistivity. Values < 0 mark the estimate as rejected.
pha (float) – Phase in degrees.
rhomax (float) – Upper and lower 1σ bounds of resistivity. May be missing.
rhomin (float) – Upper and lower 1σ bounds of resistivity. May be missing.
phamax (float) – Upper and lower 1σ bounds of phase. May be missing.
phamin (float) – Upper and lower 1σ bounds of phase. May be missing.
wrho (float) – Weights. A negative weight marks the estimate as rejected.
wpha (float) – Weights. A negative weight marks the estimate as rejected.
rej (bool) – Convenience rejection flag derived from the rules above.

Notes

Missing numeric values are often written as -999.0 in J files. The higher-level APIs convert them to NaN for numeric workflows.

Examples

>>> row = RRow(
...     period=1.0, rho=100.0, pha=45.0,
...     rhomax=110.0, rhomin=90.0,
...     phamax=50.0, phamin=40.0,
...     wrho=1.0, wpha=1.0, rej=False,
... )
>>> row.rho, row.rej
(100.0, False)

See also

RBlock: Sequence of RRow with I/O helpers.
TFRow: Row model for transfer-function blocks.

References

[RRow-1]

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

period: float

rho: float

pha: float

rhomax: float

rhomin: float

phamax: float

phamin: float

wrho: float

wpha: float

rej: bool = False

class pycsamt.jones.blocks.TFRow(period, real, imag, error, weight, rej=False)[source]

Bases: object

One parsed transfer-function row of a J Z/Q/C/T block.

The row stores period (s), real/imag parts, a standard error, a row weight, and a derived rej flag based on J-format rules.

Parameters:

period (float) – Period in seconds. If input stored frequency (Hz) as a negative number, it is normalized to a positive period.
real (float) – Real and imaginary parts of the transfer function.
imag (float) – Real and imaginary parts of the transfer function.
error (float) – Standard error (format-specific). May be missing.
weight (float) – Row weight. Negative values mark the row as rejected.
rej (bool) – Convenience rejection flag derived from the rules above.

Notes

The J specification allows several TF families (Z/Q/C/T). The row schema stays the same; only the physical meaning differs.

Examples

>>> tf = TFRow(
...     period=0.1, real=1.0, imag=-2.0,
...     error=0.1, weight=1.0, rej=False,
... )
>>> tf.period, tf.rej
(0.1, False)

See also

TFBlock: Sequence of TFRow with I/O helpers.
RRow: Row model for resistivity/phase blocks.

References

[TFRow-1]

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

period: float

real: float

imag: float

error: float

weight: float

rej: bool = False

class pycsamt.jones.blocks.JBlock(head=None, *, rows=None, verbose=0)[source]

Bases: JComponentBase

Abstract base for J-format data blocks.

A block ties a parsed header (Head) to a homogeneous sequence of rows (RRow or TFRow). Subclasses implement the row parser, normalization, serialization, and simple QA summaries.

Parameters:

head (Head) – Parsed header triple (station, data-type, count).
rows (sequence of rows) – Concrete row records for this block family.
verbose (int, optional) – Verbosity for warnings during parsing and writing.

Variables:

head (Head) – Block header with station, kind, comp, n.
nrows (int) – Number of parsed data rows.
units (station, kind, comp,) – Convenience views onto head.dtype.
columns (tuple of str) – Column names for the structured numeric view.
shape ((int, int)) – (nrows, ncols) derived from the current rows.

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

Build a block from a file slice. The concrete subclass is chosen from the header’s kind.

Parameters:

j_fn (str | Path)
verbose (int)

Return type:

JBlock

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

Parse from in-memory lines (header + body).

Parameters:

lines (Sequence[str])
verbose (int)

Return type:

JBlock

read((head, body_lines))[source]

Populate the block from an existing Head and the subsequent body lines. Marks the instance as read.

Parameters:: data (tuple[Head, Sequence[str]] | None)
Return type:: JBlock

write()[source]

Serialize header and all body rows into text.

Return type:: list[str]

to_numpy()[source]

Structured array view with numeric normalization (period sign, missing sentinels, rejection flags).

Return type:: dict[str, ndarray]

to_dataframe()[source]: Optional pandas representation (if available).

qa_summary()[source]

Small dict of quick QA metrics for this block.

Return type:: dict[str, Any]

Notes

The base class is intentionally minimal to keep the parser light. Subclasses define the row regex, column names, and row-level normalization logic.

Examples

>>> # Pseudocode; subclass chosen from header
>>> blk = JBlock.from_lines(["S01", "RXY", "1", "..."])
>>> blk.station, blk.nrows
('S01', 1)

See also

RBlock, TFBlock

Heads: Header-only convenience container.

References

[JBlock-1]

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

head: Head | None

rows: list[Any]

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

Parameters:

j_fn (str | Path)
verbose (int)

Return type:

JBlock

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

Parameters:

lines (Sequence[str])
verbose (int)

Return type:

JBlock

read(data=None)[source]

Parameters:: data (tuple[Head, Sequence[str]] | None)
Return type:: JBlock

write()[source]

Return type:: list[str]

normalize()[source]

Apply row-level normalization:

negative period => frequency (Hz) to period (s)
missing sentinel (-999) => NaN
set rejection flags per rules

Return type:: JBlock

qa_summary()[source]

Quick QA metrics (counts and basic stats).

Return type:: dict[str, Any]

to_numpy()[source]

Return type:: dict[str, ndarray]

to_dataframe()[source]

property nrows: int[source]

property station: str | None[source]

property kind: str | None[source]

property comp: str | None[source]

property units: str | None[source]

property has_units: bool[source]

property columns: tuple[str, ...][source]

property shape: tuple[int, int][source]

property periods[source]

class pycsamt.jones.blocks.RBlock(head=None, *, rows=None, verbose=0)[source]

Bases: JBlock

Resistivity/phase (R/S) block implementation.

Parses rows of the form period rho pha rhomax rhomin phamax phamin wrho wpha. Applies J-format rules to normalize period sign and to mark rejected estimates.

Parameters:

head (Head) – Header whose kind is 'R' or 'S'. The component encodes the tensor entry or average (e.g. RXY, RDE).
rows (sequence of RRow, optional) – Prebuilt rows. Usually left to the parser.
verbose (int, optional) – Verbosity for warnings during parsing.

Variables:

columns (tuple of str) – ('period', 'rho', 'pha', 'rhomax', 'rhomin', 'phamax', 'phamin', 'wrho', 'wpha', 'rej').

Notes

Normalization rules:

If input period is negative, the value stores frequency in Hz and is converted to period (s).
rho < 0 or wrho < 0 marks the row as rejected.
-999.0 sentinels are converted to NaN in numeric views.

Examples

>>> lines = [
...     "S01",
...     "RXY",
...     "2",
...     "-1.0 100 45 110 90 50 40 1 1",
...     " 2.0 -5  30  35 25 40 20 1 1",
... ]
>>> blk = RBlock.from_lines(lines)
>>> a = blk.to_numpy()
>>> a["period"][0]  # 1/Hz -> s
1.0
>>> a["rej"][1]  # rho < 0
True

See also

TFBlock: Transfer-function block family.
RRow: Single row record used by this block.

References

[RBlock-1]

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

read(data=None)[source]

Parameters:: data (tuple[Head, Sequence[str]] | None)
Return type:: RBlock

normalize()[source]

Apply row-level normalization:

negative period => frequency (Hz) to period (s)
missing sentinel (-999) => NaN
set rejection flags per rules

Return type:: RBlock

to_numpy()[source]

Return type:: dict[str, ndarray]

qa_summary()[source]

Quick QA metrics (counts and basic stats).

Return type:: dict[str, Any]

write()[source]

Return type:: list[str]

property columns: tuple[str, ...][source]

class pycsamt.jones.blocks.TFBlock(head=None, *, rows=None, verbose=0)[source]

Bases: JBlock

Transfer-function (Z/Q/C/T) block implementation.

Parses rows of the form period real imag error weight. Applies J-format rules to normalize period sign and to mark rejected estimates.

Parameters:

head (Head) – Header whose kind is one of 'Z', 'Q', 'C', or 'T'.
rows (sequence of TFRow, optional) – Prebuilt rows. Usually left to the parser.
verbose (int, optional) – Verbosity for warnings during parsing.

Variables:

columns (tuple of str) – ('period', 'real', 'imag', 'error', 'weight', 'rej').

Notes

Normalization rules:

If input period is negative, the value stores frequency in Hz and is converted to period (s).
weight < 0 marks the row as rejected.
-999.0 sentinels are converted to NaN in numeric views.

Examples

>>> lines = [
...     "S02",
...     "ZXY SI",
...     "2",
...     "-1.0e+1 1.0 -2.0 0.1 1.0",
...     " 5.0    -999 3.0 -999 -1.0",
... ]
>>> blk = TFBlock.from_lines(lines)
>>> a = blk.to_numpy()
>>> round(a["period"][0], 3)
0.1
>>> a["rej"][1]  # weight < 0
True

See also

RBlock: Resistivity/phase block family.
TFRow: Single row record used by this block.

References

[TFBlock-1]

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

read(data=None)[source]

Parameters:: data (tuple[Head, Sequence[str]] | None)
Return type:: TFBlock

normalize()[source]

Apply row-level normalization:

negative period => frequency (Hz) to period (s)
missing sentinel (-999) => NaN
set rejection flags per rules

Return type:: TFBlock

to_numpy()[source]

Return type:: dict[str, ndarray]

qa_summary()[source]

Quick QA metrics (counts and basic stats).

Return type:: dict[str, Any]

write()[source]

Return type:: list[str]

property columns: tuple[str, ...][source]

class pycsamt.jones.blocks.JBlocks(blocks=None, *, verbose=0)[source]

Bases: JComponentBase

Container for a sequence of parsed J data blocks.

Provides discovery from raw text, iteration, selection by family or component, serialization, and quick QA roll-ups across blocks.

Parameters:

blocks (sequence of JBlock, optional) – Prebuilt blocks. Usually created by the parser.
verbose (int, optional) – Verbosity for warnings during parsing.

Variables:

blocks (list of JBlock) – Parsed blocks in file order.
n (int) – Number of blocks.
stations (list of str) – All station identifiers seen across blocks.
kinds (list of str) – The kind tokens across all blocks (e.g. 'R', 'Z').

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

Parse all blocks found in a file.

Parameters:

j_fn (str | Path)
verbose (int)

Return type:

JBlocks

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

Parse blocks from an in-memory sequence of lines.

Parameters:

lines (Sequence[str])
verbose (int)

Return type:

JBlocks

read(lines)[source]

Replace current content with blocks parsed from lines.

Parameters:: lines (Sequence[str] | None)
Return type:: JBlocks

write()[source]

Serialize every block back to text.

Return type:: list[str]

select(kind=None, comp=None)[source]

Return blocks filtered by family and/or component.

Parameters:

kind (str | None)
comp (str | None)

Return type:

list[JBlock]

period_range()[source]

Global period min/max across blocks (ignores NaN).

Return type:: tuple[float, float] | None

qa_summary()[source]

List of QA dicts, one per block.

Return type:: list[dict[str, Any]]

Notes

Header discovery is tolerant to real-world quirks, including optional azimuth on the station line and the count-before-dtype pattern seen in some files.

Examples

>>> col = JBlocks.from_file("data/j/kb0-s001.txt")
>>> col.n >= 1
True
>>> [b.station for b in col.select(kind="R")]
['KB0001', ...]

See also

Head, Heads, RBlock, TFBlock

References

[JBlocks-1]

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

blocks: list[JBlock]

property n: int[source]

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

Parameters:

j_fn (str | Path)
verbose (int)

Return type:

JBlocks

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

Parameters:

lines (Sequence[str])
verbose (int)

Return type:

JBlocks

read(lines=None)[source]

Parameters:: lines (Sequence[str] | None)
Return type:: JBlocks

write()[source]

Return type:: list[str]

to_numpy()[source]

Return type:: list[dict[str, ndarray]]

to_dataframe()[source]

qa_summary()[source]

Return type:: list[dict[str, Any]]

property stations: list[str][source]

property station: str | None[source]: Return the single, unique station name for the block collection. Returns None if no blocks are present.

property kinds: list[str][source]

select(*, kind=None, comp=None)[source]

Parameters:

kind (str | None)
comp (str | None)

Return type:

list[JBlock]

period_range()[source]

Return type:: tuple[float, float] | None