SeisBench

https://seisbench.readthedocs.io/en/stable/
Admin
SeisBench is an open-source Python toolbox for machine learning in seismology that provides a...
Tokens:178,342
Snippets:1,108
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install SeisBench from source

Source: https://seisbench.readthedocs.io/en/stable/_sources/pages/installation_and_usage.rst.txt

Installs the library from a local clone of the repository.

```bash
pip install .
```

--------------------------------

### Install Pyrocko and PyQt5

Source: https://seisbench.readthedocs.io/en/stable/pages/data/dataset_inspection.html

Install the necessary libraries for Pyrocko integration and interactive waveform exploration.

```bash
pip install pyrocko PyQt5

```

--------------------------------

### Install SeisBench via pip

Source: https://seisbench.readthedocs.io/en/stable/_sources/pages/installation_and_usage.rst.txt

Standard installation command for the SeisBench library.

```bash
pip install seisbench
```

--------------------------------

### Install CPU-only SeisBench

Source: https://seisbench.readthedocs.io/en/stable/_sources/pages/installation_and_usage.rst.txt

Two-step process to install PyTorch without CUDA support followed by SeisBench.

```bash
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
pip install seisbench
```

--------------------------------

### Get Pyrocko Event from Sample

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/inspection.html

Converts a sample's metadata into a Pyrocko Event object. Requires Pyrocko to be installed. Uses sample index to retrieve metadata.

```python
def get_pyrocko_event(self, sample_idx: int) -> Event:
        """
        Returns the event of a sample as a pyrocko Event object.

        Requires pyrocko to be installed.

        :param idx: Idx of sample to return event for, or event source_id
        :return: pyrocko Event object
        """

        metadata = self._metadata

        metadata = metadata.iloc[sample_idx].to_dict()
        return Event(
            name=f"{metadata['index']} ({metadata['split']})",
            time=metadata["source_origin_time"].timestamp(),
            lat=metadata["source_latitude_deg"],
            lon=metadata["source_longitude_deg"],
            depth=metadata["source_depth_km"] * 1e3,
            magnitude=metadata.get("source_magnitude", 0.0),
            magnitude_type=metadata.get("source_magnitude_type"),
            extras={
                "id": metadata["source_id"],
                "split": metadata["split"],
            },
        )
```

--------------------------------

### Install SeisBench with DAS support

Source: https://seisbench.readthedocs.io/en/stable/_sources/pages/installation_and_usage.rst.txt

Installs SeisBench including additional dependencies required for DAS data support.

```bash
pip install seisbench[das]
```

--------------------------------

### Download from Huggingface Hub

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/cwa.html

Ensures that huggingface_hub is installed and available for downloading datasets. Raises an error if the library is not found, providing installation instructions.

```python
assert hf_hub_download is not None,
            "To download this dataset, huggingface_hub must be installed. "
            "For installation instructions, "
            "see https://huggingface.co/docs/huggingface_hub/installation"
```

--------------------------------

### Visualize Sample with Snuffle

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/inspection.html

Opens a Pyrocko Snuffle window for a specific sample. Requires Pyrocko to be installed.

```python
    def pyrocko_snuffle_sample(self, sample_idx: int) -> None:
        """
        Returns a pyrocko Snuffle object containing the traces, event and picks of a sample.

        Requires pyrocko to be installed.

        :param idx: Idx of sample to return Snuffle for
        :return: pyrocko Snuffle object
        """

        traces = self.get_pyrocko_traces(sample_idx)
        event = self.get_pyrocko_event(sample_idx)
        picks = self.get_pyrocko_picks(sample_idx)
        station = self._get_station_tuple(sample_idx)

        snuffle(
            traces=traces,
            events=[event],
            markers=picks,
            stations=[station.as_pyrocko_station()],
        )
```

--------------------------------

### Get Split Time for Dataset

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/lendb.html

A static helper method to determine the split for a given start time, using a predefined border date.

```python
@staticmethod
def _get_split_from_time(starttime):
        train_dev_border = "2017-01-16"
```

--------------------------------

### Get Pyrocko Traces from Sample

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/inspection.html

Retrieves seismic waveforms for a given sample index as a list of Pyrocko Trace objects. Requires Pyrocko to be installed. Handles missing location codes.

```python
def get_pyrocko_traces(self, sample_idx: int) -> list[Trace]:
        """
        Returns the waveforms of a sample as a list of pyrocko Trace objects.

        Requires pyrocko to be installed.

        :param idx: Idx of sample to return traces for
        :return: List of pyrocko Trace objects
        """

        ds = self._dataset

        data, metadata = ds.get_sample(sample_idx)
        traces = []

        location_code = str(metadata.get("station_location_code"))
        location_code = "" if location_code == "nan" else location_code

        for ichannel, trace_data in enumerate(data):
            channel = metadata["trace_component_order"][ichannel]
            trace = Trace(
                ydata=trace_data,
                tmin=datetime.fromisoformat(metadata["trace_start_time"]).timestamp(),
                deltat=1.0 / metadata["trace_sampling_rate_hz"],
                network=metadata["station_network_code"],
                station=metadata["station_code"],
                location=location_code,
                channel=f"{metadata['trace_channel']}{channel}",
            )
            traces.append(trace)
        return traces
```

--------------------------------

### Define Complex Germany Domain

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/util/region.html

Example of creating a complex region geometry for Germany using `fiona` and `shapely`. Requires these libraries to be installed. This class defines how to query parameters and check if a point is within the domain based on a shape file.

