2.30. pycsamt.map#

Code-first station, profile, and 3-D mapping tools for pyCSAMT.

The pycsamt.map package is the reusable mapping layer for scripts, notebooks, and applications. It accepts the same survey inputs as pycsamt.emtools._core.ensure_sites(): an EDI directory, one or more EDI files, EDI-like objects, or a pycsamt.site.Sites container. For multi-line surveys, use pycsamt.map.load_lines() or pycsamt.map.MapView.

2.30.1. Quick Use#

Function-style use is compact and works well in notebooks.

from pycsamt.map import (
    ProfileMapOptions,
    StationMapOptions,
    VolumeMapOptions,
    plot_pseudosection,
    plot_station_map,
    plot_volume_map,
)

line = "data/AMT/WILLY_DATA/L18PLT"

station_fig = plot_station_map(
    line,
    options=StationMapOptions(
        overlay="rho",
        frequency=10.0,
        component="xy",
        frequency_tolerance=2.0,
    ),
)

pseudo_fig = plot_pseudosection(
    line,
    options=ProfileMapOptions(
        quantity="phase",
        components=("xy", "yx"),
        x_axis="distance",
    ),
)

volume_fig = plot_volume_map(
    line,
    options=VolumeMapOptions(
        mode="fence",
        component="xy",
        depth_range=(0.0, 2000.0),
    ),
)

2.30.2. Builder API#

Builder classes keep one normalized survey in memory and let you create variants without reloading the EDI data.

from pycsamt.map import ProfileMap, StationMap, VolumeMap

station = (
    StationMap("data/AMT/WILLY_DATA/L18PLT")
    .with_overlay("skin_depth", frequency=10.0)
    .with_options(show_labels=False)
    .figure()
)

profile = (
    ProfileMap("data/AMT/WILLY_DATA/L18PLT")
    .with_quantity("rho")
    .with_components("xy", "yx")
    .pseudosection()
)

volume = (
    VolumeMap("data/AMT/WILLY_DATA/L18PLT")
    .with_mode("surface")
    .with_quantity("phase")
    .figure()
)

2.30.3. MapView#

pycsamt.map.MapView is a session facade for code users who want the same survey to drive station, profile, and 3-D views.

from pycsamt.map import MapView

mv = MapView.from_folder(
    "data/AMT/WILLY_DATA",
    detect="folder",
)

station = mv.station(overlay="elevation")
pseudo = mv.pseudosection(component="xy")
fence = mv.map3d(mode="fence", depth_range=(0.0, 2000.0))

2.30.4. Export#

Use pycsamt.map.export_figure() for format-aware export, or the direct helpers for explicit output types.

from pycsamt.map import ExportOptions, export_figure

export_figure(
    station,
    ExportOptions(path="station.html"),
)

export_figure(
    fence,
    ExportOptions(path="fence", format="html"),
)

2.30.5. Scientific Note#

The 3-D map modes in pycsamt.map are quick-look visualizations. Fence, block, depth-slice, and isosurface views use pseudo-depth grids derived from apparent resistivity and period. They are useful for inspection and communication, but they are not a replacement for a constrained 2-D or 3-D inversion model.

2.30.6. Public API#

Code-first mapping API for pyCSAMT surveys.

This package provides reusable station, profile, and 3-D map builders for scripts, notebooks, and applications.

Functions accept the same flexible inputs used by pycsamt.emtools.ensure_sites: an EDI path, a directory, an iterable of EDI-like objects, or a Sites instance.

class pycsamt.map.BasemapConfig(style, center, zoom, bearing=0.0, layers=())#

Bases: object

Plotly geographic map layout settings.

Parameters:
style: str#
center: dict[str, float]#
zoom: int#
bearing: float = 0.0#
layers: tuple = ()#
class pycsamt.map.ComponentSpec(name, indices=None, mode='tensor')#

Bases: object

Parsed impedance component request.

Parameters:
name: str#
indices: tuple[int, int] | None = None#
mode: str = 'tensor'#
class pycsamt.map.CRSConfig(source, target=4326, always_xy=True)#

Bases: object

Coordinate transform settings.

Parameters:
source: int | str#
target: int | str = 4326#
always_xy: bool = True#
pycsamt.map.basemap_style_and_layers(style, *, dark=False)#

Resolve a style name into a (base style, raster layers) pair.

ESRI styles are rendered as white-bg + a raster tile layer; native Plotly styles are returned as-is with no layers.

Parameters:
Return type:

tuple[str, list]

pycsamt.map.build_geo_contour_image(lons, lats, values, *, cmap='jet', n_levels=12, opacity=0.6, mode='filled+lines', log_scale=False, grid_res=160, expand=0.06, interp='cubic', smooth_sigma=0.0, vmin=None, vmax=None)#

Render a Surfer-style filled-contour PNG for a basemap image layer.

Interpolates sparse station values onto a regular lon/lat grid and rasterises filled (and/or line) contours to a transparent PNG. The result is meant to be added to a Plotly map as an image layer.

Returns:

{"image": "data:image/png;base64,...", "coordinates": [...], "vmin": float, "vmax": float} (coordinates are the TL, TR, BR, BL [lon, lat] corners), or None when it cannot be built.

Return type:

dict | None

Parameters:
class pycsamt.map.ExportOptions(path, format=None, width=None, height=None, scale=2.0, include_plotlyjs='cdn')#

Bases: object

Options used by figure export helpers.

Parameters:
path: str | Path#
format: str | None = None#
width: int | None = None#
height: int | None = None#
scale: float = 2.0#
include_plotlyjs: str | bool = 'cdn'#
class pycsamt.map.FrequencySelection(requested, actual, index, delta, relative_delta, within_tolerance=True)#

Bases: object

Nearest-frequency selection metadata.

Parameters:
requested: float | None#
actual: float#
index: int#
delta: float#
relative_delta: float#
within_tolerance: bool = True#
class pycsamt.map.FrequencyValue(station, value, selection)#

Bases: object

Station value and selected-frequency metadata.

Parameters:
station: str#
value: float#
selection: FrequencySelection#
class pycsamt.map.Map3D(data, *, options=None, **ensure_kwargs)#

Bases: object

Builder object for 3-D survey maps.

Parameters:
with_mode(mode)#

Return a copy with another 3-D mode.

Parameters:

mode (str)

Return type:

Map3D

with_options(**kwargs)#

Return a copy with updated options.

Parameters:

kwargs (Any)

Return type:

Map3D

with_quantity(quantity)#

Return a copy using another mapped quantity.

Parameters:

quantity (str)

Return type:

Map3D

with_component(component)#

Return a copy using another component.

Parameters:

component (str)

Return type:

Map3D

figure()#

Build and return the 3-D map figure.

Return type:

Any

class pycsamt.map.MapData(sites, stations=(), profiles=(), metadata=<factory>)#

Bases: object

Normalized survey data shared by map renderers.

Parameters:
sites: Any#
stations: tuple[StationRecord, ...] = ()#
profiles: tuple[ProfileLine, ...] = ()#
metadata: dict[str, Any]#
property station_ids: tuple[str, ...]#

Return normalized station IDs.

property lines: tuple[str, ...]#

Return available profile/line names.

property has_geo: bool#

Whether stations have finite map coordinates.

iter_edis()#

Return EDI-like source objects.

Return type:

tuple[Any, …]

class pycsamt.map.MapView(data, *, theme='light', backend='plotly')#

Bases: object

A code-first session bound to one (multi-line) survey.

Parameters:

  • data (Any)

  • theme (str)

  • backend (str)

classmethod from_folder(path, *, detect='folder', recursive=True, theme='light', backend='plotly', **load_kwargs)#

Build a view from a directory of one or more lines.

Parameters:
Return type:

MapView

classmethod from_lines(lines, *, theme='light', backend='plotly', **load_kwargs)#

Build a view from an explicit {line: source} mapping.

Parameters:
Return type:

MapView

classmethod from_inversion_results(folder, *, known_stations=None, fetch_elevation=True, theme='light', backend='plotly', verbose=0)#

