Command reference

squirrel spectrogram

Calculate multi-resolution spectrograms.

squirrel spectrogram

usage: squirrel spectrogram [--help] [--loglevel LEVEL] [--progress DEST]
                            [--threads-loading INT] [--add PATH [PATH ...]]
                            [--include REGEX] [--exclude REGEX] [--optimistic]
                            [--format FORMAT] [--add-only KINDS]
                            [--persistent NAME] [--samples-block N]
                            [--dataset FILE] [--upgrade-storage]
                            [--kinds KINDS] [--codes CODES]
                            [--codes-exclude CODES] [--tmin TIME] [--tmax TIME]
                            [--time TIME] [--block-size-exponent INT]
                            [--levels INT] [--weighting-exponent INT]
                            [--interpolation {cos,nearest_neighbor}]
                            [--tinc DURATION] [--no-snap-window]
                            [--show-construction] [--quantity QUANTITY]
                            [--out-storage-path PATH] [--force] [--append]
                            [--merge]

Compute spectrograms of the selected waveforms and store them as carpets. Spectrograms with different FFT block lengths are merged into one, so that each frequency is represented with a suitable time resolution (see --levels, --block-size-exponent). The instrument response is removed to get the spectra of the physical quantity given with --quantity, which requires response information, e.g. from StationXML files. The values are natural logarithms of spectral power. Output codes get MS appended to the extra code. Output files are organized in time windows of length --tinc.

A directory layout which works well with this and the related commands: data/raw/ for the waveforms, meta/stations.xml for station and response metadata, data/spectrograms/main/ for the output of this command and data/spectrograms/cascade/ for overviews created with squirrel cascade.

Example: squirrel spectrogram --add data/raw meta/stations.xml --out-storage-path data/spectrograms/main – compute spectrograms of all waveforms in data/raw/.

Next steps: create overviews with squirrel cascade --add data/spectrograms/main --out-storage-path data/spectrograms/cascade and browse the spectrograms with squirrel service --add data/spectrograms.

Note: spectrograms and cascades for continuous recordings use a lot of disk space. Use --tmin, --tmax and --codes to restrict the computation to certain time spans or channels.

Options:

--block-size-exponent INT

Set block size used to calculate FFTs as a power-of-two exponent. Default: 10 (2**10 = 1024).

--levels INT

Set number of levels for the multi-resolution spectrograms.

--weighting-exponent INT

Set exponent for the weighting function which is used to merge the multi-resolution spectrogram components.

--interpolation {cos,nearest_neighbor}

Set interpolation method for multi-resolution spectrogram stitching. Choices: cos, nearest_neighbor, Default: cos

--tinc DURATION

Set time length of output files [s].

--no-snap-window

Do not snap windows to multiples of the processing interval

--show-construction

Show multi-resolution spectrogram construction plots (for debugging purposes).

--quantity QUANTITY

Apply instrument correction for given QUANTITY. Compatible instrument response information must be available. Set to counts to disable. Choices: acceleration, velocity, displacement, pressure, rotation_displacement, rotation_velocity, rotation_acceleration, temperature, voltage, counts. Default: velocity.

--out-storage-path PATH

Store output in directory PATH.

--force

Force overwriting of existing files.

--append

Append to existing files. Checks are performed to ensure that appended data has no overlap with already existing data.

--merge

Merge with existing data in files.

General options:

--help, -h

Show this help message and exit.

--loglevel LEVEL

Set logger level. Choices: critical, error, warning, info, debug. Default: info.

--progress DEST

Set how progress status is reported. Choices: terminal, log, off. Default: terminal.

--threads-loading INT

Set number of threads used in file content loading/decoding. Default: 1

Data collection options:

--add, -a PATH [PATH ...]

Add files and directories with waveforms, metadata and events. Content is indexed and added to the temporary (default) or persistent (see --persistent) data selection.

--include REGEX

Only include files whose paths match the regular expression REGEX. Examples: --include='\.MSEED$' would only match files ending with .MSEED. --include='\.BH[EN]\.' would match paths containing .BHE. or .BHN.. --include='/2011/' would match paths with a subdirectory 2011 in their path hierarchy.

--exclude REGEX

Only include files whose paths do not match the regular expression REGEX. Examples: --exclude='/\.DS_Store/' would exclude anything inside any .DS_Store subdirectory.

--optimistic, -o

Disable checking file modification times for faster startup.

--format, -f FORMAT

Assume input files are of given FORMAT. Choices: datacube, hdf5_optodas, mseed, pyrocko_events, pyrocko_stations, rug, sac, spickle, sqlite-ELK1, stationxml, tdms_idas, virtual, yaff, yaml. Default: detect.

--add-only KINDS

Restrict meta-data scanning to given content kinds. KINDS is a comma-separated list of content kinds. Choices: waveform, station, channel, response, event, carpet, waveform_promise. By default, all content kinds are indexed.

--persistent, -p NAME

Create/use persistent selection with given NAME. Persistent selections can be used to speed up startup of Squirrel-based applications.

--samples-block N

When downloading data, use blocks with approximately N samples. Default: 100000

--dataset, -d FILE

Add files, directories and remote sources from dataset description file. This option can be repeated to add multiple datasets. Run squirrel template to obtain examples of dataset description files.

--upgrade-storage

Upgrade storage layout of cached data to latest version.

Data query options:

--kinds KINDS

Content kinds to query. KINDS is a comma-separated list of content kinds. Choices: waveform, station, channel, response, event, carpet, waveform_promise. By default, all content kinds are queried.

--codes CODES

Code patterns to query (STA, NET.STA, NET.STA.LOC, NET.STA.LOC.CHA, or NET.STA.LOC.CHA.EXTRA). The pattern may contain wildcards * (zero or more arbitrary characters), ? (single arbitrary character), and [CHARS] (any character out of CHARS). Multiple patterns can be given by separating them with commas.

--codes-exclude CODES

Code patterns to exclude. See --codes.

--tmin TIME

Begin of time interval to query. Format: YYYY-MM-DD HH:MM:SS.FFF, truncation allowed.

--tmax TIME

End of time interval to query. Format: YYYY-MM-DD HH:MM:SS.FFF, truncation allowed.

--time TIME

Time instant to query. Format: YYYY-MM-DD HH:MM:SS.FFF, truncation allowed.

---

Manual: https://pyrocko.org/docs/current/apps/squirrel

Tutorial: https://pyrocko.org/docs/current/apps/squirrel/tutorial.html

Examples: https://pyrocko.org/docs/current/apps/squirrel/manual.html#examples

🐿️