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

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

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

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

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

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

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