Build a view from a ModEM 3-D inversion result folder.

See pycsamt.map.inversion.load_modem_lines(). Pass known_stations=existing_view.data.stations to geo-reference and group ModEM stations using a previously-loaded EDI survey. Pass fetch_elevation=False to skip the best-effort online elevation lookup (e.g. offline use, or large surveys where the extra round-trip isn’t wanted).

Parameters:
Return type:

MapView

classmethod from_pcsf(path, *, known_stations=None, fetch_elevation=True, theme='light', backend='plotly', mesh_z_samples=60)#

Build a view from a backend-neutral .pcsf/.pcsm/ .pcsm.gz file.

See pycsamt.map.inversion.load_pcsf_lines(). Works with a file in either PCSF encoding (binary .pcsf or its lossless ASCII sibling, .pcsm/gzip-compressed .pcsm.gz — see pycsamt/format/SPEC.md S9) with any of the four geometry kinds — grid2d, multiline, native grid3d (e.g. ModEM 3-D), or mesh_unstructured (e.g. MARE2DEM, sampled by point-location on its real triangulation, see mesh_z_samples) — pass known_stations=existing_view.data.stations to geo-reference it against a previously-loaded EDI survey, the same as from_inversion_results().

Parameters:
Return type:

MapView

property lines: tuple[str, ...]#

Return the profile/line names in this survey.

property stations: tuple[str, ...]#

Return the station IDs in this survey.

property n_stations: int#

Return the number of stations across all lines.

property has_geo: bool#

Whether stations carry finite map coordinates.

table()#

Return survey stations as a pandas.DataFrame.

with_elevations(elev_map)#

Return a copy with station elevations overridden by elev_map.

Parameters:

elev_map (dict[str, float])

Return type:

MapView

fetch_elevations(*, api_name='open_meteo')#

Fetch station elevations online (see pycsamt.map.fetch_elevations()).

Parameters:

api_name (str)

Return type:

dict[str, float]

export_topography(path, *, fmt=None)#

Export this survey’s station id/elevation/coordinates.

Useful for an EDI-sourced view: a ModEM (or Occam2D/MARE2DEM) inversion result carries no real elevation of its own, so exporting it here produces a small, portable file that can be re-applied later — even in a session that never reloads these EDIs — via the “Upload file” elevation source (see pycsamt.map.topo.export_elevations()).

Parameters:
station(*, options=None, **overrides)#

Build a 2-D station map figure.

Parameters:
Return type:

Any

profile(*, options=None, **overrides)#

Build a profile-view figure.

Parameters:
Return type:

Any

pseudosection(*, options=None, **overrides)#

Build a resistivity/phase pseudosection figure.

Parameters:
Return type:

Any

map3d(*, mode='fence', options=None, **overrides)#

Build a 3-D fence/block/depth/surface figure.

Parameters:
Return type:

Any

figure(view='station', **overrides)#

Build a figure for view by name.

Parameters:

  • view ({"station", "profile", "pseudosection", "map3d"}) – Which renderer to call.

  • **overrides – Forwarded to the matching renderer.

Return type:

Any

export(path, *, view='station', fmt=None, scale=2.0, width=None, height=None, **overrides)#

Render view and write it to path.

The format is inferred from the suffix unless fmt is given; .html, .png, .json and Plotly static images are supported (see pycsamt.map.export_figure()).

Parameters:
Return type:

Path

export_all(directory, *, fmt='html', views=('station', 'pseudosection', 'map3d'), **overrides)#

Export several views into directory, keyed by view name.

Parameters:
Return type:

dict[str, Path]

launch(**kwargs)#

Open this survey in the map-view platform.

Requires the optional Dash GUI extra (pycsamt.app.mapview).

Parameters:

kwargs (Any)

Return type:

None

class pycsamt.map.ProfileLine(name, stations=())#

Bases: object

A named sequence of stations in one profile.

Parameters:
name: str#
stations: tuple[StationRecord, ...] = ()#
class pycsamt.map.ProfileMap(data, *, options=None, **ensure_kwargs)#

Bases: object

Builder object for profile maps.

Parameters:
with_options(**kwargs)#

Return a copy with updated options.

Parameters:

kwargs (Any)

Return type:

ProfileMap

with_quantity(quantity)#

Return a copy using another mapped quantity.

Parameters:

quantity (str)

Return type:

ProfileMap

with_component(component)#

Return a copy using one impedance component.

Parameters:

component (str)

Return type:

ProfileMap

with_components(*components)#

Return a copy using multiple components.

Parameters:

components (str)

Return type:

ProfileMap

figure()#

Build and return the profile figure.

Return type:

Any

pseudosection()#

Build and return the pseudosection figure.

Return type:

Any

class pycsamt.map.ProfileMapOptions(quantity='rho', component='xy', components=('xy', 'yx'), theme='light', backend='plotly', period_range=None, phase_range=None, value_range=None, x_axis='station', log_rho=True, height_per_panel=260, show_errbar=False, cmap=None, by_line=False, line_cols=None)#

Bases: object

Options for pseudosection and profile-view maps.

Parameters:
quantity: str = 'rho'#
component: str = 'xy'#
components: tuple[str, ...] = ('xy', 'yx')#
theme: Literal['light', 'dark', 'publication'] = 'light'#
backend: Literal['plotly', 'matplotlib'] = 'plotly'#
period_range: tuple[float, float] | None = None#
phase_range: tuple[float, float] | None = None#
value_range: tuple[float, float] | None = None#
x_axis: Literal['station', 'distance'] = 'station'#
log_rho: bool = True#
height_per_panel: int = 260#
show_errbar: bool = False#
cmap: str | None = None#
by_line: bool = False#
line_cols: int | None = None#
class pycsamt.map.StationMap(data, *, options=None, **ensure_kwargs)#

Bases: object

Builder object for station-map figures.

Parameters:
with_overlay(overlay, **kwargs)#

Return a copy with a different overlay.

Parameters:
Return type:

StationMap

with_options(**kwargs)#

Return a copy with updated options.

Parameters:

kwargs (Any)

Return type:

StationMap

figure()#

Build and return the station-map figure.

Return type:

Any

class pycsamt.map.StationMapOptions(overlay='index', frequency=None, frequency_tolerance=None, depth=None, show_markers=True, component='xy', theme='light', backend='plotly', selected_id=None, line_filter=None, marker_size=10, basemap=None, cmap='plasma', value_range=None, log_color=False, opacity=0.92, show_labels=True, label_fontsize=8.0, label_rotation=0.0, show_profiles=True, elevation_mode='markers', show_contours=False, contour_image=False, contour_mode='filled+lines', contour_levels=12, contour_opacity=0.55, contour_interp='linear', contour_smooth=1.0, contour_grid_res=150, bearing=0.0, title='')#

Bases: object

Options for 2-D station maps.

Parameters:

  • overlay (str)

  • frequency (float | None)

  • frequency_tolerance (float | None)

  • depth (float | None)

  • show_markers (bool)

  • component (str)

  • theme (Literal['light', 'dark', 'publication'])

  • backend (Literal['plotly', 'matplotlib'])

  • selected_id (str | None)

  • line_filter (tuple[str, ...] | None)

  • marker_size (int)

  • basemap (str | None)

  • cmap (str)

  • value_range (tuple[float, float] | None)

  • log_color (bool)

  • opacity (float)

  • show_labels (bool)

  • label_fontsize (float)

  • label_rotation (float)

  • show_profiles (bool)

  • elevation_mode (Literal['markers', 'contours'])

  • show_contours (bool)

  • contour_image (bool)

  • contour_mode (str)

  • contour_levels (int)

  • contour_opacity (float)

  • contour_interp (str)

  • contour_smooth (float)

  • contour_grid_res (int)

  • bearing (float)

  • title (str)

