pycsamt.jones.collection#

Classes

JCollection([items, verbose])

High-level collection of Jones J-format files.

JCollectionMixin()

Mixin that provides folder/glob expansion and robust parsing orchestration for Jones J-format collections.
class pycsamt.jones.collection.JCollectionMixin[source]#

Bases: JParseMixin

Mixin that provides folder/glob expansion and robust parsing orchestration for Jones J-format collections.

The mixin augments a stateful base (e.g., JCBBase) with helpers to normalize user input paths, expand folders and wildcards, deduplicate candidates, and parse items using a tolerant strategy.

Implementations typically use JFile as the per-item reader, but the mixin is agnostic to the concrete class as long as it exposes a compatible from_file constructor.

Notes

The design keeps discovery and parsing separate. First the mixin expands and filters path candidates; then the owning class decides how to instantiate items and how to record failures. This separation avoids tight coupling and keeps error handling clear.

The mixin favors permissive heuristics while still catching obvious mistakes (non-files, unreadable paths, extensions that are unlikely to be J-format, etc.).

Typical Methods#

from_paths(paths, *, strict=False, verbose=0)

Expand and parse paths into items. Returns the created items (usually a list).

_iter_paths(paths)

Yield pathlib.Path objects from strings or paths, ignoring duplicates.

_iter_j_files(paths, *, recursive=True)

Yield J-candidates by expanding folders and glob patterns (e.g., "*.j", "**/*.txt").

_is_j_candidate(path)

Light heuristic that recognizes J-format candidates.

Examples

Expand a folder and parse all candidates:

>>> mix = JCollectionMixin()
>>> # usually inherited together with JCBBase
>>> list(mix._iter_j_files(["data/j"]))[:1]
[PosixPath('...kb0-s001.txt')]

See also

JCBBase

Minimal stateful base for collections (stores items).

JCollection

High-level collection that mixes in this helper and provides user-facing APIs.

pycsamt.jones.j.JFile

High-level J reader used as default item type.

References

add_from(sources, *, recursive=True, strict=False, on_dup='replace', verbose=None)[source]#
Parameters:
Return type:

JCollectionMixin

select(stations)[source]#
Parameters:

stations (Sequence[str])

Return type:

JCollection

where(fn)[source]#
Parameters:

fn (Callable[[JFile], bool])

Return type:

JCollection

sort(key='station', *, reverse=False)[source]#
Parameters:
Return type:

JCollection

property paths: list[str][source]#
nf_stats()[source]#
Return type:

dict

class pycsamt.jones.collection.JCollection(items=None, *, verbose=0)[source]#

Bases: JCBBase, JCollectionMixin

High-level collection of Jones J-format files.

Combines JCBBase (state container) with JCollectionMixin (discovery/orchestration) to offer a convenient interface for batch loading, quick metadata browsing, and simple filtering over many J files.

The default per-item object is JFile, which exposes parsed headers (Heads) and data blocks (JBlocks) as well as MT objects (pycsamt.z.z.Z, pycsamt.z.tipper.Tipper, pycsamt.z.resphase.ResPhase) when available.

Parameters:

  • verbose (int, default 0) – Verbosity for logging and warnings during discovery and parsing.

  • items (Iterable[JFile] | None)

Variables:

  • items (list of JFile) – Parsed items in insertion order. The class follows Python’s container protocol (__len__, __iter__).

  • n (int) – Number of items in the collection (len(self)).

  • paths (list of Path) – Convenience view of the associated file paths.

  • stations (list of str) – Station codes when available on items (best-effort).

parse(paths, \*, strict=False, verbose=None)#

Expand paths (file, folder, glob), parse J files, and append items to the collection. Returns the new items.

where(**query)#

Optional, return a filtered view (e.g., by station or by component family has_Z/has_R/has_T).

summary()[source]#

Optional, return a compact text or dataframe summary.

Parameters:

fields (Sequence[str])

Return type:

list[dict]

write_index(path, \*, overwrite=True)#

Optional, serialize a CSV/TSV inventory for the collection.

Notes

The collection is intentionally lightweight. It does not enforce a database schema, and it avoids implicitly reading large arrays until needed. This makes it suitable for quick exploration and CI tests.

Error handling is conservative: unreadable paths or parse errors are usually skipped with a warning (unless strict=True is requested).

Examples

Parse a folder and browse basic metadata:

>>> col = JCollection(verbose=0)
>>> _ = col.parse(["data/j"])
>>> len(col) >= 1
True
>>> sorted(set(getattr(x, "site", None) for x in col))[:3]
[...]

Filter by station (if where is provided):

>>> sub = getattr(col, "where", lambda **k: col)(station="KB0001")
>>> len(sub) >= 1
True

