SpectrogramList

Stability: Stable

What it is

Use SpectrogramList to keep multiple Spectrogram objects together while preserving channel labels and metadata.

Representative Signatures

SpectrogramList(data: list[Spectrogram])
SpectrogramList.to_matrix()

Minimal Example

from gwexpy.spectrogram import Spectrogram, SpectrogramList
import numpy as np

lst = SpectrogramList([Spectrogram(np.ones((8, 16)), dt=1.0, df=1.0)])
mat = lst.to_matrix()

Related Theory

• FFT_Conventions

• Spectrogram

• SpectrogramMatrix

Related Tutorials

• GWpy Migration Guide

• Spectrogram Tutorial

• Segment Visualization

• Glitch Analysis

API Reference

The detailed generated API continues below on this page.

Inherits from: PhaseMethodsMixin, UserList

List of Spectrogram objects. Reference: similar to TimeSeriesList but for 2D Spectrograms.

Physical Context

Use SpectrogramList for several time-frequency maps that should stay separate but be processed together: repeated runs, multiple sensors, or several preprocessing branches of the same event.

• each item can have different provenance even when you batch-plot them

• the container does not enforce matching color semantics, normalization, or binning

Common Misreadings

1. comparing brightness across items without matching scaling and units

2. assuming all entries share the same dt/df because they live in one list

3. treating stacked visual summaries as evidence of alignment without checking metadata

Where to go next

• per-map interpretation: Spectrogram

• aligned collection analysis: SpectrogramMatrix

• practical workflows: Segment Visualization, Glitch Analysis

Note

Spectrogram objects can be very large in memory. Use inplace=True where possible to avoid deep copies.

Methods

__init__

__init__(self, initlist=None)

Initialize self. See help(type(self)) for accurate signature.

(Inherited from PhaseMethodsMixin)

angle

angle(self, unwrap: bool = False, deg: bool = False, **kwargs: Any) -> Any

Alias for phase(unwrap=unwrap, deg=deg).

append

append(self, item)

S.append(value) – append value to the end of the sequence

(Inherited from MutableSequence)

bootstrap_asd

bootstrap_asd(self, *args, **kwargs)

Estimate robust ASD from each spectrogram in the list (returns FrequencySeriesList).

crop

crop(self, t0, t1, inplace=False)

Crop each spectrogram.

crop_frequencies

crop_frequencies(self, f0, f1, inplace=False)

Crop frequencies.

degree

degree(self, unwrap: 'bool' = False) -> "'SpectrogramList'"

Compute phase (in degrees) of each spectrogram.

extend

extend(self, other)

S.extend(iterable) – extend sequence by appending elements from the iterable

(Inherited from MutableSequence)

interpolate

interpolate(self, dt, df, inplace=False)

Interpolate each spectrogram.

phase

phase(self, unwrap: bool = False, deg: bool = False, **kwargs: Any) -> Any

Calculate the phase of the data.

Parameters

unwrap : bool, optional If True, unwrap the phase to remove discontinuities. Default is False. deg : bool, optional If True, return the phase in degrees. Default is False (radians). **kwargs Additional arguments passed to the underlying calculation.

Returns

Series or Matrix or Collection The phase of the data.

plot

plot(self, **kwargs)

Plot all spectrograms stacked vertically.

plot_summary

plot_summary(self, **kwargs)

Plot List as side-by-side Spectrograms and percentile summaries.

radian

radian(self, unwrap: 'bool' = False) -> "'SpectrogramList'"

Compute phase (in radians) of each spectrogram.

read

read(self, source, *args, **kwargs)

Read spectrograms into the list from HDF5.

rebin

rebin(self, dt, df, inplace=False)

Rebin each spectrogram.

to_cupy

to_cupy(self, *args, **kwargs) -> 'list'

Convert each item to cupy.ndarray. Returns a list.

to_dask

to_dask(self, *args, **kwargs) -> 'list'

Convert each item to dask.array. Returns a list.

to_jax

to_jax(self, *args, **kwargs) -> 'list'

Convert each item to jax.Array. Returns a list.

to_matrix

to_matrix(self)

Convert to SpectrogramMatrix (N, Time, Freq).

to_tensorflow

to_tensorflow(self, *args, **kwargs) -> 'list'

Convert each item to tensorflow.Tensor. Returns a list.

to_torch

to_torch(self, *args, **kwargs) -> 'list'

Convert each item to torch.Tensor. Returns a list.

write

write(self, target, *args, **kwargs)

Write list to file.

For HDF5 output you can choose a layout (default is GWpy-compatible dataset-per-entry).

sgl.write("out.h5", format="hdf5")               # GWpy-compatible (default)
sgl.write("out.h5", format="hdf5", layout="group")  # legacy group-per-entry

Warning

Never unpickle data from untrusted sources. pickle/shelve can execute arbitrary code on load.

Pickle portability note: pickled gwexpy SpectrogramList unpickles as a built-in list of GWpy Spectrogram (gwexpy not required on the loading side).