overlay: str = 'index'#
frequency: float | None = None#
frequency_tolerance: float | None = None#
depth: float | None = None#
show_markers: bool = True#
component: str = 'xy'#
theme: Literal['light', 'dark', 'publication'] = 'light'#
backend: Literal['plotly', 'matplotlib'] = 'plotly'#
selected_id: str | None = None#
line_filter: tuple[str, ...] | None = None#
marker_size: int = 10#
basemap: str | None = None#
cmap: str = 'plasma'#
value_range: tuple[float, float] | None = None#
log_color: bool = False#
opacity: float = 0.92#
show_labels: bool = True#
label_fontsize: float = 8.0#
label_rotation: float = 0.0#
show_profiles: bool = True#
elevation_mode: Literal['markers', 'contours'] = 'markers'#
show_contours: bool = False#
contour_image: bool = False#
contour_mode: str = 'filled+lines'#
contour_levels: int = 12#
contour_opacity: float = 0.55#
contour_interp: str = 'linear'#
contour_smooth: float = 1.0#
contour_grid_res: int = 150#
bearing: float = 0.0#
title: str = ''#
class pycsamt.map.StationRecord(id, latitude=None, longitude=None, elevation=None, line=None, index=0, source=None)#

Bases: object

A normalized station row used by map renderers.

Parameters:
id: str#
latitude: float | None = None#
longitude: float | None = None#
elevation: float | None = None#
line: str | None = None#
index: int = 0#
source: Any = None#
class pycsamt.map.VolumeMapOptions(mode='fence', quantity='resistivity', component='xy', theme='light', cmap='RdYlBu_r', depth_range=None, period_range=None, rho_range=None, iso_range=None, value_range=None, log_color=True, opacity=0.85, show_contours=False, show_labels=True, n_slices=5, surface_count=12, line_spacing=1.0, azimuth=0.0, topography=True, show_terrain=True, terrain_opacity=0.7, show_stations=False, station_symbol='diamond', station_size=4, station_color='#1f2937', station_labels=False, station_label_angle=0.0, station_label_fraction=1.0, station_label_names=None, max_stations=None, aspectmode='data', x_unit='m', depth_unit='m', smooth_sections=True, section_res=100, volume_smoothing=0.0, title='')#

Bases: object

Options for 3-D fence, block, and depth-slice maps.

Parameters:
mode: Literal['fence', 'block', 'depth', 'surface'] = 'fence'#
quantity: str = 'resistivity'#
component: str = 'xy'#
theme: Literal['light', 'dark', 'publication'] = 'light'#
cmap: str = 'RdYlBu_r'#
depth_range: tuple[float, float] | None = None#
period_range: tuple[float, float] | None = None#
rho_range: tuple[float, float] | None = None#
iso_range: tuple[float, float] | None = None#
value_range: tuple[float, float] | None = None#
log_color: bool = True#
opacity: float = 0.85#
show_contours: bool = False#
show_labels: bool = True#
n_slices: int = 5#
surface_count: int = 12#
line_spacing: float = 1.0#
azimuth: float = 0.0#
topography: bool = True#
show_terrain: bool = True#
terrain_opacity: float = 0.7#
show_stations: bool = False#
station_symbol: str = 'diamond'#
station_size: int = 4#
station_color: str = '#1f2937'#
station_labels: bool = False#
station_label_angle: float = 0.0#
station_label_fraction: float = 1.0#
station_label_names: tuple[str, ...] | None = None#
max_stations: int | None = None#
aspectmode: str = 'data'#
x_unit: str = 'm'#
depth_unit: str = 'm'#
smooth_sections: bool = True#
section_res: int = 100#
volume_smoothing: float = 0.0#
title: str = ''#
pycsamt.map.VolumeMap#

alias of Map3D

pycsamt.map.apply_elevations(data, elev_map)#

Return a copy of data with station elevations overridden.

Parameters:

  • data (MapData) – Source survey data.

  • elev_map (dict[str, float]) – Mapping of station_id -> elevation (m). Stations not present keep their existing elevation.

Return type:

MapData

pycsamt.map.build_3d_map(data, options)#

Build the concrete 3-D figure.

Parameters:
Return type:

Any

pycsamt.map.build_basemap_layout(lon, lat, *, dark=False, style=None, bearing=0.0)#

Return layout settings for geographic station maps.

Parameters:
Return type:

BasemapConfig

pycsamt.map.build_contour_overlay(x, y, values, *, levels=12, cmap='Viridis', opacity=0.65, grid_size=80, mode='lines')#

Build an interpolated map contour overlay.

Returns a Plotly Contour trace on a regular grid.

Parameters:
Return type:

Any

pycsamt.map.build_profile_line_overlay(x, y, *, geo=False, name='Profile', color='#2563eb', width=2.0)#

Build a reusable profile-line overlay trace.

Parameters:
Return type:

Any

pycsamt.map.build_profile_map(data, options)#

Build the concrete profile-view figure.

Parameters:
Return type:

Any

pycsamt.map.build_pseudosection(data, options)#

Build the concrete pseudosection figure.

Parameters:
Return type:

Any

pycsamt.map.build_station_map(data, options=None)#

Build a Plotly 2-D station map.

Parameters:
Return type:

Any

pycsamt.map.build_station_label_overlay(x, y, labels, *, geo=False, name='Station labels', color='#111827')#

Build a reusable station-label overlay trace.

Parameters:
Return type:

Any

pycsamt.map.build_topography_overlay(x, y, elevation, *, opacity=0.7, colorscale='Earth')#

Build a Plotly 3-D terrain mesh or surface.

Parameters:
Return type:

Any

pycsamt.map.component_spec(component)#

Return a parsed impedance component specification.

Parameters:

component (str | None)

Return type:

ComponentSpec

pycsamt.map.ensure_map_data(data, *, recursive=True, line_map=None, verbose=0)#

Return normalized map data.

Parameters:

  • data (Any) – EDI path, directory, iterable, or Sites.

  • recursive (bool) – Passed to pycsamt.emtools._core.ensure_sites().

  • line_map (dict[str, Iterable[str]] | None) – Optional line -> station names mapping used when line metadata is not embedded in EDI objects.

  • verbose (int) – Verbosity passed to ensure_sites().

Return type:

MapData

pycsamt.map.export_elevations(data, path, *, fmt=None)#

Export station id/elevation/coordinates to CSV or HDF5.

EDI files carry real, field-surveyed elevation; a ModEM (or Occam2D/MARE2DEM) inversion result does not. Exporting a survey’s EDI-derived topography here produces a small, portable lookup table — station + elevation (plus latitude/ longitude/line for provenance) — that parse_elevation_file() already knows how to read back in. That means it can be applied to an inversion-sourced view later via the “Upload file” elevation source, in a different session that never reloads the original EDIs, matching stations by id (with the same normalized fallback used by apply_elevations()).

Parameters:

  • data (MapData) – Survey to export (typically EDI-sourced, where elevation is already populated).

  • path (path-like) – Destination file. fmt defaults to the file’s own suffix (.csv / .h5 / .hdf5); pass it explicitly to override.

  • fmt ({"csv", "h5", "hdf5"}, optional)

Returns:

The path written to.

Return type:

pathlib.Path

Raises:

ValueError – If no station in data has a known elevation, or fmt is unsupported.

pycsamt.map.export_figure(fig, options)#

Export fig according to options.

Parameters:
Return type:

Path

pycsamt.map.fetch_elevations(data, *, api_name='open_meteo')#

Fetch station elevations online from their coordinates.

Uses pycsamt.gis.utils.get_elevation_from_api() (needs an internet connection and requests).

Returns:

station_id -> elevation (m) for stations with valid coordinates and a finite fetched value.

Return type:

dict

Parameters:
pycsamt.map.figure_to_dict(fig)#

Return a serializable figure dictionary.

Parameters:

fig (Any)

Return type:

dict[str, Any]

pycsamt.map.group_modem_stations(station_names, *, known_stations=None)#

Group ModEM station names into survey lines.