```python
from obspy.clients.fdsn.mass_downloader.domain import (
    CircularDomain,
    Domain,
    RectangularDomain,
)
from obspy.geodetics.base import locations2degrees




[docs]
class Germany(Domain):
    """
    Example usage of how to create more complex region geometries.
    https://docs.obspy.org/_modules/obspy/clients/fdsn/mass_downloader/domain.html
    """

    def __init__(self):
        Domain.__init__(self)
        try:
            import fiona
            import shapely.geometry
        except ModuleNotFoundError:
            raise ModuleNotFoundError(
                "The Germany domain requires fiona and shapely. "
                "Please install fiona and shapely, e.g., using pip."
            )

        fiona_collection = fiona.open("./shape_files/DEU_adm/DEU_adm0.shp")
        geometry = fiona_collection.next()["geometry"]
        self.shape = shapely.geometry.asShape(geometry)
        self.b = fiona_collection.bounds



[docs]
    def get_query_parameters(self):
        return {
            "minlatitude": self.b[1],
            "minlongitude": self.b[0],
            "maxlatitude": self.b[3],
            "maxlongitude": self.b[2],
        }





[docs]
    def is_in_domain(self, latitude, longitude):
        """
        Checks whether a point is within the domain

        :param latitude: Latitude of query point
        :type latitude: float
        :param longitude: Longitude of query point
        :type longitude: float
        :return: True if point is within the domain, false otherwise
        :rtype: bool
        """
        import shapely

        return self.shape.contains(shapely.geometry.Point(longitude, latitude))
```

--------------------------------

### Initialize DummyDataset

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/dummy.html

Initializes the DummyDataset with a citation and enables repository lookup. Use this to create a basic custom dataset.

```python
class DummyDataset(WaveformBenchmarkDataset):
    """
    A dummy dataset visualizing the implementation of custom datasets
    """

    def __init__(self, **kwargs):
        citation = (
            "Münchmeyer, Jannes; Bindi, Dino; Sippl, Christian; Leser, Ulf; Tilmann, Frederik (2019): "
            "Magnitude scales, attenuation models and feature matrices for the IPOC catalog. "
            "V. 1.0. GFZ Data Services. https://doi.org/10.5880/GFZ.2.4.2019.004"
        )
        super().__init__(citation=citation, repository_lookup=True, **kwargs)
```

--------------------------------

### STEAD Dataset Initialization and Download

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/stead.html

This snippet covers the initialization of the STEAD dataset and the process for downloading and preparing the data if it's not found locally.

```APIDOC
## STEAD Dataset Initialization

### Description
Initializes the STEAD dataset. If the dataset is not found locally, it provides instructions for manual download and specifies the required file locations.

### Method
__init__

### Parameters
- **kwargs**: Additional keyword arguments to pass to the base class.
- **basepath** (str, optional): The path to the directory containing the unpacked STEAD files ('merged.csv' and 'merged.hdf5'). If not provided and the dataset is not cached, a ValueError is raised with download instructions.

### Request Example
```python
from seisbench.data import STEAD

try:
    stead_dataset = STEAD()
except ValueError as e:
    print(e)
    # Provide basepath if download instructions are followed
    # stead_dataset = STEAD(basepath='/path/to/your/stead/files')
```

### Response
#### Success Response (Initialization)
- The STEAD dataset object is initialized.

#### Response Example
(No specific response example for initialization, object is created)

## STEAD Dataset Download and Processing

### Description
This method handles the download and processing of the STEAD dataset. It requires the user to manually download the dataset and provide the path to the files. It then converts the data into the SeisBench format, including splitting the data into train, development, and test sets.

### Method
_download_dataset

### Parameters
- **writer** (WaveformDataWriter): An instance of WaveformDataWriter to handle data writing.
- **basepath** (str): The path to the directory containing 'merged.csv' and 'merged.hdf5'.
- **kwargs**: Additional keyword arguments.

### Request Example
```python
from seisbench.data import STEAD
from seisbench.data.base import WaveformDataWriter

# Assuming you have downloaded STEAD and placed merged.csv and merged.hdf5 in '/path/to/stead'
writer = WaveformDataWriter()
try:
    stead_dataset = STEAD(basepath='/path/to/stead')
except ValueError as e:
    print(e)
```

### Response
#### Success Response (Processing)
- The STEAD dataset is downloaded, processed, and saved in SeisBench format.
- Metadata columns are renamed and split information (train, dev, test) is added.

#### Response Example
(No specific response example for processing, data is saved internally)
```

--------------------------------

### List and Load Pretrained Models

Source: https://seisbench.readthedocs.io/en/stable/_sources/pages/models/pretrained_models.rst.txt

Use these methods to discover available model versions and initialize a model with specific pretrained weights.

```python
import seisbench.models as sbm

sbm.PhaseNet.list_pretrained()                  # Get available models
model = sbm.PhaseNet.from_pretrained("geofon")  # Load the model trained on GEOFON
```

--------------------------------

### Initialize LFEStacksMexicoFrank2014 Dataset

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/lfe_stacks.html

Initializes the LFEStacksMexicoFrank2014 dataset. Requires 'component_order' and other keyword arguments. Uses a specific citation and license.