See also

JCBBase

Underlying state container.

JCollectionMixin

Path expansion and tolerant orchestration.

pycsamt.jones.j.JFile

Per-item high-level J reader.

References

classmethod from_sources(sources, *, recursive=True, strict=False, on_dup='replace', verbose=0)[source]#
Parameters:
Return type:

JCollection

merge(other, *, on_dup='replace')[source]#
Parameters:
Return type:

JCollection

get(site, what, default=None)[source]#
Quick extractor. ‘what’ supports:

  • ‘freq’

  • ‘z’,’zxx’,’zxy’,’zyx’,’zyy’

  • ‘tip’,’tx’,’ty’

  • ‘rxy’,’ryx’,’rxx’,’ryy’ (rho)

  • ‘phixy’,’phiyx’,’phixx’,’phiyy’

  • ‘station’/’site’,’lat’,’lon’,’elev’,’az’,’name’

  • ‘path’,’filename’

Parameters:
Return type:

object | None

set(site, *, jfile=None, update=None)[source]#

Replace or mutate a site’s JFile.

  • If ‘jfile’ is given, replace the stored object.

  • Else apply ‘update’ keys on the existing object: ‘station’/’site’,’lat’,’lon’,’elev’,’az’, ‘freq’,’z’,’tip’,’resphase’

Parameters:
Return type:

JFile

adjust(site, *, dlat=None, dlon=None, lat=None, lon=None, elev=None, rename=None)[source]#

Shift or set position and/or rename station.

Parameters:
Return type:

JFile

summary(fields=('station', 'n_freq', 'has_z', 'has_r', 'has_t', 'lat', 'lon', 'az'))[source]#
Parameters:

fields (Sequence[str])

Return type:

list[dict]

property sites: list[str][source]#

Best-effort station names (one per item).

property latitude: ndarray[source]#

Vector of latitudes (np.nan for missing).

property longitude: ndarray[source]#

Vector of longitudes (np.nan for missing).

export(output_dir, *, file_pattern='{station}.j', export_summary=False, summary_filename='summary.csv', **jfile_write_kwargs)[source]#

Exports all JFile items to a directory with advanced options.

This method orchestrates the writing of each JFile in the collection to a specified directory, with flexible naming, error handling, and an optional summary CSV file.

Parameters:

  • output_dir (Pathish) – The path to the directory where files will be saved. It will be created if it does not exist.

  • file_pattern (str, default="{station}.j") – A format string for output filenames. Can use attributes of JFile like {station}, {name}, {site}.

  • export_summary (bool, default=False) – If True, a summary of the collection will also be saved as a CSV file in the output directory.

  • summary_filename (str, default="summary.csv") – The name of the summary file if export_summary is True.

  • **jfile_write_kwargs – Keyword arguments to be passed directly to each JFile.write() call (e.g., datatype=”ZRT”, overwrite=True).

Returns:

A dictionary with two keys: - ‘successful’: A list of paths to successfully written files. - ‘failed’: A list of tuples, where each tuple contains the

station name and the error that occurred.

Return type:

dict

fetch(site=None, lat=None, lon=None, tol=0.001, first=False, **kwargs)[source]#

Fetches JFile objects from the collection based on specified criteria.

This method provides a flexible way to search for J-format files by site name, geographic coordinates, or any other attribute of the JFile object or its nested Heads sections.

Parameters:

  • site (str, optional) – The site or station name to search for. The comparison is case-insensitive.

  • lat (float, optional) – The latitude to search for, in decimal degrees.

  • lon (float, optional) – The longitude to search for, in decimal degrees.

  • tol (float, default=0.001) – The tolerance in decimal degrees for geographic coordinate searches. A match is found if the absolute difference is within this tolerance.

  • first (bool, default=False) – If True, returns only the first matching JFile object found, or None if no match is found. If False, returns a list of all matching objects.

  • **kwargs (Any) – Additional keyword arguments to match against attributes of the JFile object or its nested Heads object (e.g., acqby=’Contractor’). The attribute name is case-insensitive.

Returns:

  • If first=True, returns the first matching JFile or None.

  • If first=False, returns a list of all matching JFile objects. An empty list is returned if no matches are found.

Return type:

JFile or list of JFile or None

Examples

>>> # Fetch a single site by its name
>>> jfile_obj = jcollection.fetch(site='S01', first=True)

>>> # Fetch all sites where the azimuth is 0
>>> zero_az_files = jcollection.fetch(azimuth=0)

>>> # Fetch all sites within a small geographic area
>>> area_files = jcollection.fetch(
...     lat=26.05,
...     lon=-10.33,
...     tol=0.1
... )