Prefers matching each name against known_stations (e.g. previously loaded EDI stations) and using their line tag. Falls back to parsing the line token out of the station-name convention {survey}-{line}-{station}{suffix} (e.g. 23-18-001A -> line 18) — a heuristic, used only when a station has no match in known_stations.

Parameters:
Return type:

dict[str, list[str]]

pycsamt.map.interpolate_overlay_grid(x, y, values, *, grid_size=80, method='linear')#

Interpolate scattered values to a regular grid.

Parameters:
Return type:

tuple[ndarray, ndarray, ndarray]

pycsamt.map.load_lines(source, *, detect='folder', recursive=True, line_map=None, verbose=0)#

Build one combined MapData from multiple lines.

Parameters:

  • source (Any) – Mapping, sequence, directory, or file (see module docstring). A MapData is returned unchanged.

  • detect ({"folder", "auto", "flat"}, default "folder") –

    Line-grouping rule applied only when source is a single directory:

    folder

    One line per immediate sub-folder holding EDI files (a flat folder becomes one line named after it).

    auto

    Group by the station-ID prefix, e.g. 22-001 -> L22.

    flat

    Treat the whole directory as a single line.

  • recursive (bool) – Recurse into sub-directories when discovering EDI files and when calling ensure_map_data().

  • line_map (dict[str, Iterable[str]] | None) – Optional line -> station names mapping forwarded to ensure_map_data() for sources without embedded line metadata.

  • verbose (int) – Verbosity forwarded to ensure_map_data().

Returns:

Stations from every line, re-indexed and tagged with their resolved line name; profiles are rebuilt per line.

Return type:

MapData

pycsamt.map.load_modem_lines(folder, *, known_stations=None, fetch_elevation=True, verbose=0)#

Load a ModEM 3-D inversion result folder as a multi-line MapData.

Parameters:

  • folder (path-like) – A ModEM output directory. The matching final-iteration .rho/.dat pair is auto-detected by pycsamt.models.modem.results.InversionResult.

  • known_stations (iterable of StationRecord, optional) – Previously-loaded EDI stations (e.g. existing_map_data.stations) used to geo-reference and group ModEM stations by real coordinates/line name — see the module docstring.

  • fetch_elevation (bool, default True) – ModEM output carries no real elevation (unlike EDI, where it’s already in the file header, so “Drape topography” just works). When True, any station still missing an elevation after known_stations matching gets a best-effort online lookup (Open-Meteo) so topography isn’t silently flat by default. Failures (offline, API error, …) are swallowed — elevation simply stays unset, same as passing False.

  • verbose (int, default 0) – Verbosity forwarded to the ModEM readers.

Returns:

sites=None (no EDI backing); stations carries one StationRecord per ModEM station with coordinates resolved where possible; metadata["sections"] carries the precomputed per-line (x, z, rho) curtains consumed directly by pycsamt.map.volume.

Return type:

MapData

pycsamt.map.launch_app(source=None, *, host='127.0.0.1', port=8770, debug=False, open_browser=True, theme='light', backend='plotly', detect='folder', recursive=True, **load_kwargs)#

Launch the interactive map-view app.

Parameters:

  • source (Any) – Optional survey source. None starts the welcome screen. Otherwise accepts data, paths, sites, or mappings.

  • host (str) – Forwarded to pycsamt.app.mapview.launch().

  • port (int) – Forwarded to pycsamt.app.mapview.launch().

  • debug (bool) – Forwarded to pycsamt.app.mapview.launch().

  • open_browser (bool) – Forwarded to pycsamt.app.mapview.launch().

  • theme (str) – Used when building a MapView.

  • backend (str) – Used when building a MapView.

  • detect (str) – Used for path/folder inputs.

  • recursive (bool) – Used for path/folder inputs.

  • **load_kwargs (Any) – Extra options forwarded to MapView.from_folder or load_lines().

Return type:

None

pycsamt.map.launch_mapview(source=None, **kwargs)#

Alias for launch_app().

Parameters:
Return type:

None

pycsamt.map.normalize_component(component)#

Return the canonical map component name.

Parameters:

component (str | None)

Return type:

str

pycsamt.map.normalize_epsg(epsg)#

Return an EPSG authority string.

Parameters:

epsg (int | str)

Return type:

str

pycsamt.map.normalize_station_id(name)#

Loosely-normalized station id for fuzzy matching.

Lowercases and strips everything but letters/digits, so minor formatting differences between sources — 23-18-001A vs 23_18_001a vs 23 18 001A — still match. Used as a fallback tier (never the only lookup) wherever a station from one source (EDI, ModEM, an uploaded elevation file, …) needs to be matched against another.

Parameters:

name (Any)

Return type:

str

pycsamt.map.open_app(source=None, **kwargs)#

Backward-compatible alias for launch_app().

Parameters:
Return type:

None

pycsamt.map.parse_elevation_file(content, filename)#

Parse an uploaded elevation file into {station_id: elev}.

Supports CSV, HDF5 (.h5/.hdf5) and NPZ. The file must hold a station-id column/array (one of station, id, name, sta) and an elevation column/array (elevation, elev, z, alt, altitude, height). Returns {} on any parse failure rather than raising.

Parameters:
Return type:

dict[str, float]

pycsamt.map.plot_3d_map(data, *, options=None, **kwargs)#

Build a 3-D map.

Parameters:
Return type:

Any

pycsamt.map.plot_profile_map(data, *, options=None, **kwargs)#

Build a profile-view map.

Parameters:
Return type:

Any

pycsamt.map.plot_pseudosection(data, *, options=None, **kwargs)#

Build a resistivity or phase pseudosection.

Parameters:
Return type:

Any

pycsamt.map.plot_station_map(data, *, options=None, **kwargs)#

Build a 2-D station map.

Parameters:
Return type:

Any

pycsamt.map.plot_volume_map(data, *, options=None, **kwargs)#

Build a 3-D volume map.

Parameters:
Return type:

Any

pycsamt.map.inversion_depth_range(data)#

(z_min, z_max) across every precomputed inversion section, or None when the survey carries no inversion result.

Parameters:

data (MapData)

Return type:

tuple[float, float] | None

pycsamt.map.reproject_xy_to_lonlat(x, y, *, epsg)#

Reproject x, y from epsg to WGS84 lon/lat.

Parameters:
Return type:

tuple[ndarray, ndarray]

pycsamt.map.resistivity_at_depth(data, depth)#

Per-station resistivity on a horizontal slice at depth (m below the surface), read from the precomputed inversion sections in data.metadata["sections"].

Each station column is linearly interpolated in depth; a query outside a column’s own sampled range returns no entry for that station (never a fabricated value). Returns {} when the survey has no inversion result.

Parameters:
Return type:

dict[str, float]

pycsamt.map.resolve_crs_info(mode='geo', *, zone=50, hemisphere='N', epsg=4326)#

Return a human-readable CRS description.

Parameters:
Return type:

str

pycsamt.map.resolve_line_groups(source, *, detect='folder', recursive=True)#

Return a {line_name: source} mapping for source.

The values are passed straight to ensure_map_data(), so they may be directories, lists of file paths, or EDI-like iterables. This mirrors the groups store used by the GUI loader, making the two paths share one grouping contract.

Parameters:
Return type:

dict[str, Any]

pycsamt.map.save_png(fig, path, **kwargs)#

Save a Matplotlib-like or Plotly-like figure as PNG.

Parameters:
Return type:

Path

pycsamt.map.select_frequency(frequencies, requested=None, *, tolerance=None)#

Select the closest finite positive frequency.

Parameters:

  • frequencies (Any)

  • requested (float | None)

  • tolerance (float | None)

Return type:

FrequencySelection | None

pycsamt.map.transform_xy(x, y, *, crs)#

Transform coordinates between two CRS definitions.

Parameters:
Return type:

tuple[ndarray, ndarray]

pycsamt.map.value_at_frequency_details(data, *, frequency, quantity='rho', component='xy', tolerance=None)#

Return values with selected-frequency metadata.

Parameters:
Return type:

dict[str, FrequencyValue]

pycsamt.map.write_html(fig, path, **kwargs)#