```python
from .base import WaveformBenchmarkDataset



[docs]
class LFEStacksMexicoFrank2014(WaveformBenchmarkDataset):
    """
    Low-frequency earthquake stacks underneath Guerrero, Mexico based on the catalog by
    Frank et al (2014). Compiled to SeisBench format by Münchmeyer et al (2024).
    """

    def __init__(self, component_order="Z12", **kwargs):
        citation = (
            "Münchmeyer, J., Giffard-Roisin, S., Malfante, M., Frank, W., Poli, P., Marsan, D., Socquet A. (2024). "
            "Deep learning detects uncataloged low-frequency earthquakes across regions. Seismica."
        )
        license = "CC BY 4.0"

        super().__init__(
            citation=citation,
            license=license,
            repository_lookup=True,
            component_order=component_order,
            **kwargs,
        )

    def _download_dataset(self, writer, **kwargs):
        pass
```

--------------------------------

### Iquique Dataset Initialization

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/iquique.html

Information on how to initialize the Iquique dataset, including its citation and a warning about download size.

```APIDOC
## Class: Iquique

### Description
Iquique Benchmark Dataset of local events used for training in Woollam (2019) study. Splits are set using standard random sampling of :py:class:`seisbench.data.base.BenchmarkDataset`.

### Initialization
```python
__init__(self, **kwargs)
```

Initializes the Iquique dataset. It sets the citation and issues a warning regarding the dataset size. The actual download is handled by the parent class.

#### Parameters
- **kwargs**: Additional keyword arguments to be passed to the parent class constructor.

### Citation
Woollam, J., Rietbrock, A., Bueno, A. and De Angelis, S., 2019. Convolutional neural network for seismic phase classification, performance demonstration over a local seismic network. Seismological Research Letters, 90(2A), pp.491-502. https://doi.org/10.1785/0220180312

### Warning
Check available storage and memory before downloading and general use of Iquique dataset. Dataset size: waveforms.hdf5 ~5Gb, metadata.csv ~2.6Mb

### Download Behavior
```python
_download_dataset(**kwargs)
```

This method is intentionally left empty, indicating that the dataset download is managed by the base class or external mechanisms.
```

--------------------------------

### Initialize LFEStacksSanAndreasShelly2017 Dataset

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/lfe_stacks.html

Initializes the LFEStacksSanAndreasShelly2017 dataset. Requires 'component_order' and other keyword arguments. Uses a specific citation and license.

```python
from .base import WaveformBenchmarkDataset



[docs]
class LFEStacksSanAndreasShelly2017(WaveformBenchmarkDataset):
    """
    Low-frequency earthquake stacks on the San Andreas Fault, California, USA based on the catalog by
    Shelly (2014). Compiled to SeisBench format by Münchmeyer et al (2024).
    """

    def __init__(self, component_order="Z12", **kwargs):
        citation = (
            "Münchmeyer, J., Giffard-Roisin, S., Malfante, M., Frank, W., Poli, P., Marsan, D., Socquet A. (2024). "
            "Deep learning detects uncataloged low-frequency earthquakes across regions. Seismica."
        )
        license = "CC BY 4.0"

        super().__init__(
            citation=citation,
            license=license,
            repository_lookup=True,
            component_order=component_order,
            **kwargs,
        )

    def _download_dataset(self, writer, **kwargs):
        pass
```

--------------------------------

### Initialize GEOFON Dataset

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/geofon.html

Initializes the GEOFON dataset. The dataset will be downloaded from the SeisBench repository on first usage. Ensure 'repository_lookup' is set to True for automatic downloading.

```python
from seisbench.data import GEOFON

dataset = GEOFON()

```

--------------------------------

### Detection Data Structure

Source: https://seisbench.readthedocs.io/en/stable/pages/documentation/util.html

A container for storing seismic detection information, including trace ID, start and end times, and an optional peak value. Detections are ordered by start time, end time, and trace ID.

```python
class Detection(_trace_id_ , _start_time_ , _end_time_ , _peak_value =None_)[source]
    
Bases: `object`
    
```

--------------------------------

### GET /get_waveforms

Source: https://seisbench.readthedocs.io/en/stable/pages/documentation/data/base.html

Collects and returns waveforms as an array.

```APIDOC
## GET /get_waveforms

### Description
Collects waveforms and returns them as an array, with optional masking or sampling rate adjustment.

### Parameters
#### Query Parameters
- **idx** (int/list) - Optional - Idx or list of idx to obtain waveforms for
- **mask** (np.ndarray) - Optional - Binary mask on the metadata
- **sampling_rate** (float) - Optional - Target sampling rate

### Response
- **Waveform array** (np.ndarray) - Waveform array with dimensions ordered according to dimension_order.
```

--------------------------------

### Initialize TXED Dataset in SeisBench

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/txed.html

Initializes the TXED dataset, setting citation and license information. Requires repository_lookup to be enabled.

