Figure.sac: Plot seismograms in SAC format

[Chuan1937]

This issue serves as the central place for discussing and tracking the implementation of the sac method in PyGMT. The issue will be closed when the initial implementation is complete. Progress is tracked at PyGMT: Wrapping GMT modules.

Documentation

• GMT: https://docs.generic-mapping-tools.org/dev/supplements/seis/sac.html
• GMT.jl: https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/sac
• PyGMT: https://www.pygmt.org/dev/api/generated/pygmt.Figure.sac.html

GMT Option Flags and Modifiers

☑️: Implemented; ⬜: To be implemented/discussed; Strikethrough: Won't implement.

• -B: frame
• -J: projection
• -R: region
• -C: time_window
• -D: offset
• -E: profile
• -F: preprocess
• -G: fill
• -M: amplitude_scale
• -Q: vertical
• -S: time_scale
• -T: reduction_velocity, time_shift, time_reference
• -W: pen
• -V: verbose
• -X/-Y: Use Figure.shift_origin instead.
• --PAR=value: Use pygmt.config instead.

Related GMT configurations

List any related GMT configurations that may affect the behavior.

Notes on Input Formats

The GMT sac module accepts SAC waveform files as input. Since ObsPy is widely used for seismic waveform processing in Python, support for ObsPy Trace/Stream objects could also be considered.

For example:

from obspy import read

trace = read("example.sac")[0]

fig.sac(spec=trace)

Linked Pull Requests

• Initial feature implementation(Figure.sac: Plot seismograms in SAC format #4854)
• Add a tutorial or gallery example

Related Issues and Discussions

Add links to related wrapper discussions, API design threads, or upstream GMT changes here.

[seisman]

There were some discussions in #967.

[seisman]

I'm re-reading the discussions in #967. Both #967 and this issue propose supporting ObsPy's Trace/Stream objects. It sounds like a good idea, but there are still some technical challenges:

1. Some features in the sac module require time markers like T0-T9, which are not available in other data formats (e.g., miniseed). So the available functionality depends on the data format.
2. Even for Trace/Stream objects created by reading SAC files, we still need to write them to temporary disk files, because GMT's virtualfile mechanism only supports data tables, grids, and images, not SAC files.

So, I feel we should limit the Figure.sac method to SAC files only. We may explore a more general Figure.waveform method for plotting Trace/Stream instead.

[Chuan1937]

I understand. So PR will only complete the warp of the sac first.