Write a Plotly-like figure to HTML.

Parameters:
Return type:

Path

pycsamt.map.write_dict(fig, path)#

Write a figure dictionary as JSON text.

Parameters:
Return type:

Path

pycsamt.map.write_image(fig, path, **kwargs)#

Write a Plotly-like image.

Parameters:
Return type:

Path

pycsamt.map.write_json(fig, path)#

Write a Plotly-like figure specification as JSON.

Parameters:
Return type:

Path

2.30.7. Modules#

pycsamt.map.config

Configuration dataclasses for pycsamt.map.

pycsamt.map._core

Core data extraction helpers for pycsamt.map.

pycsamt.map.loader

Multi-line EDI ingestion for pycsamt.map.

pycsamt.map.view

High-level MapView session façade for pyCSAMT maps.

pycsamt.map.station

2-D station-map API for pyCSAMT surveys.

pycsamt.map.profile

Profile-view and pseudosection API for pyCSAMT surveys.

pycsamt.map.volume

3-D map API for fence, block, and depth-slice views.

pycsamt.map.overlays

Overlay helpers for station, profile, and 3-D maps.

pycsamt.map.styles

Style helpers for pyCSAMT map renderers.

pycsamt.map.export

Figure export helpers for pycsamt.map.

pycsamt.map.inversion

Import geophysical inversion results into MapData.

pycsamt.map.topo

Elevation / topography sources for pycsamt.map.

2.30.8. Detailed Module API#

Core data extraction helpers for pycsamt.map.

pycsamt.map._core.normalize_station_id(name)[source]#

Loosely-normalized station id for fuzzy matching.

Lowercases and strips everything but letters/digits, so minor formatting differences between sources — 23-18-001A vs 23_18_001a vs 23 18 001A — still match. Used as a fallback tier (never the only lookup) wherever a station from one source (EDI, ModEM, an uploaded elevation file, …) needs to be matched against another.

Parameters:

name (Any)

Return type:

str

class pycsamt.map._core.StationRecord(id, latitude=None, longitude=None, elevation=None, line=None, index=0, source=None)[source]#

Bases: object

A normalized station row used by map renderers.

Parameters:
id: str#
latitude: float | None = None#
longitude: float | None = None#
elevation: float | None = None#
line: str | None = None#
index: int = 0#
source: Any = None#
class pycsamt.map._core.ProfileLine(name, stations=())[source]#

Bases: object

A named sequence of stations in one profile.

Parameters:
name: str#
stations: tuple[StationRecord, ...] = ()#
class pycsamt.map._core.MapData(sites, stations=(), profiles=(), metadata=<factory>)[source]#

Bases: object

Normalized survey data shared by map renderers.

Parameters:
sites: Any#
stations: tuple[StationRecord, ...] = ()#
profiles: tuple[ProfileLine, ...] = ()#
metadata: dict[str, Any]#
property station_ids: tuple[str, ...][source]#

Return normalized station IDs.

property lines: tuple[str, ...][source]#

Return available profile/line names.

property has_geo: bool[source]#

Whether stations have finite map coordinates.

iter_edis()[source]#

Return EDI-like source objects.

Return type:

tuple[Any, …]

class pycsamt.map._core.ComponentSpec(name, indices=None, mode='tensor')[source]#

Bases: object

Parsed impedance component request.

Parameters:
name: str#
indices: tuple[int, int] | None = None#
mode: str = 'tensor'#
class pycsamt.map._core.FrequencySelection(requested, actual, index, delta, relative_delta, within_tolerance=True)[source]#

Bases: object

Nearest-frequency selection metadata.

Parameters:
requested: float | None#
actual: float#
index: int#
delta: float#
relative_delta: float#
within_tolerance: bool = True#
class pycsamt.map._core.FrequencyValue(station, value, selection)[source]#

Bases: object

Station value and selected-frequency metadata.

Parameters:
station: str#
value: float#
selection: FrequencySelection#
pycsamt.map._core.ensure_map_data(data, *, recursive=True, line_map=None, verbose=0)[source]#

Return normalized map data.

Parameters:

  • data (Any) – EDI path, directory, iterable, or Sites.

  • recursive (bool) – Passed to pycsamt.emtools._core.ensure_sites().

  • line_map (dict[str, Iterable[str]] | None) – Optional line -> station names mapping used when line metadata is not embedded in EDI objects.

  • verbose (int) – Verbosity passed to ensure_sites().

Return type:

MapData

pycsamt.map._core.station_records(data, **kwargs)[source]#

Return normalized station records for data.

Parameters:
Return type:

tuple[StationRecord, …]

pycsamt.map._core.profile_lines(data, **kwargs)[source]#

Return normalized profile lines for data.

Parameters:
Return type:

tuple[ProfileLine, …]

pycsamt.map._core.station_dataframe(data)[source]#

Return station records as a DataFrame.

Parameters:

data (MapData)

Return type:

DataFrame

pycsamt.map._core.normalize_component(component)[source]#

Return the canonical map component name.

Parameters:

component (str | None)

Return type:

str

pycsamt.map._core.component_spec(component)[source]#

Return a parsed impedance component specification.

Parameters:

component (str | None)

Return type:

ComponentSpec

pycsamt.map._core.component_index(component)[source]#

Return tensor indices for an impedance component.

Parameters:

component (str)

Return type:

tuple[int, int]

pycsamt.map._core.component_values(arr, component, *, quantity='rho')[source]#

Extract a 1-D value series for one component.

Parameters:

  • arr (Any)

  • component (str | None)

  • quantity (str)

Return type:

ndarray

pycsamt.map._core.frequency_axis(data)[source]#

Return the first finite frequency axis found.

Parameters:

data (MapData)

Return type:

ndarray

pycsamt.map._core.select_frequency(frequencies, requested=None, *, tolerance=None)[source]#

Select the closest finite positive frequency.

Parameters:

  • frequencies (Any)

  • requested (float | None)

  • tolerance (float | None)

Return type:

FrequencySelection | None

pycsamt.map._core.station_distance_km(data)[source]#

Return approximate station distance in km.

Parameters:

data (MapData)

Return type:

ndarray

pycsamt.map._core.value_at_frequency(data, *, frequency, quantity='rho', component='xy', tolerance=None)[source]#

Return station values at the closest frequency.

Parameters:
Return type:

dict[str, float]

pycsamt.map._core.value_at_frequency_details(data, *, frequency, quantity='rho', component='xy', tolerance=None)[source]#

Return values with selected-frequency metadata.

Parameters:
Return type:

dict[str, FrequencyValue]

pycsamt.map._core.skin_depth_at_frequency(data, *, frequency, component='xy', tolerance=None)[source]#

Return skin depth at the closest frequency.

Parameters:
Return type:

dict[str, float]

pycsamt.map._core.inversion_depth_range(data)[source]#

(z_min, z_max) across every precomputed inversion section, or None when the survey carries no inversion result.

Parameters:

data (MapData)

Return type:

tuple[float, float] | None

pycsamt.map._core.resistivity_at_depth(data, depth)[source]#

Per-station resistivity on a horizontal slice at depth (m below the surface), read from the precomputed inversion sections in data.metadata["sections"].

Each station column is linearly interpolated in depth; a query outside a column’s own sampled range returns no entry for that station (never a fabricated value). Returns {} when the survey has no inversion result.

Parameters:
Return type:

dict[str, float]

pycsamt.map._core.pseudosection_table(data, *, quantity='rho', component='xy')[source]#

Return long-form profile data for pseudosections.

Parameters:
Return type:

DataFrame

Multi-line EDI ingestion for pycsamt.map.

A map-view survey is usually made of several profile lines, each stored as its own EDI folder. The renderers in pycsamt.map already understand the per-station line attribute, but the normalizer pycsamt.map._core.ensure_map_data() only consumes a single source. This module lifts the multi-line grouping logic out of the GUI layer so scripts and notebooks can build one combined MapData from many lines.

2.30.8.1. Accepted source forms#

mapping