```python
import pickle
from pathlib import Path

import h5py

import seisbench

from .base import WaveformBenchmarkDataset, WaveformDataWriter




[docs]
class TXED(WaveformBenchmarkDataset):
    """
    TEXD dataset from Chen et al.

    train/dev/test split defined in SeisBench.
    """

    def __init__(self, **kwargs):
        citation = (
            "Chen, Y., A. Savvaidis, O. M. Saad, G.-C. D. Huang, D. Siervo, V. O’Sullivan, C. McCabe, B. Uku, "
            "P. Fleck, G. Burke, N. L. Alvarez, J. Domino, and I. Grigoratos, "
            "“TXED: the texas earthquake dataset for AI,” Seismological Research Letters, vol. 1, no. 1, "
            "p. doi: 10.1785/0220230327, 2024.
        )
        license = "GPLv3"
        super().__init__(
            citation=citation, license=license, repository_lookup=True, **kwargs
        )

    def _download_dataset(self, writer: WaveformDataWriter, basepath=None, **kwargs):
        download_instructions = (
            "Please download TXED following the instructions at https://github.com/chenyk1990/txed/. "
            "Provide the locations of the TEXD files (merged.csv and merged.hdf5) in the "
            "download_kwargs argument 'basepath'. "
            "This step is only necessary the first time TEXD is loaded."
        )

        metadata_dict = {
            "causal": "trace_causal",
            "coda_end_sample": "trace_coda_end_sample",
            "ev_depth": "source_depth_km",
            "ev_latitude": "source_latitude_deg",
            "ev_longitude": "source_longitude_deg",
            "magnitude": "source_magnitude",
            "origin_time": "source_origin_time",
            "p_arrival_sample": "trace_p_arrival_sample",
            "p_arrival_time": "trace_p_arrival_time",
            "p_uncertainty": "trace_p_arrival_uncertainty_s",
            "polarity": "trace_polarity",
            "s_arrival_sample": "trace_s_arrival_sample",
            "s_arrival_time": "trace_s_arrival_time",
            "s_uncertainty": "trace_s_arrival_uncertainty_s",
            "snr_db": "trace_snr_db",
            "sta_elevation": "station_elevation_m",
            "sta_latitude": "station_latitude_deg",
            "sta_longitude": "station_longitude_deg",
            "station": "station_code",
            "trace_category": "trace_category",
        }
        float_conversions = [
            "trace_coda_end_sample",
            "source_depth_km",
            "source_latitude_deg",
            "source_longitude_deg",
            "source_magnitude",
            "trace_p_arrival_sample",
            "trace_p_arrival_uncertainty_s",
            "trace_s_arrival_sample",
            "trace_s_arrival_uncertainty_s",
            "station_elevation_m",
            "station_latitude_deg",
            "station_longitude_deg",
        ]

        if basepath is None:
            raise ValueError(
                "No cached version of TEXD found. " + download_instructions
            )

        basepath = Path(basepath)

        if not (basepath / "TXED_20231111.h5").is_file():
            raise ValueError(
                "Basepath does not contain file TXED_20231111.h5. "
                + download_instructions
            )

        with open(basepath / "split.pkl", "rb") as f:
            split = pickle.load(f)
        split = {k: set(v) for k, v in split.items()}

        self.path.mkdir(parents=True, exist_ok=True)
        seisbench.logger.warning(
            "Converting TEXD files to SeisBench format. This might take a while."
        )

        # Writer data format
        writer.data_format = {
            "dimension_order": "CW",
            "component_order": "ZNE",
            "sampling_rate": 100,
            "measurement": "velocity",
            "unit": "counts",
            "instrument_response": "not restituted",
        }

        with h5py.File(basepath / "TXED_20231111.h5") as f:
            writer.set_total(len(f))
            for trace_name in f:
                g = f[trace_name]
                org_metadata = dict(g.attrs)
                metadata = {metadata_dict[k]: v for k, v in org_metadata.items()}
                for k in float_conversions:
                    if k in metadata:
                        metadata[k] = float(metadata[k])

                metadata["source_depth_km"] /= 1e3  # m to km
                metadata["trace_name_original"] = trace_name

                for k, v in split.items():
                    if trace_name in v:
                        metadata["split"] = k
                        break
                else:
                    raise ValueError(f"Trace {trace_name} not contained in any split")

                waveforms = g["data"][()]
                waveforms = waveforms.T  # From WC to CW
                # Component order is ZNE already
                writer.add_trace(metadata, waveforms)

```

--------------------------------

### GET /get_waveforms

Source: https://seisbench.readthedocs.io/en/stable/pages/documentation/data/base.html

Collects and returns waveforms as an array.

```APIDOC
## GET /get_waveforms

### Description
Collects waveforms and returns them as an array, with optional masking or indexing.

### Method
GET

### Parameters
#### Query Parameters
- **idx** (int/list) - Optional - Idx or list of idx to obtain waveforms for
- **mask** (np.ndarray) - Optional - Binary mask on the metadata
- **kwargs** (dict) - Optional - Passed to WaveformDataset.get_waveforms()
```

--------------------------------

### Load VCSEIS Dataset and Subsets in Python

Source: https://seisbench.readthedocs.io/en/stable/_sources/pages/data/benchmark_datasets.rst.txt

Demonstrates how to initialize the VCSEIS dataset and extract specific subsets like data from Alaska, Hawaii, Northern California, Cascade, long-period earthquakes, regular earthquakes, and noise traces. Requires the seisbench library to be installed.

```python
import seisbench.data as sbd

dataset = sbd.VCSEIS()

# Data from Alaska
alaska = dataset.get_alaska_subset()

# Data from Hawaii
hawaii = dataset.get_hawaii_subset()

# Data from Northern California
nca = dataset.get_northern_california_subset()

# Data from Cascade
cascade = dataset.get_cascade_subset()

# Long-period earthquakes
lp_eq = dataset.get_long_period_earthquakes()

# Regular volcano-tectonic earthquakes
regular_eq = dataset.get_regular_earthquakes()

# Noise traces
noise = dataset.get_noise_traces()
```

--------------------------------

### Get Dataset Name

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/base.html

Retrieves the immutable name of the dataset.

```python
@property
    def name(self):
        """
        Name of the dataset (immutable)
        """
        return self._name
```

--------------------------------

### Initialize OBS Dataset

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/obs.html

Initialize the OBS benchmark dataset. The default component order is 'Z12H'. You can specify a different order, like 'Z12', to exclude the hydrophone component if needed for land station pickers.

