Plotting

MSNoise comes with some default plotting tools.

All plotting commands accept the --outfile argument. If provided, the figure will be saved to the disk. Names can be explicit, or tell the code to generate the filename automatically (using the ? question mark), for example:

# automatic naming, save to PNG
msnoise cc dtt plot dvv -o ?.png

# automatic naming, save to PDF
msnoise cc dtt plot dvv -o ?.pdf

# explicit naming, save to JPG
msnoise cc dtt plot dvv -o mydvv.jpg

Customizing Plots 

All plots commands can be overridden using a -c argument in front of the plot command !!

Examples:

msnoise -c plot distance
msnoise -c plot ccftime YA.UV02 YA.UV06 -m 5
etc.

To make this work, one has to copy the plot script from the msnoise install directory to the project directory (where your db.ini file is located, then edit it to one’s desires. The first thing to edit in the code is the import of the MSNoise API:

from ..api import *

to

from msnoise.api import *

and it should work.

New in version 1.4.

Data Availability Plot 

Plots the data availability, as contained in the database. Every day which .. include:: /clickhelp/msnoise-plot-data_availability.rst

has a least some data will be coloured in red. Days with no data remain blank.

Example:

msnoise plot data_availability :

Station Map 

This plots a station map using PyGMT.

msnoise plot station_map --help

Usage:  [OPTIONS]

  Plots the station map

Options:
  -s, --show BOOLEAN  Show figure interactively?
  -o, --outfile TEXT  Output filename (?=auto). Supports any matplotlib
                      format, e.g. ?.pdf for PDF with automatic naming.
  --help              Show this message and exit.

Example:

msnoise plot station_map :

It will also generate a HTML file showing the stations on the Leaflet Mapping Service:

Interferogram Plot 

This plot shows the cross-correlation functions (CCF) vs time in a very similar .. include:: /clickhelp/msnoise-cc-plot-interferogram.rst

manner as on the ccftime plot above, but shows an image instead of wiggles. The parameters allow to plot the daily or the mov-stacked CCF. Filters and components are selectable too. Passing --refilter allows to bandpass filter CCFs before plotting .

Example:

msnoise cc plot interferogram YA.UV06 YA.UV11 -m5 will plot the ZZ component (default), filter 1 (default) and mov_stack 5:

CCF vs Time 

This plot shows the cross-correlation functions (CCF) vs time. The parameters .. include:: /clickhelp/msnoise-cc-plot-ccftime.rst

allow to plot the daily or the mov-stacked CCF. Filters and components are selectable too. The --ampli argument allows to increase the vertical scale of the CCFs. The --seismic shows the up-going wiggles with a black-filled background (very heavy !). Passing --refilter allows to bandpass filter CCFs before plotting .

Example:

msnoise cc plot ccftime YA.UV06 YA.UV11 will plot all defaults:

For zooming in the CCFs:

msnoise cc plot ccftime YA.UV05 YA.UV11 --xlim=-10,10 --ampli=15:

It is sometimes useful to refilter the CCFs on the fly:

msnoise cc plot ccftime YA.UV05 YA.UV11 -r 0.5:1.0:

CCF’s spectrum vs Time 

This plot shows the cross-correlation functions’ spectrum vs time. The .. include:: /clickhelp/msnoise-cc-plot-spectime.rst

parameters allow to plot the daily or the mov-stacked CCF. Filters and components are selectable too. The --ampli argument allows to increase the vertical scale of the CCFs. Passing --refilter allows to bandpass filter CCFs before computing the FFT and plotting. Passing --startdate and --enddate parameters allows to specify which period of data should be plotted. By default the plot uses dates determined in database.

Example:

msnoise cc plot spectime YA.UV05 YA.UV11 will plot all defaults:

Zooming in the X-axis and playing with the amplitude:

msnoise cc plot spectime YA.UV05 YA.UV11 --xlim=0.08,1.1 --ampli=10:

And refiltering to enhance high frequency content:

msnoise cc plot spectime YA.UV05 YA.UV11 --xlim=0.5,1.1 --ampli=10 -r0.7:1.0:

MWCS Plot 

This plot shows the result of the MWCS calculations in two superposed images. .. include:: /clickhelp/msnoise-cc-dtt-plot-mwcs.rst

One is the dt calculated vs time lag and the other one is the coherence. The image is constructed by horizontally stacking the MWCS of different days. The two right panels show the mean and standard deviation per time lag of the whole image. The selected time lags for the dt/t calculation are presented with green horizontal lines, and the minimum coherence or the maximum dt are in red.

Example:

msnoise cc dtt plot mwcs BE.UCC.-- BE.MEM.-- -f 1 -w 1 -mi 1 will plot MWCS for filter 1, mwcs set 1, first mov_stack:

Distance Plot 

Plots the REF stacks vs interstation distance. This could help deciding which .. include:: /clickhelp/msnoise-cc-plot-distance.rst

parameters to use in the dt/t calculation step. Passing --refilter allows to bandpass filter CCFs before plotting . It is also possible to only draw CCFs for pairs including one station by passing --virtual-pair followed by the desired NET.STA .

Example:

msnoise cc plot distance will plot all defaults:

dv/v Plot 

Plot dv/v from the MWCS → dt/t method.

Reads pre-aggregated network dv/v from the mwcs_dtt_dvv step output written by msnoise.s07_compute_dvv.

Example:

msnoise cc dtt plot mwcs_dtt will plot all defaults.

msnoise cc dtt plot mwcs_dtt -f 2 -m 1 -c ZZ will plot filter 2, mov_stack 1, component ZZ.

dt/t Plot 

This plots dt (delay time) against t (time lag) for a single day. It shows .. include:: /clickhelp/msnoise-cc-dtt-plot-dtt.rst

the raw MWCS measurements as a scatter plot plus the M and M0 regression lines computed by the MWCS-DTT step.

Example:

msnoise cc dtt plot dtt BE.UCC.-- BE.MEM.-- 2023-06-15 -f 1 -w 1 -d 1 will plot MWCS scatter + DTT regression for that day:

PSD-RMS 

PSD-RMS Visualisation 

Plots derived from the psd_rms workflow step: time-series, clock plots, hour-maps, grid-maps, and daily stacks. Ported and adapted from the SeismoRMS / SeismoSocialDistancing project (https://github.com/ThomasLecocq/SeismoRMS).

CLI usage:

msnoise qc plot_psd_rms BE.UCC..HHZ --type timeseries --band 1.0-10.0
msnoise qc plot_psd_rms BE.UCC..HHZ --type clockplot  --timezone Europe/Brussels
msnoise qc plot_psd_rms BE.UCC..HHZ --type hourmap
msnoise qc plot_psd_rms BE.UCC..HHZ --type gridmap
msnoise qc plot_psd_rms BE.UCC..HHZ --type dailyplot

Notebook usage:

from msnoise.core.db import connect
from msnoise.results import MSNoiseResult
from msnoise.plots.psd_rms import load_rms, plot_timeseries, plot_clockplot

db = connect()
r = MSNoiseResult.from_ids(db, psd=1, psd_rms=1)
data = load_rms(r, ["BE.UCC..HHZ"])
plot_timeseries(data, band="1.0-10.0")

class msnoise.plots.psd_rms.DayNightWindow(day_start: float = 7.0, day_end: float = 19.0, day_color: str = '#fffacd', night_color: str = '#cce5ff', day_alpha: float = 0.15, night_alpha: float = 0.12)

Define the local “daytime” and “nighttime” hour windows.

Used by all plot functions to:

draw the daytime median overlay on time-series plots,
shade night hours on clockplots, gridmaps, and dailyplots,
shade night sectors on hourmaps.

Hours are expressed as floats in 0..24 in local time (after timezone conversion). The window wraps midnight correctly, so day_start=22 with day_end=6 defines a “daytime” from 22:00 to 06:00 (e.g. a city station where the quiet hours are at night).

Parameters:

day_start:: Start of daytime in decimal hours (default 7.0 = 07:00 local).
day_end:: End of daytime in decimal hours (default 19.0 = 19:00 local).
day_color:: Matplotlib colour for daytime shading (default light yellow).
night_color:: Matplotlib colour for nighttime shading (default light blue).
day_alpha:: Alpha for daytime shading (default 0.15).
night_alpha:: Alpha for nighttime shading (default 0.12).

Examples

>>> # Standard business-hours window
>>> dnw = DayNightWindow(day_start=8, day_end=18)

>>> # Seismological quiet window: anthropogenic noise lowest 22:00-05:00
>>> dnw = DayNightWindow(day_start=5, day_end=22)

>>> # Marine station: no meaningful day/night -- disable shading
>>> dnw = DayNightWindow(day_start=0, day_end=24)

day_start: float = 7.0

day_end: float = 19.0

day_color: str = '#fffacd'

night_color: str = '#cce5ff'

day_alpha: float = 0.15

night_alpha: float = 0.12

property day_label: str: Human-readable label, e.g. ‘7-19 h’.

shade_cartesian_hour(ax) → None

Shade day / night horizontal bands on a Cartesian hour-of-day y-axis.

Assumes the y-axis represents hours 0-24 (gridmap).

shade_cartesian_time(ax, x_min: datetime, x_max: datetime) → None

Shade night windows as vertical spans on a calendar time x-axis.

Used by plot_timeseries to shade each nightly period.

shade_polar(ax, rmin: float, rmax: float) → None

Shade night sectors on a polar (clockplot / hourmap) axis.

Parameters:

ax:: Polar Axes with clockwise direction and North at top (as set by clock24_plot_commons).
rmin, rmax:: Radial extent of the shaded wedge.

msnoise.plots.psd_rms.load_rms(result, seed_ids: list[str] | None = None, *, psd_id: int = 1, psd_rms_id: int = 1) → dict[str, pandas.core.frame.DataFrame]

Load PSD-RMS results via an MSNoiseResult.

This is the preferred entry point for notebooks and scripts. It delegates all path resolution to MSNoiseResult.get_psd_rms(), which correctly handles the psd_N/psd_rms_N/_output/ lineage without hard-coding step names or output folders.

Parameters:

result:

An MSNoiseResult that contains psd_rms in its lineage, obtained via:

from msnoise.results import MSNoiseResult
r = MSNoiseResult.from_ids(db, psd=1, psd_rms=1)

seed_ids:

Optional list of SEED IDs to load (e.g. ["BE.UCC..HHZ"]). When None (default) every station found on disk is returned.

Returns:

dict: Mapping seed_id -> DataFrame (columns = band labels, index = DatetimeIndex in UTC). Stations with no data on disk are silently omitted.

Examples

Preferred – MSNoiseResult:

>>> from msnoise.core.db import connect
>>> from msnoise.results import MSNoiseResult
>>> from msnoise.plots.psd_rms import load_rms
>>> db = connect()
>>> r = MSNoiseResult.from_ids(db, psd=1, psd_rms=1)
>>> data = load_rms(r)                   # all stations auto-discovered
>>> data = load_rms(r, ["BE.UCC..HHZ"])  # single station

msnoise.plots.psd_rms.plot_timeseries(data: dict[str, pandas.core.frame.DataFrame], band: str | None = None, scale: float = 1000000000.0, unit: str = 'nm', annotations: dict | None = None, time_zone: str = 'UTC', resample_freq: str = '30min', agg_func: str | Callable = 'mean', day_night: DayNightWindow | None = None, logo: str | None = None, show: bool = True, outfile: str | None = None) → Figure

Time-series plot of RMS amplitudes for one or multiple stations.

Parameters:

data:: dict {seed_id: DataFrame} as returned by load_rms().
band:: Frequency band label (column name in the DataFrame, e.g. "1.0-10.0"). Defaults to the first available band.
scale:: Multiply amplitudes before display (default 1e9 -> nm for DISP).
unit:: Y-axis unit label (default "nm").
annotations:: Optional dict {date_string: label} for vertical event lines.
time_zone:: Time zone for x-axis localisation (default "UTC").
resample_freq:: Resampling frequency string (default "30min").
agg_func:: Aggregation function applied to each resampled bin. Accepts a string ("mean", "median", "max", …) or any callable (e.g. np.nanmedian, lambda s: s.quantile(0.1)). Default "mean".
day_night:: DayNightWindow defining local daytime/nighttime hours. Controls: (1) the daytime median overlay time window and label, and (2) night shading applied as vertical spans. Defaults to DEFAULT_DAY_NIGHT (07:00-19:00). Pass DayNightWindow(day_start=0, day_end=24) to disable shading.
logo:: URL or path to a logo image to embed bottom-left (optional).
show:: Call plt.show() when done.
outfile:: Save figure to this path.

Returns:

matplotlib.figure.Figure

msnoise.plots.psd_rms.plot_clockplot(data: dict[str, pandas.core.frame.DataFrame], band: str | None = None, scale: float = 1000000000.0, unit: str = 'nm', split_date: str | None = None, time_zone: str = 'UTC', resample_freq: str = '30min', agg_func: str | Callable = 'mean', day_night: DayNightWindow | None = None, show: bool = True, outfile: str | None = None) → Figure

Polar 24-hour clock plot of median RMS per weekday / hour.

When split_date is provided two panels are drawn (before / after), useful for comparing noise regimes across an event or intervention.

Parameters:

data:: dict {seed_id: DataFrame} as returned by load_rms(). Only the first station is used; for multi-station comparisons build a side-by-side figure using stack_wday_time() directly (see the multi-station notebook example).
band:: Frequency band label.
scale:: Amplitude scale factor (default 1e9 -> nm).
unit:: Unit label for radial tick labels.
split_date:: ISO date string ("YYYY-MM-DD") to split the data. When None a single panel is drawn covering the full time range.
time_zone:: Local time zone for hour-of-day grouping (default "UTC").
resample_freq:: Resampling frequency string (default "30min").
agg_func:: Aggregation function for resampled bins ("mean", "median", callable, …). Default "mean".
day_night:: DayNightWindow for shading night sectors on the polar axes. Defaults to DEFAULT_DAY_NIGHT (07:00-19:00).
show:: Call plt.show().
outfile:: Save figure to this path.

Returns:

matplotlib.figure.Figure

msnoise.plots.psd_rms.plot_hourmap(data: dict[str, pandas.core.frame.DataFrame], band: str | None = None, scale: float = 1000000000.0, unit: str = 'nm', annotations: dict | None = None, time_zone: str = 'UTC', resample_freq: str = '30min', agg_func: str | Callable = 'mean', day_night: DayNightWindow | None = None, show: bool = True, outfile: str | None = None) → Figure

Polar hour-map: radial axis = elapsed days, angular axis = hour of day.

Equivalent to SeismoRMS clockmap / hourmap. Best for datasets up to ~1-2 years; beyond that the polar readability degrades and plot_gridmap() is preferable.

Parameters:

data:: dict {seed_id: DataFrame} as returned by load_rms().
band:: Frequency band label.
scale / unit:: Amplitude scale and unit label.
annotations:: Optional dict {date_str: label} to mark events as radial markers.
time_zone:: Local time zone.
resample_freq:: Resampling frequency.
agg_func:: Aggregation function for resampled bins ("mean", "median", callable, …). Default "mean".
day_night:: DayNightWindow for shading night sectors on the polar axes. Defaults to DEFAULT_DAY_NIGHT (07:00-19:00).
show / outfile:: Display / save options.

Returns:

matplotlib.figure.Figure

msnoise.plots.psd_rms.plot_gridmap(data: dict[str, pandas.core.frame.DataFrame], band: str | None = None, scale: float = 1000000000.0, unit: str = 'nm', annotations: dict | None = None, time_zone: str = 'UTC', resample_freq: str = '30min', agg_func: str | Callable = 'mean', day_night: DayNightWindow | None = None, show: bool = True, outfile: str | None = None) → Figure

Cartesian grid-map: x = calendar date, y = hour of day.

Equivalent to SeismoRMS gridmap. Handles long time series (years) better than plot_hourmap().

Parameters:

data:: dict {seed_id: DataFrame} as returned by load_rms().
band:: Frequency band label.
scale / unit:: Amplitude scale and unit label.
annotations:: Optional dict {date_str: label} for event markers.
time_zone:: Local time zone.
resample_freq:: Resampling frequency.
agg_func:: Aggregation function for resampled bins ("mean", "median", callable, …). Default "mean".
day_night:: DayNightWindow for shading night bands on the hour-of-day y-axis. Defaults to DEFAULT_DAY_NIGHT (07:00-19:00).
show / outfile:: Display / save options.

Returns:

matplotlib.figure.Figure

msnoise.plots.psd_rms.plot_dailyplot(data: dict[str, pandas.core.frame.DataFrame], band: str | None = None, scale: float = 1000000000.0, unit: str = 'nm', split_date: str | None = None, time_zone: str = 'UTC', resample_freq: str = '30min', agg_func: str | Callable = 'mean', day_night: DayNightWindow | None = None, show: bool = True, outfile: str | None = None) → Figure

Hour-of-day stacked plot, one curve per weekday.

Solid curves cover the full dataset (or the period before split_date when provided); dashed curves represent the period after split_date.

Parameters:

data:: dict {seed_id: DataFrame} as returned by load_rms().
band:: Frequency band label.
scale / unit:: Amplitude scale and unit label.
split_date:: Optional date string to draw a pre/post comparison (solid vs dashed).
time_zone:: Local time zone for hour-of-day grouping.
resample_freq:: Resampling frequency.
agg_func:: Aggregation function for resampled bins ("mean", "median", callable, …). Default "mean".
day_night:: DayNightWindow for shading night bands on the hour-of-day x-axis. Defaults to DEFAULT_DAY_NIGHT (07:00-19:00).
show / outfile:: Display / save options.

Returns:

matplotlib.figure.Figure

msnoise.plots.psd_rms.main(seed_ids: list[str], psd_id: int = 1, psd_rms_id: int = 1, plot_type: str = 'timeseries', band: str | None = None, scale: float = 1000000000.0, unit: str = 'nm', time_zone: str = 'UTC', day_start: float = 7.0, day_end: float = 19.0, split_date: str | None = None, annotations: dict | None = None, outfile: str | None = None, show: bool = True, loglevel: str = 'INFO') → None

CLI/script entry point: load RMS data and dispatch to plot function(s).

Constructs an MSNoiseResult from the database, loads data via load_rms(), then dispatches to the requested plot function(s).

Parameters:

seed_ids:: List of SEED IDs (e.g. ["BE.UCC..HHZ"]). Empty list -> all stations found on disk for this lineage.
psd_id:: Config-set number for the psd step (default 1).
psd_rms_id:: Config-set number for the psd_rms step (default 1).
plot_type:: One of "timeseries", "clockplot", "hourmap", "gridmap", "dailyplot", or "all".
band:: Frequency band column label (e.g. "1.0-10.0").
scale / unit:: Amplitude scale and label.
time_zone:: Time zone string for local-time plots.
day_start:: Start of daytime in decimal hours (default 7.0).
day_end:: End of daytime in decimal hours (default 19.0).
split_date:: Date string for before/after split (clockplot, dailyplot).
annotations:: Dict {date_str: label} for event markers (timeseries, hourmap, gridmap).
outfile:: Base filename for saved figures; a _<type> suffix is inserted before the extension for each type when plot_type="all".
show:: Call plt.show().
loglevel:: Logging level string.

msnoise.plots.psd_rms.localize_tz_and_reindex(df: DataFrame, freq: str = '15min', time_zone: str = 'UTC', agg_func: str | Callable = 'mean') → DataFrame

Convert a UTC-indexed DataFrame to time_zone, resample to freq, and aggregate with agg_func.

Parameters:

df:

DataFrame with a timezone-naive UTC DatetimeIndex.

freq:

Pandas offset string for resampling (default "15min").

time_zone:

Target timezone string (default "UTC").

agg_func:

Aggregation function applied after resampling. Can be:

a string supported by agg() ("mean", "median", "max", "min", "std", …)
any callable that accepts a Series and returns a scalar (e.g. np.nanmedian, lambda s: s.quantile(0.1)).

Default "mean" preserves the original behaviour.

Returns:

DataFrame

msnoise.plots.psd_rms.pivot_for_hourmap(data: DataFrame, columns: str = 'angles') → DataFrame

Pivot a single-column RMS DataFrame into a (days x time) matrix.

Parameters:

data:: DataFrame with a DatetimeIndex and a single RMS column (already scaled to the desired display unit).
columns:: "angles" (default) converts the time axis to radians 0-2pi for polar pcolormesh; "hours" leaves them as float hours 0-24 for the Cartesian grid-map.

Returns:

DataFrame: Rows = elapsed integer days since the first sample; columns = hour or angle values.

msnoise.plots.psd_rms.stack_wday_time(df: DataFrame, scale: float = 1.0) → DataFrame

Median-stack a single-column RMS DataFrame into a (hour x weekday) table.

Parameters:

df:: DataFrame with a DatetimeIndex and a single column. The column name is ignored — only the first column is used.
scale:: Multiply all values by this factor (default 1.0).

Returns:

DataFrame: Index = float hour-of-day; columns = weekday names ordered Monday to Sunday.

msnoise.plots.psd_rms.radial_hours(N: int) → ndarray

Return N evenly-spaced angles for a 24-hour clock plot (closed polygon).

The last element equals the first so that DataFrame.plot() closes the polygon around the clock face.

msnoise.plots.psd_rms.clock24_plot_commons(ax, unit: str = 'nm') → None: Apply standard 24-hour polar axis decoration in-place.

Stretching dv/v 

Plot dv/v from the Stretching method.

Reads pre-aggregated network dv/v from the stretching_dvv step output written by msnoise.s07_compute_dvv.

Example:

msnoise cc dtt plot dvvs will plot all defaults.

msnoise cc dtt plot dvvs -f 2 -m 1 -c ZZ will plot filter 2, mov_stack 1, component ZZ.

msnoise.plots.stretching_dvv.main(mov_stackid=None, components='ZZ', pair_type='CC', filterid=1, stretchingid=1, dvvid=1, pairs=None, show=False, outfile=None, loglevel='INFO')

Plot network-level dv/v from the stretching aggregate.

Requires the stretching_dvv step to have been run first (msnoise dtt compute_stretching_dvv).

Parameters:

mov_stackid – 1-based index into params.stack.mov_stack. None or 0 plots all moving-stack windows.
components – Component pair string, comma-separated for multiple.
filterid – Filter set number.
stretchingid – Stretching config set number.
dvvid – stretching_dvv config set number.
show – Display the figure interactively.
outfile – Save path (? = auto-name).
loglevel – Logging verbosity.

dt/t Timing 

This plot shows the per-pair and network-mean dt/t timeseries from the .. include:: /clickhelp/msnoise-cc-dtt-plot-timing.rst

MWCS-DTT step, equivalent to the old timing plot but reading from the lineage-aware NetCDF store.

Example:

msnoise cc dtt plot timing will plot all defaults:

msnoise.plots.timing.main(mov_stackid=None, dttname='m', components='ZZ', filterid=1, mwcsid=1, dttid=1, pairs=None, showALL=False, show=False, outfile=None, loglevel='INFO')

Plot per-pair and network-mean dt/t timeseries.

Parameters:

mov_stackid – 1-based index into params.stack.mov_stack (0/None = all).
dttname – DTT column to display: 'm' (slope = dt/t) or 'm0' (zero-intercept slope).
components – Component pair string.
filterid – Filter set number.
mwcsid – MWCS set number.
dttid – MWCS-DTT set number.
pairs – List of 'NET.STA.LOC:NET.STA.LOC' strings to highlight.
showALL – Unused (kept for signature compatibility).
show – Display interactively.
outfile – Save path (? = auto-name).
loglevel – Logging verbosity.

PSD-RMS 

PSD-RMS Visualisation 

Plots derived from the psd_rms workflow step: time-series, clock plots, hour-maps, grid-maps, and daily stacks. Ported and adapted from the SeismoRMS / SeismoSocialDistancing project (https://github.com/ThomasLecocq/SeismoRMS).

CLI usage:

msnoise qc plot_psd_rms BE.UCC..HHZ --type timeseries --band 1.0-10.0
msnoise qc plot_psd_rms BE.UCC..HHZ --type clockplot  --timezone Europe/Brussels
msnoise qc plot_psd_rms BE.UCC..HHZ --type hourmap
msnoise qc plot_psd_rms BE.UCC..HHZ --type gridmap
msnoise qc plot_psd_rms BE.UCC..HHZ --type dailyplot

Notebook usage:

from msnoise.core.db import connect
from msnoise.results import MSNoiseResult
from msnoise.plots.psd_rms import load_rms, plot_timeseries, plot_clockplot

db = connect()
r = MSNoiseResult.from_ids(db, psd=1, psd_rms=1)
data = load_rms(r, ["BE.UCC..HHZ"])
plot_timeseries(data, band="1.0-10.0")

class msnoise.plots.psd_rms.DayNightWindow(day_start: float = 7.0, day_end: float = 19.0, day_color: str = '#fffacd', night_color: str = '#cce5ff', day_alpha: float = 0.15, night_alpha: float = 0.12)

Define the local “daytime” and “nighttime” hour windows.

Used by all plot functions to:

draw the daytime median overlay on time-series plots,
shade night hours on clockplots, gridmaps, and dailyplots,
shade night sectors on hourmaps.

Hours are expressed as floats in 0..24 in local time (after timezone conversion). The window wraps midnight correctly, so day_start=22 with day_end=6 defines a “daytime” from 22:00 to 06:00 (e.g. a city station where the quiet hours are at night).

Parameters:

day_start:: Start of daytime in decimal hours (default 7.0 = 07:00 local).
day_end:: End of daytime in decimal hours (default 19.0 = 19:00 local).
day_color:: Matplotlib colour for daytime shading (default light yellow).
night_color:: Matplotlib colour for nighttime shading (default light blue).
day_alpha:: Alpha for daytime shading (default 0.15).
night_alpha:: Alpha for nighttime shading (default 0.12).

Examples

>>> # Standard business-hours window
>>> dnw = DayNightWindow(day_start=8, day_end=18)

>>> # Seismological quiet window: anthropogenic noise lowest 22:00-05:00
>>> dnw = DayNightWindow(day_start=5, day_end=22)

>>> # Marine station: no meaningful day/night -- disable shading
>>> dnw = DayNightWindow(day_start=0, day_end=24)

day_start: float = 7.0

day_end: float = 19.0

day_color: str = '#fffacd'

night_color: str = '#cce5ff'

day_alpha: float = 0.15

night_alpha: float = 0.12

property day_label: str: Human-readable label, e.g. ‘7-19 h’.

shade_cartesian_hour(ax) → None

Shade day / night horizontal bands on a Cartesian hour-of-day y-axis.

Assumes the y-axis represents hours 0-24 (gridmap).

shade_cartesian_time(ax, x_min: datetime, x_max: datetime) → None

Shade night windows as vertical spans on a calendar time x-axis.

Used by plot_timeseries to shade each nightly period.

shade_polar(ax, rmin: float, rmax: float) → None

Shade night sectors on a polar (clockplot / hourmap) axis.

Parameters:

ax:: Polar Axes with clockwise direction and North at top (as set by clock24_plot_commons).
rmin, rmax:: Radial extent of the shaded wedge.

msnoise.plots.psd_rms.load_rms(result, seed_ids: list[str] | None = None, *, psd_id: int = 1, psd_rms_id: int = 1) → dict[str, pandas.core.frame.DataFrame]

Load PSD-RMS results via an MSNoiseResult.

This is the preferred entry point for notebooks and scripts. It delegates all path resolution to MSNoiseResult.get_psd_rms(), which correctly handles the psd_N/psd_rms_N/_output/ lineage without hard-coding step names or output folders.

Parameters:

result:

An MSNoiseResult that contains psd_rms in its lineage, obtained via:

from msnoise.results import MSNoiseResult
r = MSNoiseResult.from_ids(db, psd=1, psd_rms=1)

seed_ids:

Optional list of SEED IDs to load (e.g. ["BE.UCC..HHZ"]). When None (default) every station found on disk is returned.

Returns:

dict: Mapping seed_id -> DataFrame (columns = band labels, index = DatetimeIndex in UTC). Stations with no data on disk are silently omitted.

Examples

Preferred – MSNoiseResult:

>>> from msnoise.core.db import connect
>>> from msnoise.results import MSNoiseResult
>>> from msnoise.plots.psd_rms import load_rms
>>> db = connect()
>>> r = MSNoiseResult.from_ids(db, psd=1, psd_rms=1)
>>> data = load_rms(r)                   # all stations auto-discovered
>>> data = load_rms(r, ["BE.UCC..HHZ"])  # single station

msnoise.plots.psd_rms.plot_timeseries(data: dict[str, pandas.core.frame.DataFrame], band: str | None = None, scale: float = 1000000000.0, unit: str = 'nm', annotations: dict | None = None, time_zone: str = 'UTC', resample_freq: str = '30min', agg_func: str | Callable = 'mean', day_night: DayNightWindow | None = None, logo: str | None = None, show: bool = True, outfile: str | None = None) → Figure

Time-series plot of RMS amplitudes for one or multiple stations.

Parameters:

data:: dict {seed_id: DataFrame} as returned by load_rms().
band:: Frequency band label (column name in the DataFrame, e.g. "1.0-10.0"). Defaults to the first available band.
scale:: Multiply amplitudes before display (default 1e9 -> nm for DISP).
unit:: Y-axis unit label (default "nm").
annotations:: Optional dict {date_string: label} for vertical event lines.
time_zone:: Time zone for x-axis localisation (default "UTC").
resample_freq:: Resampling frequency string (default "30min").
agg_func:: Aggregation function applied to each resampled bin. Accepts a string ("mean", "median", "max", …) or any callable (e.g. np.nanmedian, lambda s: s.quantile(0.1)). Default "mean".
day_night:: DayNightWindow defining local daytime/nighttime hours. Controls: (1) the daytime median overlay time window and label, and (2) night shading applied as vertical spans. Defaults to DEFAULT_DAY_NIGHT (07:00-19:00). Pass DayNightWindow(day_start=0, day_end=24) to disable shading.
logo:: URL or path to a logo image to embed bottom-left (optional).
show:: Call plt.show() when done.
outfile:: Save figure to this path.

Returns:

matplotlib.figure.Figure

msnoise.plots.psd_rms.plot_clockplot(data: dict[str, pandas.core.frame.DataFrame], band: str | None = None, scale: float = 1000000000.0, unit: str = 'nm', split_date: str | None = None, time_zone: str = 'UTC', resample_freq: str = '30min', agg_func: str | Callable = 'mean', day_night: DayNightWindow | None = None, show: bool = True, outfile: str | None = None) → Figure

Polar 24-hour clock plot of median RMS per weekday / hour.

When split_date is provided two panels are drawn (before / after), useful for comparing noise regimes across an event or intervention.

Parameters:

data:: dict {seed_id: DataFrame} as returned by load_rms(). Only the first station is used; for multi-station comparisons build a side-by-side figure using stack_wday_time() directly (see the multi-station notebook example).
band:: Frequency band label.
scale:: Amplitude scale factor (default 1e9 -> nm).
unit:: Unit label for radial tick labels.
split_date:: ISO date string ("YYYY-MM-DD") to split the data. When None a single panel is drawn covering the full time range.
time_zone:: Local time zone for hour-of-day grouping (default "UTC").
resample_freq:: Resampling frequency string (default "30min").
agg_func:: Aggregation function for resampled bins ("mean", "median", callable, …). Default "mean".
day_night:: DayNightWindow for shading night sectors on the polar axes. Defaults to DEFAULT_DAY_NIGHT (07:00-19:00).
show:: Call plt.show().
outfile:: Save figure to this path.

Returns:

matplotlib.figure.Figure

msnoise.plots.psd_rms.plot_hourmap(data: dict[str, pandas.core.frame.DataFrame], band: str | None = None, scale: float = 1000000000.0, unit: str = 'nm', annotations: dict | None = None, time_zone: str = 'UTC', resample_freq: str = '30min', agg_func: str | Callable = 'mean', day_night: DayNightWindow | None = None, show: bool = True, outfile: str | None = None) → Figure

Polar hour-map: radial axis = elapsed days, angular axis = hour of day.

Equivalent to SeismoRMS clockmap / hourmap. Best for datasets up to ~1-2 years; beyond that the polar readability degrades and plot_gridmap() is preferable.

Parameters:

data:: dict {seed_id: DataFrame} as returned by load_rms().
band:: Frequency band label.
scale / unit:: Amplitude scale and unit label.
annotations:: Optional dict {date_str: label} to mark events as radial markers.
time_zone:: Local time zone.
resample_freq:: Resampling frequency.
agg_func:: Aggregation function for resampled bins ("mean", "median", callable, …). Default "mean".
day_night:: DayNightWindow for shading night sectors on the polar axes. Defaults to DEFAULT_DAY_NIGHT (07:00-19:00).
show / outfile:: Display / save options.

Returns:

matplotlib.figure.Figure

msnoise.plots.psd_rms.plot_gridmap(data: dict[str, pandas.core.frame.DataFrame], band: str | None = None, scale: float = 1000000000.0, unit: str = 'nm', annotations: dict | None = None, time_zone: str = 'UTC', resample_freq: str = '30min', agg_func: str | Callable = 'mean', day_night: DayNightWindow | None = None, show: bool = True, outfile: str | None = None) → Figure

Cartesian grid-map: x = calendar date, y = hour of day.

Equivalent to SeismoRMS gridmap. Handles long time series (years) better than plot_hourmap().

Parameters:

data:: dict {seed_id: DataFrame} as returned by load_rms().
band:: Frequency band label.
scale / unit:: Amplitude scale and unit label.
annotations:: Optional dict {date_str: label} for event markers.
time_zone:: Local time zone.
resample_freq:: Resampling frequency.
agg_func:: Aggregation function for resampled bins ("mean", "median", callable, …). Default "mean".
day_night:: DayNightWindow for shading night bands on the hour-of-day y-axis. Defaults to DEFAULT_DAY_NIGHT (07:00-19:00).
show / outfile:: Display / save options.

Returns:

matplotlib.figure.Figure

msnoise.plots.psd_rms.plot_dailyplot(data: dict[str, pandas.core.frame.DataFrame], band: str | None = None, scale: float = 1000000000.0, unit: str = 'nm', split_date: str | None = None, time_zone: str = 'UTC', resample_freq: str = '30min', agg_func: str | Callable = 'mean', day_night: DayNightWindow | None = None, show: bool = True, outfile: str | None = None) → Figure

Hour-of-day stacked plot, one curve per weekday.

Solid curves cover the full dataset (or the period before split_date when provided); dashed curves represent the period after split_date.

Parameters:

data:: dict {seed_id: DataFrame} as returned by load_rms().
band:: Frequency band label.
scale / unit:: Amplitude scale and unit label.
split_date:: Optional date string to draw a pre/post comparison (solid vs dashed).
time_zone:: Local time zone for hour-of-day grouping.
resample_freq:: Resampling frequency.
agg_func:: Aggregation function for resampled bins ("mean", "median", callable, …). Default "mean".
day_night:: DayNightWindow for shading night bands on the hour-of-day x-axis. Defaults to DEFAULT_DAY_NIGHT (07:00-19:00).
show / outfile:: Display / save options.

Returns:

matplotlib.figure.Figure

msnoise.plots.psd_rms.main(seed_ids: list[str], psd_id: int = 1, psd_rms_id: int = 1, plot_type: str = 'timeseries', band: str | None = None, scale: float = 1000000000.0, unit: str = 'nm', time_zone: str = 'UTC', day_start: float = 7.0, day_end: float = 19.0, split_date: str | None = None, annotations: dict | None = None, outfile: str | None = None, show: bool = True, loglevel: str = 'INFO') → None

CLI/script entry point: load RMS data and dispatch to plot function(s).

Constructs an MSNoiseResult from the database, loads data via load_rms(), then dispatches to the requested plot function(s).

Parameters:

seed_ids:: List of SEED IDs (e.g. ["BE.UCC..HHZ"]). Empty list -> all stations found on disk for this lineage.
psd_id:: Config-set number for the psd step (default 1).
psd_rms_id:: Config-set number for the psd_rms step (default 1).
plot_type:: One of "timeseries", "clockplot", "hourmap", "gridmap", "dailyplot", or "all".
band:: Frequency band column label (e.g. "1.0-10.0").
scale / unit:: Amplitude scale and label.
time_zone:: Time zone string for local-time plots.
day_start:: Start of daytime in decimal hours (default 7.0).
day_end:: End of daytime in decimal hours (default 19.0).
split_date:: Date string for before/after split (clockplot, dailyplot).
annotations:: Dict {date_str: label} for event markers (timeseries, hourmap, gridmap).
outfile:: Base filename for saved figures; a _<type> suffix is inserted before the extension for each type when plot_type="all".
show:: Call plt.show().
loglevel:: Logging level string.

msnoise.plots.psd_rms.localize_tz_and_reindex(df: DataFrame, freq: str = '15min', time_zone: str = 'UTC', agg_func: str | Callable = 'mean') → DataFrame

Convert a UTC-indexed DataFrame to time_zone, resample to freq, and aggregate with agg_func.

Parameters:

df:

DataFrame with a timezone-naive UTC DatetimeIndex.

freq:

Pandas offset string for resampling (default "15min").

time_zone:

Target timezone string (default "UTC").

agg_func:

Aggregation function applied after resampling. Can be:

a string supported by agg() ("mean", "median", "max", "min", "std", …)
any callable that accepts a Series and returns a scalar (e.g. np.nanmedian, lambda s: s.quantile(0.1)).

Default "mean" preserves the original behaviour.

Returns:

DataFrame

msnoise.plots.psd_rms.pivot_for_hourmap(data: DataFrame, columns: str = 'angles') → DataFrame

Pivot a single-column RMS DataFrame into a (days x time) matrix.

Parameters:

data:: DataFrame with a DatetimeIndex and a single RMS column (already scaled to the desired display unit).
columns:: "angles" (default) converts the time axis to radians 0-2pi for polar pcolormesh; "hours" leaves them as float hours 0-24 for the Cartesian grid-map.

Returns:

DataFrame: Rows = elapsed integer days since the first sample; columns = hour or angle values.

msnoise.plots.psd_rms.stack_wday_time(df: DataFrame, scale: float = 1.0) → DataFrame

Median-stack a single-column RMS DataFrame into a (hour x weekday) table.

Parameters:

df:: DataFrame with a DatetimeIndex and a single column. The column name is ignored — only the first column is used.
scale:: Multiply all values by this factor (default 1.0).

Returns:

DataFrame: Index = float hour-of-day; columns = weekday names ordered Monday to Sunday.

msnoise.plots.psd_rms.radial_hours(N: int) → ndarray

Return N evenly-spaced angles for a 24-hour clock plot (closed polygon).

The last element equals the first so that DataFrame.plot() closes the polygon around the clock face.

msnoise.plots.psd_rms.clock24_plot_commons(ax, unit: str = 'nm') → None: Apply standard 24-hour polar axis decoration in-place.

Stretching dv/v 

Plot dv/v from the Stretching method.

Reads pre-aggregated network dv/v from the stretching_dvv step output written by msnoise.s07_compute_dvv.

Example:

msnoise cc dtt plot dvvs will plot all defaults.

msnoise cc dtt plot dvvs -f 2 -m 1 -c ZZ will plot filter 2, mov_stack 1, component ZZ.

msnoise.plots.stretching_dvv.main(mov_stackid=None, components='ZZ', pair_type='CC', filterid=1, stretchingid=1, dvvid=1, pairs=None, show=False, outfile=None, loglevel='INFO')

Plot network-level dv/v from the stretching aggregate.

Requires the stretching_dvv step to have been run first (msnoise dtt compute_stretching_dvv).

Parameters:

mov_stackid – 1-based index into params.stack.mov_stack. None or 0 plots all moving-stack windows.
components – Component pair string, comma-separated for multiple.
filterid – Filter set number.
stretchingid – Stretching config set number.
dvvid – stretching_dvv config set number.
show – Display the figure interactively.
outfile – Save path (? = auto-name).
loglevel – Logging verbosity.

dt/t Timing 

This plot shows the per-pair and network-mean dt/t timeseries from the .. include:: /clickhelp/msnoise-cc-dtt-plot-timing.rst

MWCS-DTT step, equivalent to the old timing plot but reading from the lineage-aware NetCDF store.

Example:

msnoise cc dtt plot timing will plot all defaults:

msnoise.plots.timing.main(mov_stackid=None, dttname='m', components='ZZ', filterid=1, mwcsid=1, dttid=1, pairs=None, showALL=False, show=False, outfile=None, loglevel='INFO')

Plot per-pair and network-mean dt/t timeseries.

Parameters:

mov_stackid – 1-based index into params.stack.mov_stack (0/None = all).
dttname – DTT column to display: 'm' (slope = dt/t) or 'm0' (zero-intercept slope).
components – Component pair string.
filterid – Filter set number.
mwcsid – MWCS set number.
dttid – MWCS-DTT set number.
pairs – List of 'NET.STA.LOC:NET.STA.LOC' strings to highlight.
showALL – Unused (kept for signature compatibility).
show – Display interactively.
outfile – Save path (? = auto-name).
loglevel – Logging verbosity.