{line_name: dir | iterable_of_edis} — explicit line layout.

sequence of directories

[dir_a, dir_b, ...] — one line per directory (named after it).

sequence of EDI-like items / files

Treated as a single "line".

single directory

Grouped according to detect (see load_lines()).

single file

A one-station line named after the file stem.

pycsamt.map.loader.load_lines(source, *, detect='folder', recursive=True, line_map=None, verbose=0)[source]#

Build one combined MapData from multiple lines.

Parameters:

  • source (Any) – Mapping, sequence, directory, or file (see module docstring). A MapData is returned unchanged.

  • detect ({"folder", "auto", "flat"}, default "folder") –

    Line-grouping rule applied only when source is a single directory:

    folder

    One line per immediate sub-folder holding EDI files (a flat folder becomes one line named after it).

    auto

    Group by the station-ID prefix, e.g. 22-001 -> L22.

    flat

    Treat the whole directory as a single line.

  • recursive (bool) – Recurse into sub-directories when discovering EDI files and when calling ensure_map_data().

  • line_map (dict[str, Iterable[str]] | None) – Optional line -> station names mapping forwarded to ensure_map_data() for sources without embedded line metadata.

  • verbose (int) – Verbosity forwarded to ensure_map_data().

Returns:

Stations from every line, re-indexed and tagged with their resolved line name; profiles are rebuilt per line.

Return type:

MapData

pycsamt.map.loader.resolve_line_groups(source, *, detect='folder', recursive=True)[source]#

Return a {line_name: source} mapping for source.

The values are passed straight to ensure_map_data(), so they may be directories, lists of file paths, or EDI-like iterables. This mirrors the groups store used by the GUI loader, making the two paths share one grouping contract.

Parameters:
Return type:

dict[str, Any]

High-level MapView session façade for pyCSAMT maps.

MapView is the single object scripts, notebooks, and the map-view platform share. It holds one combined MapData (possibly spanning many lines) and renders every view through the existing builders, so the GUI carries no plotting logic of its own.

Examples

>>> from pycsamt.map import MapView
>>> mv = MapView.from_folder("data/survey", detect="folder")
>>> mv.lines
('L18PLT', 'L22PLT')
>>> fig = mv.station(overlay="rho", frequency=1024)
>>> mv.export("out/station.html")
class pycsamt.map.view.MapView(data, *, theme='light', backend='plotly')[source]#

Bases: object

A code-first session bound to one (multi-line) survey.

Parameters:

  • data (Any)

  • theme (str)

  • backend (str)

classmethod from_folder(path, *, detect='folder', recursive=True, theme='light', backend='plotly', **load_kwargs)[source]#

Build a view from a directory of one or more lines.

Parameters:
Return type:

MapView

classmethod from_lines(lines, *, theme='light', backend='plotly', **load_kwargs)[source]#

Build a view from an explicit {line: source} mapping.

Parameters:
Return type:

MapView

classmethod from_inversion_results(folder, *, known_stations=None, fetch_elevation=True, theme='light', backend='plotly', verbose=0)[source]#

Build a view from a ModEM 3-D inversion result folder.

See pycsamt.map.inversion.load_modem_lines(). Pass known_stations=existing_view.data.stations to geo-reference and group ModEM stations using a previously-loaded EDI survey. Pass fetch_elevation=False to skip the best-effort online elevation lookup (e.g. offline use, or large surveys where the extra round-trip isn’t wanted).

Parameters:
Return type:

MapView

classmethod from_pcsf(path, *, known_stations=None, fetch_elevation=True, theme='light', backend='plotly', mesh_z_samples=60)[source]#

Build a view from a backend-neutral .pcsf/.pcsm/ .pcsm.gz file.

See pycsamt.map.inversion.load_pcsf_lines(). Works with a file in either PCSF encoding (binary .pcsf or its lossless ASCII sibling, .pcsm/gzip-compressed .pcsm.gz — see pycsamt/format/SPEC.md S9) with any of the four geometry kinds — grid2d, multiline, native grid3d (e.g. ModEM 3-D), or mesh_unstructured (e.g. MARE2DEM, sampled by point-location on its real triangulation, see mesh_z_samples) — pass known_stations=existing_view.data.stations to geo-reference it against a previously-loaded EDI survey, the same as from_inversion_results().

Parameters:
Return type:

MapView

property lines: tuple[str, ...][source]#

Return the profile/line names in this survey.

property stations: tuple[str, ...][source]#

Return the station IDs in this survey.

property n_stations: int[source]#

Return the number of stations across all lines.

property has_geo: bool[source]#

Whether stations carry finite map coordinates.

table()[source]#

Return survey stations as a pandas.DataFrame.

with_elevations(elev_map)[source]#

Return a copy with station elevations overridden by elev_map.

Parameters:

elev_map (dict[str, float])

Return type:

MapView

fetch_elevations(*, api_name='open_meteo')[source]#

Fetch station elevations online (see pycsamt.map.fetch_elevations()).

Parameters:

api_name (str)

Return type:

dict[str, float]

export_topography(path, *, fmt=None)[source]#

Export this survey’s station id/elevation/coordinates.

Useful for an EDI-sourced view: a ModEM (or Occam2D/MARE2DEM) inversion result carries no real elevation of its own, so exporting it here produces a small, portable file that can be re-applied later — even in a session that never reloads these EDIs — via the “Upload file” elevation source (see pycsamt.map.topo.export_elevations()).

Parameters:
station(*, options=None, **overrides)[source]#

Build a 2-D station map figure.

Parameters:
Return type:

Any

profile(*, options=None, **overrides)[source]#

Build a profile-view figure.

Parameters:
Return type:

Any

pseudosection(*, options=None, **overrides)[source]#

Build a resistivity/phase pseudosection figure.

Parameters:
Return type:

Any

map3d(*, mode='fence', options=None, **overrides)[source]#

Build a 3-D fence/block/depth/surface figure.

Parameters:
Return type:

Any

figure(view='station', **overrides)[source]#

Build a figure for view by name.

Parameters:

  • view ({"station", "profile", "pseudosection", "map3d"}) – Which renderer to call.

  • **overrides – Forwarded to the matching renderer.

Return type:

Any

export(path, *, view='station', fmt=None, scale=2.0, width=None, height=None, **overrides)[source]#

Render view and write it to path.

The format is inferred from the suffix unless fmt is given; .html, .png, .json and Plotly static images are supported (see pycsamt.map.export_figure()).

Parameters:
Return type:

Path

export_all(directory, *, fmt='html', views=('station', 'pseudosection', 'map3d'), **overrides)[source]#

Export several views into directory, keyed by view name.

Parameters:
Return type:

dict[str, Path]

launch(**kwargs)[source]#

Open this survey in the map-view platform.

Requires the optional Dash GUI extra (pycsamt.app.mapview).

Parameters:

kwargs (Any)

Return type:

None

pycsamt.map.view.launch_app(source=None, *, host='127.0.0.1', port=8770, debug=False, open_browser=True, theme='light', backend='plotly', detect='folder', recursive=True, **load_kwargs)#

Launch the interactive map-view app.

Parameters:

  • source (Any) – Optional survey source. None starts the welcome screen. Otherwise accepts data, paths, sites, or mappings.

  • host (str) – Forwarded to pycsamt.app.mapview.launch().

  • port (int) – Forwarded to pycsamt.app.mapview.launch().

  • debug (bool) – Forwarded to pycsamt.app.mapview.launch().

  • open_browser (bool) – Forwarded to pycsamt.app.mapview.launch().

  • theme (str) – Used when building a MapView.

  • backend (str) – Used when building a MapView.

  • detect (str) – Used for path/folder inputs.

  • recursive (bool) – Used for path/folder inputs.

  • **load_kwargs (Any) – Extra options forwarded to MapView.from_folder or load_lines().

Return type:

None

pycsamt.map.view.launch_mapview(source=None, **kwargs)#

Alias for launch_app().

Parameters:
Return type:

None