```python
import seisbench.util
from seisbench.data.base import WaveformBenchmarkDataset



[docs]
class OBS(WaveformBenchmarkDataset):
    """
    OBS Benchmark Dataset of local events

    Default component order is 'Z12H'. You can easily omit one component like, e.g., hydrophone by explicitly passing
    parameter 'component_order="Z12"'. This way, the dataset can be input to land station pickers that use only 3
    components.
    """

    def __init__(self, component_order="Z12H", **kwargs):
        citation = (
            "Bornstein, T., Lange, D., Münchmeyer, J., Woollam, J., Rietbrock, A., Barcheck, G., "
            "Grevemeyer, I., Tilmann, F. (2023). PickBlue: Seismic phase picking for ocean bottom "
            "seismometers with deep learning. arxiv preprint. http://arxiv.org/abs/2304.06635"
        )

        self._write_chunk_file()

        super().__init__(
            citation=citation,
            repository_lookup=True,
            component_order=component_order,
            **kwargs,
        )
```

--------------------------------

### GET /get_group_waveforms

Source: https://seisbench.readthedocs.io/en/stable/pages/documentation/data/base.html

Retrieves waveforms for each member of a specific group.

```APIDOC
## GET /get_group_waveforms

### Description
Returns the waveforms for each member of a group.

### Parameters
#### Path Parameters
- **idx** (int) - Required - Group index

### Response
- **List of waveforms** (list) - The waveforms for the group members.
```

--------------------------------

### Initialize ETHZ Dataset

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/ethz.html

Initializes the ETHZ dataset, providing citation information and a warning about storage requirements. It sets up the dataset for remote lookup or direct download.

```python
import seisbench
from seisbench.data.base import WaveformBenchmarkDataset



[docs]
class ETHZ(WaveformBenchmarkDataset):
    """
    Regional benchmark dataset of publicly available waveform data & corresponding
    metadata in Swiss Seismological Service (SED) archive. Contains data from
    (2013-2020). A pre-compiled version of the benchmark dataset in compatible
    SeisBench format is available for download from remote root. In case of download issues,
    benchmark dataset is downloaded directly from source via FDSN client and converted SeisBench
    format.

    """

    def __init__(self, **kwargs):
        citation = (
            "Each individual network has its own DOI. From publicly available data:\n"
            "CH: https://doi.org/10.12686/sed/networks/ch\n"
            "C4: https://doi.org/10.12686/sed/networks/c4\n"
            "8D: https://doi.org/10.12686/sed/networks/8d\n"
            "S:  https://doi.org/10.12686/sed/networks/s\n"
            "XT: https://doi.org/10.12686/alparray/xt_2014"
        )

        seisbench.logger.warning(
            "Check available storage and memory before downloading and general use "
            "of ETHZ dataset. "
            "Dataset size: waveforms.hdf5 ~22Gb, metadata.csv ~13Mb"
        )

        self._client = None
        super().__init__(citation=citation, repository_lookup=True, **kwargs)
```

--------------------------------

### GET /available_chunks

Source: https://seisbench.readthedocs.io/en/stable/pages/documentation/data/base.html

Determines the chunks of the dataset in the given path.

```APIDOC
## GET /available_chunks

### Description
Returns a list of chunks available in the specified dataset path.

### Method
GET

### Parameters
#### Query Parameters
- **path** (str) - Required - Dataset path

### Response
#### Success Response (200)
- **chunks** (list[str]) - List of available chunks
```

--------------------------------

### Download Dataset

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/bohemia.html

Initializes the client and downloads seismic data from BGR and Geofon if not already present locally.

```python
    def _download_dataset(
        self,
        writer,
        time_before: float = 60.0,
        time_after: float = 60.0,
        **kwargs,
    ):
        logger.info(
            "No pre-downloaded dataset available, downloading from BGR and Geofon. "
            "This may take a while.",
        )
        if not self._eida_token:
            logger.warning(
                "No EIDA token provided. "
                "Restricted WB network data will not be accessible.",
            )
        self._init_client()
        writer.data_format = {
            "dimension_order": "CW",
            "component_order": COMPONENT_ORDER,
            "measurement": "velocity",
            "unit": "counts",
            "instrument_response": "not restituted",
        }

        cat = self.get_catalog()
        inv = self.get_inventory(cat, force_download=True)

        cat = fixup_catalog(cat, inv)
```

--------------------------------

### GET /get_sample

Source: https://seisbench.readthedocs.io/en/stable/pages/documentation/data/base.html

Retrieves a specific sample from the dataset by index.

```APIDOC
## GET /get_sample

### Description
Wraps WaveformDataset.get_sample() to retrieve a sample by its index.

### Method
GET

### Parameters
#### Query Parameters
- **idx** (int) - Required - Index of the sample
- **args** (list) - Optional - Passed to parent function
- **kwargs** (dict) - Optional - Passed to parent function
```

--------------------------------

### Initialize ProbabilisticLabeller

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/generate/labeling.html

Creates supervised labels from picks using a probabilistic representation.

```python
class ProbabilisticLabeller(StreamPickLabeller):
    """
    Create supervised labels from picks with probabilistic representation.
    """

    def __init__(self, shape: str = "gaussian", sigma: int = 10, **kwargs):
        super().__init__(
            shape=shape, sigma=sigma, labeller_type="probabilistic", **kwargs
        )

    def __str__(self):
        return f"ProbabilisticLabeller (label_type={self.label_type}, dim={self.dim})"
```

--------------------------------

### Pick Data Structure

Source: https://seisbench.readthedocs.io/en/stable/pages/documentation/util.html

A container for storing seismic pick information, including trace ID, start time, and optional end time, peak time, peak value, phase, and polarity. Picks are ordered by start time, end time, and trace ID.

```python
class Pick(_trace_id_ , _start_time_ , _end_time =None_, _peak_time =None_, _peak_value =None_, _phase =None_, _polarity =None_, _polarity_value =None_)[source]
    
Bases: `object`
    
```

--------------------------------

### Make HTTP PROPFIND Request with Requests

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/util/file.html

This snippet demonstrates how to make a PROPFIND request using the `requests` library to retrieve file information from a URL. It includes error handling for non-2xx status codes and parses the XML response to extract file paths.

```python
req = requests.Request("PROPFIND", url, headers={"Depth": "1"}, data=xml_request)
prep = req.prepare()

with requests.Session() as sess:
    ret = sess.send(prep)

if not 200 <= ret.status_code < 300:
    raise ValueError(
        f"Invalid URL. Request returned status code {ret.status_code}."
    )

files = [""]  # The first part of the response is always the root path
tree = etree.fromstring(ret.content)
for elem in tree.xpath(".//d:href", namespaces={"d": "DAV:"})[1:]:
    # Extract basepath from path
    p = elem.text[:-1].rfind("/") + 1
    files.append(elem.text[p:])

return files
```

--------------------------------

### GET /group/{idx}/waveforms

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/base.html

Returns the waveforms for each member of a group.

```APIDOC
## GET /group/{idx}/waveforms

### Description
Returns the waveforms for each member of a group.

### Method
GET

### Endpoint
/group/{idx}/waveforms

### Parameters
#### Path Parameters
- **idx** (int) - Required - Group index

### Response
#### Success Response (200)
- **waveforms** (list) - List of waveforms
```

--------------------------------

### Get Component Order

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/base.html

Retrieves the current order of components in the output.

```python
@property
    def component_order(self):
        """
        Get or set order of components in the output.
        """
        return self._component_order
```

--------------------------------

### Get Dimension Order

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/base.html

Retrieves the current order of dimensions for the dataset.

```python
@property
    def dimension_order(self):
        """
        Get or set the order of the dimension in the output.
        """
        return self._dimension_order
```

--------------------------------

### seisbench.generate.windows

Source: https://seisbench.readthedocs.io/en/stable/_sources/pages/documentation/generate.rst.txt

Details about the window selection submodule, including its members and inheritance.

```APIDOC
## seisbench.generate.windows

### Description
This submodule provides functionality for selecting time windows from seismic data.

### Members
- **members**: Lists all public members of the module.
- **undoc-members**: Includes members that are not documented.
- **show-inheritance**: Indicates whether to show the inheritance hierarchy.
```

--------------------------------

### Initialize Dataset Writer

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/base.html

Constructor for the writer class, setting up paths, bucketing defaults, and file system structures.

```python
def __init__(self, metadata_path, waveforms_path):
        self.metadata_path = Path(metadata_path)
        self.waveforms_path = Path(waveforms_path)
        self.metadata_dict = {}
        self.data_format = {}

        self.metadata_path.parent.mkdir(parents=True, exist_ok=True)
        self.waveforms_path.parent.mkdir(parents=True, exist_ok=True)

        self._metadata = []
        self._waveform_file = None
        self._pbar = None

        self._bucketer = GeometricBucketer()
        self._bucket_size = 1024
        self._cache = defaultdict(list)  # Cache used for the bucketing
        self._bucket_counter = 0  # Bucket counter to generate bucket names
```

--------------------------------

### GET /get_sample

Source: https://seisbench.readthedocs.io/en/stable/pages/documentation/data/base.html

Retrieves both waveforms and metadata for a specific sample index.

```APIDOC
## GET /get_sample

### Description
Returns both waveforms and metadata of a trace, adjusting metadata to the specified sampling rate.

### Parameters
#### Query Parameters
- **idx** (int) - Required - Idx of sample to return
- **sampling_rate** (float) - Optional - Target sampling rate

### Response
- **Tuple** (tuple) - Waveforms and metadata of the sample.
```

--------------------------------

### GET /get_event_sample_indices

Source: https://seisbench.readthedocs.io/en/stable/pages/documentation/data/base.html

Retrieves indices of samples associated with a specific event.

```APIDOC
## GET /get_event_sample_indices

### Description
Returns the indices of all samples associated with a given event ID.

### Method
GET

### Parameters
#### Query Parameters
- **event_id** (str) - Required - Event identifier

### Response
#### Success Response (200)
- **indices** (list[int]) - List of indices associated with the event
```

--------------------------------

### OBS Dataset Initialization

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/obs.html

Initializes the OBS Benchmark Dataset. Allows customization of the component order and provides citation information.

```APIDOC
## OBS Dataset Initialization

### Description
Initializes the OBS Benchmark Dataset, which contains local event data from ocean bottom seismometers. The default component order is 'Z12H', but this can be customized by passing a `component_order` argument (e.g., `"Z12"`). The dataset includes citation information for referencing the source.

### Method
`__init__`

### Parameters
- **component_order** (str) - Optional - Default: "Z12H" - Specifies the order of seismic components (e.g., 'Z12H', 'Z12').
- **kwargs** - Additional keyword arguments to be passed to the parent class.

### Request Example
```python
from seisbench.data import OBS

# Initialize with default component order
dataset_default = OBS()

# Initialize with a custom component order
dataset_custom = OBS(component_order="Z12")
```

### Response
#### Success Response (200)
An instance of the OBS dataset is returned, ready for data loading and processing.

#### Response Example
```json
{
  "message": "OBS Dataset initialized successfully."
}
```
```