pycsamt.map.view.open_app(source=None, **kwargs)#

Backward-compatible alias for launch_app().

Parameters:
Return type:

None

2-D station-map API for pyCSAMT surveys.

class pycsamt.map.station.StationMap(data, *, options=None, **ensure_kwargs)[source]#

Bases: object

Builder object for station-map figures.

Parameters:
with_overlay(overlay, **kwargs)[source]#

Return a copy with a different overlay.

Parameters:
Return type:

StationMap

with_options(**kwargs)[source]#

Return a copy with updated options.

Parameters:

kwargs (Any)

Return type:

StationMap

figure()[source]#

Build and return the station-map figure.

Return type:

Any

pycsamt.map.station.plot_station_map(data, *, options=None, **kwargs)[source]#

Build a 2-D station map.

Parameters:
Return type:

Any

pycsamt.map.station.build_station_map(data, options=None)[source]#

Build a Plotly 2-D station map.

Parameters:
Return type:

Any

Profile-view and pseudosection API for pyCSAMT surveys.

class pycsamt.map.profile.ProfileMap(data, *, options=None, **ensure_kwargs)[source]#

Bases: object

Builder object for profile maps.

Parameters:
with_options(**kwargs)[source]#

Return a copy with updated options.

Parameters:

kwargs (Any)

Return type:

ProfileMap

with_quantity(quantity)[source]#

Return a copy using another mapped quantity.

Parameters:

quantity (str)

Return type:

ProfileMap

with_component(component)[source]#

Return a copy using one impedance component.

Parameters:

component (str)

Return type:

ProfileMap

with_components(*components)[source]#

Return a copy using multiple components.

Parameters:

components (str)

Return type:

ProfileMap

figure()[source]#

Build and return the profile figure.

Return type:

Any

pseudosection()[source]#

Build and return the pseudosection figure.

Return type:

Any

pycsamt.map.profile.plot_profile_map(data, *, options=None, **kwargs)[source]#

Build a profile-view map.

Parameters:
Return type:

Any

pycsamt.map.profile.plot_pseudosection(data, *, options=None, **kwargs)[source]#

Build a resistivity or phase pseudosection.

Parameters:
Return type:

Any

pycsamt.map.profile.build_profile_map(data, options)[source]#

Build the concrete profile-view figure.

Parameters:
Return type:

Any

pycsamt.map.profile.build_pseudosection(data, options)[source]#

Build the concrete pseudosection figure.

Parameters:
Return type:

Any

3-D map API for fence, block, and depth-slice views.

class pycsamt.map.volume.Map3D(data, *, options=None, **ensure_kwargs)[source]#

Bases: object

Builder object for 3-D survey maps.

Parameters:
with_mode(mode)[source]#

Return a copy with another 3-D mode.

Parameters:

mode (str)

Return type:

Map3D

with_options(**kwargs)[source]#

Return a copy with updated options.

Parameters:

kwargs (Any)

Return type:

Map3D

with_quantity(quantity)[source]#

Return a copy using another mapped quantity.

Parameters:

quantity (str)

Return type:

Map3D

with_component(component)[source]#

Return a copy using another component.

Parameters:

component (str)

Return type:

Map3D

figure()[source]#

Build and return the 3-D map figure.

Return type:

Any

pycsamt.map.volume.VolumeMap#

alias of Map3D

pycsamt.map.volume.plot_3d_map(data, *, options=None, **kwargs)[source]#

Build a 3-D map.

Parameters:
Return type:

Any

pycsamt.map.volume.plot_volume_map(data, *, options=None, **kwargs)[source]#

Build a 3-D volume map.

Parameters:
Return type:

Any

pycsamt.map.volume.build_3d_map(data, options)[source]#

Build the concrete 3-D figure.

Parameters:
Return type:

Any

Configuration dataclasses for pycsamt.map.

class pycsamt.map.config.StationMapOptions(overlay='index', frequency=None, frequency_tolerance=None, depth=None, show_markers=True, component='xy', theme='light', backend='plotly', selected_id=None, line_filter=None, marker_size=10, basemap=None, cmap='plasma', value_range=None, log_color=False, opacity=0.92, show_labels=True, label_fontsize=8.0, label_rotation=0.0, show_profiles=True, elevation_mode='markers', show_contours=False, contour_image=False, contour_mode='filled+lines', contour_levels=12, contour_opacity=0.55, contour_interp='linear', contour_smooth=1.0, contour_grid_res=150, bearing=0.0, title='')[source]#

Bases: object

Options for 2-D station maps.

Parameters:

  • overlay (str)

  • frequency (float | None)

  • frequency_tolerance (float | None)

  • depth (float | None)

  • show_markers (bool)

  • component (str)

  • theme (Literal['light', 'dark', 'publication'])

  • backend (Literal['plotly', 'matplotlib'])

  • selected_id (str | None)

  • line_filter (tuple[str, ...] | None)

  • marker_size (int)

  • basemap (str | None)

  • cmap (str)

  • value_range (tuple[float, float] | None)

  • log_color (bool)

  • opacity (float)

  • show_labels (bool)

  • label_fontsize (float)

  • label_rotation (float)

  • show_profiles (bool)

  • elevation_mode (Literal['markers', 'contours'])

  • show_contours (bool)

  • contour_image (bool)

  • contour_mode (str)

  • contour_levels (int)

  • contour_opacity (float)

  • contour_interp (str)

  • contour_smooth (float)

  • contour_grid_res (int)

  • bearing (float)

  • title (str)

overlay: str = 'index'#
frequency: float | None = None#
frequency_tolerance: float | None = None#
depth: float | None = None#
show_markers: bool = True#
component: str = 'xy'#
theme: Literal['light', 'dark', 'publication'] = 'light'#
backend: Literal['plotly', 'matplotlib'] = 'plotly'#
selected_id: str | None = None#
line_filter: tuple[str, ...] | None = None#
marker_size: int = 10#
basemap: str | None = None#
cmap: str = 'plasma'#
value_range: tuple[float, float] | None = None#
log_color: bool = False#
opacity: float = 0.92#
show_labels: bool = True#
label_fontsize: float = 8.0#
label_rotation: float = 0.0#
show_profiles: bool = True#
elevation_mode: Literal['markers', 'contours'] = 'markers'#
show_contours: bool = False#
contour_image: bool = False#
contour_mode: str = 'filled+lines'#
contour_levels: int = 12#
contour_opacity: float = 0.55#
contour_interp: str = 'linear'#
contour_smooth: float = 1.0#
contour_grid_res: int = 150#
bearing: float = 0.0#
title: str = ''#
class pycsamt.map.config.ProfileMapOptions(quantity='rho', component='xy', components=('xy', 'yx'), theme='light', backend='plotly', period_range=None, phase_range=None, value_range=None, x_axis='station', log_rho=True, height_per_panel=260, show_errbar=False, cmap=None, by_line=False, line_cols=None)[source]#

Bases: object

Options for pseudosection and profile-view maps.

Parameters:
quantity: str = 'rho'#
component: str = 'xy'#
components: tuple[str, ...] = ('xy', 'yx')#
theme: Literal['light', 'dark', 'publication'] = 'light'#
backend: Literal['plotly', 'matplotlib'] = 'plotly'#
period_range: tuple[float, float] | None = None#
phase_range: tuple[float, float] | None = None#
value_range: tuple[float, float] | None = None#
x_axis: Literal['station', 'distance'] = 'station'#
log_rho: bool = True#
height_per_panel: int = 260#
show_errbar: bool = False#
cmap: str | None = None#
by_line: bool = False#
line_cols: int | None = None#
class pycsamt.map.config.VolumeMapOptions(mode='fence', quantity='resistivity', component='xy', theme='light', cmap='RdYlBu_r', depth_range=None, period_range=None, rho_range=None, iso_range=None, value_range=None, log_color=True, opacity=0.85, show_contours=False, show_labels=True, n_slices=5, surface_count=12, line_spacing=1.0, azimuth=0.0, topography=True, show_terrain=True, terrain_opacity=0.7, show_stations=False, station_symbol='diamond', station_size=4, station_color='#1f2937', station_labels=False, station_label_angle=0.0, station_label_fraction=1.0, station_label_names=None, max_stations=None, aspectmode='data', x_unit='m', depth_unit='m', smooth_sections=True, section_res=100, volume_smoothing=0.0, title='')[source]#

Bases: object

Options for 3-D fence, block, and depth-slice maps.

Parameters:
mode: Literal['fence', 'block', 'depth', 'surface'] = 'fence'#
quantity: str = 'resistivity'#
component: str = 'xy'#
theme: Literal['light', 'dark', 'publication'] = 'light'#
cmap: str = 'RdYlBu_r'#
depth_range: tuple[float, float] | None = None#
period_range: tuple[float, float] | None = None#
rho_range: tuple[float, float] | None = None#
iso_range: tuple[float, float] | None = None#
value_range: tuple[float, float] | None = None#
log_color: bool = True#
opacity: float = 0.85#
show_contours: bool = False#
show_labels: bool = True#
n_slices: int = 5#
surface_count: int = 12#
line_spacing: float = 1.0#
azimuth: float = 0.0#
topography: bool = True#
show_terrain: bool = True#
terrain_opacity: float = 0.7#
show_stations: bool = False#
station_symbol: str = 'diamond'#
station_size: int = 4#
station_color: str = '#1f2937'#
station_labels: bool = False#
station_label_angle: float = 0.0#
station_label_fraction: float = 1.0#
station_label_names: tuple[str, ...] | None = None#
max_stations: int | None = None#
aspectmode: str = 'data'#
x_unit: str = 'm'#
depth_unit: str = 'm'#
smooth_sections: bool = True#
section_res: int = 100#
volume_smoothing: float = 0.0#
title: str = ''#
class pycsamt.map.config.ExportOptions(path, format=None, width=None, height=None, scale=2.0, include_plotlyjs='cdn')[source]#

Bases: object

Options used by figure export helpers.

Parameters:
path: str | Path#
format: str | None = None#
width: int | None = None#
height: int | None = None#
scale: float = 2.0#
include_plotlyjs: str | bool = 'cdn'#

Overlay helpers for station, profile, and 3-D maps.

class pycsamt.map.overlays.ContourOverlay(values, x, y, levels=12, cmap='viridis', opacity=0.65)[source]#

Bases: object

Description of an interpolated contour overlay.

Parameters:
values: ndarray#
x: ndarray#
y: ndarray#
levels: int = 12#
cmap: str = 'viridis'#
opacity: float = 0.65#
class pycsamt.map.overlays.TopographyOverlay(elevation, source='stations', opacity=0.7)[source]#

Bases: object

Topography aligned to map coordinates.

Parameters:
elevation: ndarray#
source: str = 'stations'#
opacity: float = 0.7#
class pycsamt.map.overlays.CRSConfig(source, target=4326, always_xy=True)[source]#

Bases: object

Coordinate transform settings.

Parameters:
source: int | str#
target: int | str = 4326#
always_xy: bool = True#
class pycsamt.map.overlays.BasemapConfig(style, center, zoom, bearing=0.0, layers=())[source]#

Bases: object

Plotly geographic map layout settings.

Parameters:
style: str#
center: dict[str, float]#
zoom: int#
bearing: float = 0.0#
layers: tuple = ()#
pycsamt.map.overlays.basemap_style_and_layers(style, *, dark=False)[source]#

Resolve a style name into a (base style, raster layers) pair.

ESRI styles are rendered as white-bg + a raster tile layer; native Plotly styles are returned as-is with no layers.

Parameters:
Return type:

tuple[str, list]

pycsamt.map.overlays.resolve_crs_info(mode='geo', *, zone=50, hemisphere='N', epsg=4326)[source]#

Return a human-readable CRS description.

Parameters:
Return type:

str

pycsamt.map.overlays.normalize_epsg(epsg)[source]#

Return an EPSG authority string.

Parameters:

epsg (int | str)

Return type:

str

pycsamt.map.overlays.transform_xy(x, y, *, crs)[source]#

Transform coordinates between two CRS definitions.

Parameters:
Return type:

tuple[ndarray, ndarray]

pycsamt.map.overlays.reproject_xy_to_lonlat(x, y, *, epsg)[source]#

Reproject x, y from epsg to WGS84 lon/lat.

Parameters:
Return type:

tuple[ndarray, ndarray]

pycsamt.map.overlays.build_contour_overlay(x, y, values, *, levels=12, cmap='Viridis', opacity=0.65, grid_size=80, mode='lines')[source]#

Build an interpolated map contour overlay.

Returns a Plotly Contour trace on a regular grid.

Parameters:
Return type:

Any

pycsamt.map.overlays.build_geo_contour_image(lons, lats, values, *, cmap='jet', n_levels=12, opacity=0.6, mode='filled+lines', log_scale=False, grid_res=160, expand=0.06, interp='cubic', smooth_sigma=0.0, vmin=None, vmax=None)[source]#

Render a Surfer-style filled-contour PNG for a basemap image layer.

Interpolates sparse station values onto a regular lon/lat grid and rasterises filled (and/or line) contours to a transparent PNG. The result is meant to be added to a Plotly map as an image layer.

Returns:

{"image": "data:image/png;base64,...", "coordinates": [...], "vmin": float, "vmax": float} (coordinates are the TL, TR, BR, BL [lon, lat] corners), or None when it cannot be built.

Return type:

dict | None

Parameters:
pycsamt.map.overlays.interpolate_overlay_grid(x, y, values, *, grid_size=80, method='linear')[source]#

Interpolate scattered values to a regular grid.

Parameters:
Return type:

tuple[ndarray, ndarray, ndarray]

pycsamt.map.overlays.build_topography_overlay(x, y, elevation, *, opacity=0.7, colorscale='Earth')[source]#

Build a Plotly 3-D terrain mesh or surface.

Parameters:
Return type:

Any

pycsamt.map.overlays.build_station_label_overlay(x, y, labels, *, geo=False, name='Station labels', color='#111827')[source]#

Build a reusable station-label overlay trace.

Parameters:
Return type:

Any

pycsamt.map.overlays.build_profile_line_overlay(x, y, *, geo=False, name='Profile', color='#2563eb', width=2.0)[source]#

Build a reusable profile-line overlay trace.

Parameters:
Return type:

Any

pycsamt.map.overlays.build_basemap_layout(lon, lat, *, dark=False, style=None, bearing=0.0)[source]#

Return layout settings for geographic station maps.

Parameters:
Return type:

BasemapConfig

pycsamt.map.overlays.default_basemap(dark=False)[source]#

Return a default public tile style.

Parameters:

dark (bool)

Return type:

str

pycsamt.map.overlays.auto_map_zoom(lon, lat)[source]#

Estimate a reasonable Plotly map zoom.

Parameters:
Return type:

int

Figure export helpers for pycsamt.map.

pycsamt.map.export.write_html(fig, path, **kwargs)[source]#

Write a Plotly-like figure to HTML.

Parameters:
Return type:

Path

pycsamt.map.export.write_image(fig, path, **kwargs)[source]#

Write a Plotly-like image.

Parameters:
Return type:

Path

pycsamt.map.export.save_png(fig, path, **kwargs)[source]#

Save a Matplotlib-like or Plotly-like figure as PNG.

Parameters:
Return type:

Path

pycsamt.map.export.export_figure(fig, options)[source]#

Export fig according to options.

Parameters:
Return type:

Path

pycsamt.map.export.write_json(fig, path)[source]#

Write a Plotly-like figure specification as JSON.

Parameters:
Return type:

Path

pycsamt.map.export.write_dict(fig, path)[source]#

Write a figure dictionary as JSON text.

Parameters:
Return type:

Path

pycsamt.map.export.figure_to_dict(fig)[source]#

Return a serializable figure dictionary.

Parameters:

fig (Any)

Return type:

dict[str, Any]

On this page