--------------------------------

### Install Pyrocko dependencies

Source: https://seisbench.readthedocs.io/en/stable/_sources/pages/data/dataset_inspection.rst.txt

Required packages for using Pyrocko Snuffler with SeisBench.

```bash
pip install pyrocko PyQt5
```

--------------------------------

### Initialize ChunkedDummyDataset

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/dummy.html

Initializes the ChunkedDummyDataset, setting up a citation and enabling repository lookup. It also creates a 'chunks' file if it doesn't exist.

```python
class ChunkedDummyDataset(WaveformBenchmarkDataset):
    """
    A chunked dummy dataset visualizing the implementation of custom datasets with chunking
    """

    def __init__(self, **kwargs):
        citation = (
            "Münchmeyer, Jannes; Bindi, Dino; Sippl, Christian; Leser, Ulf; Tilmann, Frederik (2019): "
            "Magnitude scales, attenuation models and feature matrices for the IPOC catalog. "
            "V. 1.0. GFZ Data Services. https://doi.org/10.5880/GFZ.2.4.2019.004"
        )

        # Write chunks to file
        chunks_path = self.path / "chunks"
        if not chunks_path.is_file():
            self.path.mkdir(exist_ok=True, parents=True)
            with open(chunks_path, "w") as f:
                f.write("0\n1\n")

        super().__init__(citation=citation, repository_lookup=True, **kwargs)
```

--------------------------------

### Initialize LFEStacksCascadiaBostock2015 Dataset

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/lfe_stacks.html

Initializes the LFEStacksCascadiaBostock2015 dataset. Requires 'component_order' and other keyword arguments. Uses a specific citation and license.

```python
from .base import WaveformBenchmarkDataset



[docs]
class LFEStacksCascadiaBostock2015(WaveformBenchmarkDataset):
    """
    Low-frequency earthquake stacks underneath Vancouver Island, Cascadia, Canada/USA based on the catalog by
    Bostock et al (2015). Compiled to SeisBench format by Münchmeyer et al (2024).
    """

    def __init__(self, component_order="Z12", **kwargs):
        citation = (
            "Münchmeyer, J., Giffard-Roisin, S., Malfante, M., Frank, W., Poli, P., Marsan, D., Socquet A. (2024). "
            "Deep learning detects uncataloged low-frequency earthquakes across regions. Seismica."
        )
        license = "CC BY 4.0"

        super().__init__(
            citation=citation,
            license=license,
            repository_lookup=True,
            component_order=component_order,
            **kwargs,
        )

    def _download_dataset(self, writer, **kwargs):
        pass
```

--------------------------------

### GET /group/{idx}/samples

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/base.html

Returns the waveforms and metadata for each member of a group.

```APIDOC
## GET /group/{idx}/samples

### Description
Returns the waveforms and metadata for each member of a group.

### Method
GET

### Endpoint
/group/{idx}/samples

### Parameters
#### Path Parameters
- **idx** (int) - Required - Group index

### Response
#### Success Response (200)
- **waveforms** (list) - List of waveforms
- **metadata** (list) - List of metadata dicts
```

--------------------------------

### Construct pick labels with label method

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/generate/labeling.html

Main entry point for generating labels from metadata, handling initialization, windowing, and noise normalization.

```python
    def label(self, X, metadata):
        # Get label configuration
        if not self.label_columns:
            label_columns = self._auto_identify_picklabels(metadata)
            (
                self.label_columns,
                self.labels,
                self.label_ids,
            ) = self._columns_to_dict_and_labels(
                label_columns, self.noise_column, self.model_labels
            )
        if self.labeller_type == "polarity":
            self.labels = ["U", "D", "N"]
            self.label_ids = {"U": 0, "D": 1, "N": 2}

        sample_dim, channel_dim, width_dim = self._get_dimension_order_from_config(
            config, self.ndim
        )

        # Initialize y array
        if self.ndim == 2:
            y = np.zeros(shape=(len(self.labels), X.shape[width_dim]))
        elif self.ndim == 3:
            y = np.zeros(
                shape=(
                    X.shape[sample_dim],
                    len(self.labels),
                    X.shape[width_dim],
                )
            )
        else:
            raise ValueError(f"ndim must be either 2 or 3, not {self.ndim}")

        # Construct pick labels
        for label_column, label in self.label_columns.items():
            if label_column not in metadata:
                # Unknown pick
                continue

            i = self.label_ids[label]

            if isinstance(metadata[label_column], (int, np.integer, float)):
                # Handle single window case
                onset = metadata[label_column]
                if self.shape in self._labelshape_fn_mapper.keys():
                    label_val = self._labelshape_fn_mapper[self.shape](
                        onset=onset, length=X.shape[width_dim], sigma=self.sigma
                    )
                else:
                    raise ValueError(
                        f"Labeller of shape {self.shape} is not implemented."
                    )

                label_val[np.isnan(label_val)] = (
                    0  # Set non-present pick probabilities to 0
                )
                self._fill_y_value(y, label, label_val, metadata, i)
            else:
                # Handle multi-window case
                for j in range(X.shape[sample_dim]):
                    onset = metadata[label_column][j]
                    if self.shape in self._labelshape_fn_mapper.keys():
                        label_val = self._labelshape_fn_mapper[self.shape](
                            onset=onset, length=X.shape[width_dim], sigma=self.sigma
                        )
                    else:
                        raise ValueError(
                            f"Labeller of shape {self.shape} is not implemented."
                        )

                    label_val[np.isnan(label_val)] = 0
                    self._fill_y_value(y, label, label_val, metadata, i, j)

        # Handle noise normalization
        if self.noise_column or self.labeller_type == "polarity":
            y /= np.maximum(1, np.nansum(y, axis=channel_dim, keepdims=True))

            # Construct noise label
            if self.labeller_type == "polarity":
                noise_idx = self.label_ids.get("N", len(self.labels) - 1)
            else:
                noise_idx = self.label_ids.get("Noise", len(self.labels) - 1)
            if self.ndim == 2:
                y[noise_idx, :] = 1 - np.nansum(y, axis=channel_dim)
            elif self.ndim == 3:
                y[:, noise_idx, :] = 1 - np.nansum(y, axis=channel_dim)

        # Swap dimensions
        if self.ndim == 2:
            y = self._swap_dimension_order(
                y,
                current_dim="CW",
```

--------------------------------

### GET /group/{idx}/size

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/base.html

Returns the number of samples in a specific group.

```APIDOC
## GET /group/{idx}/size

### Description
Returns the number of samples in a group.

### Method
GET

### Endpoint
/group/{idx}/size

### Parameters
#### Path Parameters
- **idx** (int) - Required - Group index

### Response
#### Success Response (200)
- **size** (int) - Size of the group
```

--------------------------------

### GET /get_split

Source: https://seisbench.readthedocs.io/en/stable/pages/documentation/data/base.html

Returns a subset of the dataset based on the specified split name.

```APIDOC
## GET /get_split

### Description
Returns a dataset filtered to the requested split (e.g., train, dev, test).

### Method
GET

### Parameters
#### Query Parameters
- **split** (str) - Required - Split name to return (e.g., "train", "dev", "test")
```

--------------------------------

### Bohemia Dataset - Get Inventory

Source: https://seisbench.readthedocs.io/en/stable/pages/documentation/data/waveform_datasets.html

Retrieves the station inventory for the Bohemia dataset.

```APIDOC
## GET /BohemiaSaxony/inventory

### Description
Retrieves the station inventory for the Bohemia dataset.

### Method
GET

### Parameters
#### Query Parameters
- **catalog** (object) - Required - The catalog to fetch inventory for.
- **force_download** (boolean) - Optional - Whether to force a re-download of the inventory.
```

--------------------------------

### Configure backup repository

Source: https://seisbench.readthedocs.io/en/stable/_sources/pages/installation_and_usage.rst.txt

JSON configuration line to set the remote root to the backup server in the .seisbench/config.json file.

```json
"remote_root": "https://seisbench.gfz.de/mirror/"
```

--------------------------------

### DetectionLabeller Initialization

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/generate/labeling.html

Initializes the DetectionLabeller with phase metadata columns and window configuration.

```APIDOC
## DetectionLabeller.__init__

### Description
Initializes the labeller to create detection labels from seismic picks.

### Parameters
- **p_phases** (str, list[str]) - Required - P phase metadata columns.
- **s_phases** (str, list[str]) - Optional - S phase metadata columns.
- **factor** (float) - Optional - Factor for length of window after S onset (default: 1.4).
- **fixed_window** (int) - Optional - Number of samples for fixed window detections. If provided, S phases are ignored.
```

--------------------------------

### Bohemia Dataset - Get Catalog

Source: https://seisbench.readthedocs.io/en/stable/pages/documentation/data/waveform_datasets.html

Retrieves the seismic catalog for the Bohemia dataset.

```APIDOC
## GET /BohemiaSaxony/catalog

### Description
Returns the catalog associated with the Bohemia and Saxony regional dataset.

### Method
GET

### Response
#### Success Response (200)
- **Catalog** (object) - The seismic catalog object.
```

--------------------------------

### GET _parse_location

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/base.html

Parses a location string into a tuple of slice objects for numpy indexing.

```APIDOC
## GET _parse_location

### Description
Parses the location string and returns the associated tuple of slice objects.

### Method
GET

### Parameters
#### Query Parameters
- **location** (string) - Required - Location identifier in numpy format as string, e.g., "5,1:7,:"

### Response
- **slices** (tuple) - Tuple of slice objects
```

--------------------------------

### Abstract Download Dataset Method

Source: https://seisbench.readthedocs.io/en/stable/_modules/seisbench/data/base.html

Abstract method to download and convert datasets to the standard SeisBench format. Must be implemented by subclasses.

```python
def _download_dataset(self, files: list[Path], chunk: str, **kwargs):
        """
        Download and convert the dataset to the standard SeisBench format.

        :param files: List of file paths for the output files. Uses the same order as the ``_files`` list in the class.
        :param chunk: The chunk to be downloaded. Can be ignored if an unchunked data set is created.
        :param kwargs:
        :return: None
        """
        raise NotImplementedError(
            "This dataset does not implement a conversion from source."
        )
```

--------------------------------

### GET /get_idx_from_trace_name

Source: https://seisbench.readthedocs.io/en/stable/pages/documentation/data/base.html

Returns the index of a trace based on its name and optional chunk/dataset identifiers.

```APIDOC
## GET /get_idx_from_trace_name

### Description
Returns the index of a trace with given trace_name, chunk and dataset. If no matching key is found, a KeyError is raised.

### Parameters
#### Query Parameters
- **trace_name** (str) - Required - Trace name as in metadata["trace_name"]
- **chunk** (None) - Optional - Trace chunk as in metadata["trace_chunk"]
- **dataset** (None) - Optional - Trace dataset as in metadata["trace_dataset"]

### Response
- **Index** (int) - The index of the sample.
```
Tokens:
Raw