### Initialize and start EQDownloader

Source: https://seislib.readthedocs.io/en/latest/seislib.eq.html

Creates an EQDownloader instance with the previously defined stations_config and events_config, then starts the download. The example shows all constructor parameters and the start() call.

```python
from seislib.eq import EQDownloader

downloader = EQDownloader(savedir='/path/to/directory',
                          inv_provider='iris',
                          ev_provider='iris',
                          inventory_name='iris.xml',
                          sampling_rate=1,
                          prefilter=(0.001, 0.005, 0.1, 0.4),
                          vmin=1.5,
                          vmax=5.5,
                          units='disp',
                          attach_response=False,
                          stations_config=stations_config,
                          events_config=events_config,
                          verbose=True)        
downloader.start()
```

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

### start()

Source: https://seislib.readthedocs.io/en/latest/seislib.an.html

Starts the download process.

```APIDOC
## start()

### Description
Starts the download process.
```

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

### Initialize and start ANDownloader

Source: https://seislib.readthedocs.io/en/latest/seislib.an.html

Initializes the ANDownloader instance with specified parameters and starts the download. The process is resumable; if interrupted, the next run will continue from where it left off. If modifying station_configs, delete the previous .xml file or use a different inventory_name.

```python
from seislib.an import ANDownloader

downloader = ANDownloader(savedir=/path/to/directory, 
                          inventory_name='II.xml',
                          provider='iris',
                          sampling_rate=1,
                          prefilter=(0.005, 0.01, 0.5, 1),
                          units='disp',
                          attach_response=False,
                          stations_config=stations_config,
                          verbose=True)
downloader.start()
```

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

### start

Source: https://seislib.readthedocs.io/en/latest/seislib.eq.html

Starts the download of teleseismic earthquake recordings.

```APIDOC
## start

### Description
Starts the download of teleseismic earthquake recordings.

### Method
Function

### Signature
`start()`

### Parameters
None

### Returns
None

```

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

### EQDownloader

Source: https://seislib.readthedocs.io/en/latest/seislib.eq.html

Initializes an EQDownloader instance with configuration for stations and events, then starts the download process.

```APIDOC
## EQDownloader

### Description
Initializes an EQDownloader instance for downloading teleseismic earthquake recordings. The constructor accepts configuration dictionaries for stations and events, and the `start()` method begins the download process.

### Method
Constructor and start method

### Endpoint
Not applicable (Python class)

### Parameters
#### Constructor Parameters
- **savedir** (str) - Required - Absolute path of the directory that will be created
- **inv_provider** (str) - Required - Provider of station metadata and waveforms (e.g., 'iris')
- **ev_provider** (str) - Required - Provider of events metadata (e.g., 'iris')
- **inventory_name** (str) - Required - Name of the inventory file to save
- **sampling_rate** (float) - Required - Sampling rate of the final seismograms
- **prefilter** (tuple) - Required - Filter applied to the waveform before removal of the instrument response
- **vmin** (float) - Required - Minimum expected velocity of the surface waves
- **vmax** (float) - Required - Maximum expected velocity of the surface waves
- **units** (str) - Required - Physical units of the final seismogram (e.g., 'disp')
- **attach_response** (bool) - Required - Whether or not the response information is attached to the waveforms during the download
- **stations_config** (dict) - Required - Dictionary with information relevant to the download of the stations metadata
- **events_config** (dict) - Required - Dictionary with information relevant to the download of the events metadata
- **verbose** (bool) - Optional - If True, information on the downloads will be printed in console

#### stations_config Parameters
- **channel** (str) - Required - Channel preference, e.g., 'LH*,BH*,HH*' (3-component seismograms implied by asterisk)
- **includerestricted** (bool) - Required - Whether to include restricted stations
- **maxlatitude** (float) - Required - Maximum latitude of the region
- **minlatitude** (float) - Required - Minimum latitude of the region
- **minlongitude** (float) - Required - Minimum longitude of the region
- **maxlongitude** (float) - Required - Maximum longitude of the region

#### events_config Parameters
- **starttime** (UTCDateTime) - Required - Start time of the events catalogue
- **endtime** (UTCDateTime) - Required - End time of the events catalogue
- **depthmax** (float) - Required - Maximum depth of the earthquakes (km)
- **magmin** (float) - Required - Minimum magnitude
- **magmax** (float) - Required - Maximum magnitude
- **distmin** (float) - Required - Minimum distance of a station from the epicenter (km)
- **distmax** (float) - Required - Maximum distance of a station from the epicenter (km)

### Request Example
```python
from obspy import UTCDateTime as UTC
from obspy.geodetics import degrees2kilometers

stations_config=dict(
        channel='LH*,BH*,HH*',
        includerestricted=False,
        maxlatitude=12,
        minlatitude=-18,
        minlongitude=90,
        maxlongitude=140)

events_config=dict(
        starttime=UTC(2000, 1, 1),
        endtime=UTC(2021, 1, 1),
        depthmax=50,
        magmin=6,
        magmax=8.5,
        distmin=degrees2kilometers(20),
        distmax=degrees2kilometers(140))

from seislib.eq import EQDownloader

downloader = EQDownloader(savedir='/path/to/directory',
                          inv_provider='iris',
                          ev_provider='iris',
                          inventory_name='iris.xml',
                          sampling_rate=1,
                          prefilter=(0.001, 0.005, 0.1, 0.4),
                          vmin=1.5,
                          vmax=5.5,
                          units='disp',
                          attach_response=False,
                          stations_config=stations_config,
                          events_config=events_config,
                          verbose=True)
downloader.start()
```

### Response
#### Success Response
No explicit response is documented. The `start()` method initiates the download process.

### Attributes
- **savedir** (str) - Absolute path of the directory that will be created
- **staclient** (obspy.clients.fdsn.Client) - Provider of station metadata and waveforms
- **evclient** (obspy.clients.fdsn.Client) - Provider of events metadata
- **channels** (list) - List of candidate channels for the downloads
- **components** ({3, 1}) - Either 3 (ZNE) or 1 (Z)
- **vmin, vmax** (float) - Minimum and maximum expected velocity of the surface waves
- **sampling_rate** (float) - Sampling rate of the final seismograms
- **prefilter** (tuple) - Filter applied to the waveform before removal of the instrument response
- **units** (str) - Physical units of the final seismogram
- **attach_response** (bool) - Whether or not the response information is attached to the waveforms during the download
- **verbose** (bool) - Whether or not progress information are displayed in the console
- **sleep_time_after_exception** (float) - The downloads are stopped for the specified time (in s) after a FDSN exception
- **distmin, distmax** (float) - Minimum and maximum distance of a station from the epicenter (km)
- **depthmax** (float) - Maximum depth of the earthquakes (km)
- **magmin, magmax** (float) - Minimum and maximum magnitude
- **starttime, endtime** (obspy.core.utcdatetime.UTCDateTime) - Starttime and entime of the events catalogue
- **stations_config, events_config** (dict) - Dictionary object with information relevant to the download of the stations and events metadata
- **inventory** (obspy.core.inventory.inventory.Inventory) - Stations metadata
- **_exceptions** (collections.defaultdict(int)) - Dictionary object with information on the occurred exceptions
- **_downloaded** (int) - Number of waveforms downloaded
- **_no_stations** (int) - Number of stations to download
```

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

### Initialize EQVelocity and prepare data

Source: https://seislib.readthedocs.io/en/latest/seislib.eq.html

Example from the documentation showing how to initialize an EQVelocity instance and call prepare_data with parameters.

```python
from seislib.eq import EQVelocity
eq = EQVelocity(src=SRC, component='Z')
eq.prepare_data(azimuth_tolerance=7,
                distmin=None, 
                distmax=3000, 
                min_no_events=8)
```

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

### Configure ANDownloader stations_config for network II, channel BH*

Source: https://seislib.readthedocs.io/en/latest/seislib.an.html

Example of building the stations_config dictionary passed to ANDownloader. It restricts the download to network II, channel BH*, time range 2020-01-01 to 2021-01-01, excludes restricted data, and sets a geographic bounding box. Uses obspy.UTCDateTime for start and end times.

```python
from obspy import UTCDateTime as UTC

stations_config = dict(network='II',
                       channel='BH*',
                       starttime=UTC(2020, 1, 1),
                       endtime=UTC(2021, 1, 1),
                       includerestricted=False,
                       maxlatitude=12,
                       minlatitude=-18,
                       minlongitude=90,
                       maxlongitude=140)
```

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

### Install seislib via pip

Source: https://seislib.readthedocs.io/en/latest/_sources/installation.rst.txt

Installs the seislib package using pip. This command should be run after the dependencies are installed.

```console
~$ pip install seislib
```

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

### starttime_for_download(_tmp_folder_ , _station_)

Source: https://seislib.readthedocs.io/en/latest/seislib.an.html

Identifies the start time from which the downloads will begin for a given station.

```APIDOC
## starttime_for_download(_tmp_folder_ , _station_)

### Description
Identifies the start time from which the downloads will begin for a given station.

### Parameters
- **tmp_folder** (str) - Required - Absolute path to the temporary directory.
- **station** (obspy.core.inventory.station.Station) - Required - The station information.
```

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

### Install dependencies and seislib (conda, pip, git)

Source: https://seislib.readthedocs.io/en/latest/installation.html

Commands to create a conda environment with Python 3.9, install the required dependencies (obspy, cartopy, cython), install seislib via pip, and optionally compile the Cython extension from source if pip install fails.

```bash
~$ conda create -n seislib python=3.9
~$ conda activate seislib
~$ conda install -c conda-forge obspy
~$ conda install -c conda-forge cartopy
~$ conda install -c anaconda cython

```

```bash
~$ pip install seislib

```

```bash
~$ git clone https://github.com/fmagrini/seislib.git
~$ cd seislib/seislib/tomography/_ray_theory
~$ python setup_all.py build_ext --inplace

```

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

### starttime_for_download(tmp_folder, station)

Source: https://seislib.readthedocs.io/en/latest/seislib.an.html

Identifies the start time from which the downloads will begin for a given station.

```APIDOC
## starttime_for_download(tmp_folder, station)

### Description
Identifies the start time from which the downloads will begin for a given station.

### Parameters
- **tmp_folder** - Required - The temporary folder path.
- **station** (obspy.core.inventory.station.Station) - Required - The station.

### Returns
- obspy.core.utcdatetime.UTCDateTime
```

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

### Prepare input for tomography

Source: https://seislib.readthedocs.io/en/latest/seislib.eq.html

Example showing how to call prepare_input_tomography with a list of periods to generate input files for phase-velocity maps.

```python
savedir = /arbitrary/path/to/savedir
periods = [20, 30, 40, 50, 75, 100]
eq.prepare_input_tomography(savedir=savedir,
                            period=periods)
```

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

### ANDownloader

Source: https://seislib.readthedocs.io/en/latest/seislib.an.html

Initializes the ANDownloader instance and starts the download process. The constructor accepts various parameters to configure the download, such as save directory, inventory name, provider, sampling rate, prefilter, units, response attachment, station configuration, and verbosity.

```APIDOC
## ANDownloader

### Description
Initializes the ANDownloader instance and starts the download process. The constructor accepts various parameters to configure the download, such as save directory, inventory name, provider, sampling rate, prefilter, units, response attachment, station configuration, and verbosity.

### Method
Constructor

### Endpoint
ANDownloader(savedir, inventory_name, provider, sampling_rate, prefilter, units, attach_response, stations_config, verbose)

### Parameters
#### Constructor Parameters
- **savedir** (str) - Required - Absolute path of the directory that will be created.
- **inventory_name** (str) - Required - Name of the inventory file (e.g., 'II.xml').
- **provider** (str) - Required - Provider of station metadata and waveforms (e.g., 'iris').
- **sampling_rate** (float) - Required - Sampling rate of the final seismograms.
- **prefilter** (tuple of floats) - Required - Filter applied to the waveform before removal of the instrument response.
- **units** (str) - Required - Physical units of the final seismogram (e.g., 'disp').
- **attach_response** (bool) - Required - Whether or not the response information is attached to the waveforms during the download.
- **stations_config** (dict) - Required - Dictionary object with information relevant to the download of the station metadata.
- **verbose** (bool) - Required - Whether or not progress information are displayed in the console.

### Request Example
```python
from seislib.an import ANDownloader

downloader = ANDownloader(savedir='/path/to/directory', 
                          inventory_name='II.xml',
                          provider='iris',
                          sampling_rate=1,
                          prefilter=(0.005, 0.01, 0.5, 1),
                          units='disp',
                          attach_response=False,
                          stations_config=stations_config,
                          verbose=True)
downloader.start()
```

### Response
#### Success Response
No explicit response is documented. The downloader starts the download process.

### Attributes
- **savedir** (str) - Absolute path of the directory that will be created.
- **staclient** (obspy.clients.fdsn.Client) - Provider of station metadata and waveforms.
- **channels** (list) - List of candidate channels for the downloads.
- **components** (int) - Either 3 (ZNE) or 1 (Z).
- **duration** (int, float) - Duration of the waveforms downloaded (in s).
- **max_final_stream_duration** (float) - Maximum duration of the final continuous seismograms.
- **sampling_rate** (float) - Sampling rate of the final seismograms.
- **prefilter** (tuple of floats) - Filter applied to the waveform before removal of the instrument response.
- **units** (str) - Physical units of the final seismogram.
- **attach_response** (bool) - Whether or not the response information is attached to the waveforms during the download.
- **verbose** (bool) - Whether or not progress information are displayed in the console.
- **reversed_iterations** (bool) - Whether or not the inventory of stations is reversely iterated over.
- **sleep_time_after_exception** (float) - The downloads are stopped for the specified time (in s) after a FDSN exception.
- **stations_config** (dict) - Dictionary object with information relevant to the download of the station metadata.
- **inventory** (obspy.core.inventory.inventory.Inventory) - Stations metadata.
- **_exceptions** (collections.defaultdict(int)) - Dictionary object with information on the occurred exceptions.
- **_downloaded** (int) - Number of waveforms downloaded.
- **_no_stations** (int) - Number of stations to download.
```

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

### Initialize AmbientNoiseVelocity and prepare data

Source: https://seislib.readthedocs.io/en/latest/seislib.an.html

Example of creating an AmbientNoiseVelocity instance with a source path and component 'Z', then calling prepare_data() to save station coordinates and time spans to disk.

```python
an = AmbientNoiseVelocity(src=SRC,
                          component='Z')
an.prepare_data()

```

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

### Create conda environment and install dependencies

Source: https://seislib.readthedocs.io/en/latest/_sources/installation.rst.txt

Creates a new conda environment named 'seislib' with Python 3.9, activates it, and installs the required dependencies: obspy, cartopy, and cython from the specified channels.

```console
~$ conda create -n seislib python=3.9
~$ conda activate seislib
~$ conda install -c conda-forge obspy
~$ conda install -c conda-forge cartopy
~$ conda install -c anaconda cython
```

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

### Initialize EQVelocity and prepare data

Source: https://seislib.readthedocs.io/en/latest/seislib.eq.html

Example of initializing an EQVelocity instance and preparing data for inter-station dispersion curve calculation. Assumes dispersion curves are located in /path/to/data.

```python
from seislib.eq import EQVelocity

eq = EQVelocity(src=SRC, component='Z')
eq.prepare_data(azimuth_tolerance=7,
                distmin=None, 
                distmax=3000, 
                min_no_events=8)

```

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

### Example of stations.pickle dictionary

Source: https://seislib.readthedocs.io/en/latest/seislib.eq.html

Shows the structure of the stations.pickle file saved by prepare_data, mapping station codes to latitude/longitude tuples.

```python
{ 
net1.sta1 : (lat1, lon1),
net1.sta2 : (lat2, lon2),
net2.sta3 : (lat3, lon3)
    }
```

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

### TwoStationMethod initialization example

Source: https://seislib.readthedocs.io/en/latest/seislib.eq.html

Initializes the TwoStationMethod class with a reference curve and parameters for period range, velocity range, and minimum number of wavelengths. The reference curve must have two columns: period and phase velocity (km/s or m/s).

```python
from seislib.eq import TwoStationMethod

tsm = TwoStationMethod(refcurve=refcurve,
                       periodmin=15,
                       periodmax=150,
                       no_periods=75,
                       cmin=2.5, 
                       cmax=5, 
                       min_no_wavelengths=1.5)
```

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

### Example timespans dictionary

Source: https://seislib.readthedocs.io/en/latest/seislib.an.html

Shows the format of the timespans.pickle file, where each value is a tuple of starttime and endtime timestamps.

```python
{ net1.sta1 : (starttime1, endtime1),
  net1.sta2 : (starttime2, endtime2),
  net2.sta3 : (starttime3, endtime3)
  }

```

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

### events_info dictionary example

Source: https://seislib.readthedocs.io/en/latest/seislib.eq.html

Example of the events_info dictionary where each key is an event origin time and each value is a tuple of latitude, longitude, and magnitude.

```python
{ '1222701570.84' : (lat1, lon1, mag1),
    '1237486660.74' : (lat2, lon2, mag2),
    '1239825695.33' : (lat3, lon3, mag3)
    }                 

```

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

### Example of stations.pickle dictionary structure

Source: https://seislib.readthedocs.io/en/latest/seislib.eq.html

Shows the dictionary format saved at $self.savedir/stations.pickle, mapping station codes to (lat, lon) tuples.

```python
{ net1.sta1 : (lat1, lon1),
  net1.sta2 : (lat2, lon2),
  net2.sta3 : (lat3, lon3)
  }
```

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

### Clone and compile seislib from source

Source: https://seislib.readthedocs.io/en/latest/_sources/installation.rst.txt

Alternative installation approach: clones the seislib repository, changes to the tomography/_ray_theory directory, and compiles the Cython files in place. The last command requires a C compiler (e.g., gcc). In an Anaconda environment, you may need to replace 'python' with the full path to your Python executable.

```console
~$ git clone https://github.com/fmagrini/seislib.git
~$ cd seislib/seislib/tomography/_ray_theory
~$ python setup_all.py build_ext --inplace
```

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

### Example timespans.pickle dictionary

Source: https://seislib.readthedocs.io/en/latest/seislib.an.html

Shows the expected format for the timespans.pickle file: a dictionary mapping station codes to tuples of starttime and endtime (as obspy.UTCDateTime.timestamp).

```python
{net1.sta1 : (starttime1, endtime1), net1.sta2 : (starttime2, endtime2)}
```

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

### prepare_data(recompute=False)

Source: https://seislib.readthedocs.io/en/latest/seislib.an.html

Saves to disk the geographic coordinates and the starting and ending time associated with each continuous seismogram.

```APIDOC
## prepare_data(recompute=False)

### Description
Saves to disk the geographic coordinates and the starting and ending time associated with each continuous seismogram.

### Method
prepare_data

### Parameters
- **recompute** (bool, optional) - Whether to recompute the data even if already saved. Default is False.

### Returns
None
```

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

### prepare_data(recompute=False)

Source: https://seislib.readthedocs.io/en/latest/seislib.an.html

Saves to disk the geographic coordinates and the starting and ending time associated with each continuous seismogram. These are saved to $self.savedir/stations.pickle and $self.savedir/timespans.pickle, respectively.

```APIDOC
## prepare_data(recompute=False)

### Description
Saves to disk the geographic coordinates and the starting and ending time associated with each continuous seismogram. These are saved to $self.savedir/stations.pickle and $self.savedir/timespans.pickle, respectively.

The stations.pickle file contains a dictionary object where each key corresponds to a station code ($network_code.$station_code) and each value is a tuple containing latitude and longitude of the station. For example:
```
{ net1.sta1 : (lat1, lon1),
  net1.sta2 : (lat2, lon2),
  net2.sta3 : (lat3, lon3)
  }
```

The timespans.pickle file contains a dictionary object similar to the above, where each value is a tuple containing the starttime and endtime (obspy.UTCDateTime.timestamp) of the continuous seismogram associated with the station. For example:
```
{ net1.sta1 : (starttime1, endtime1),
  net1.sta2 : (starttime2, endtime2),
  net2.sta3 : (starttime3, endtime3)
  }
```

### Parameters
- **recompute** (bool) - Optional - If True, recompute the data. Default is False.
```

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

### adapt_startime_to_t

Source: https://seislib.readthedocs.io/en/latest/seislib.eq.html

Zero-pads data to align the start time with the event origin time. Optionally returns a power-of-2 sized array for efficient FFT.

```APIDOC
## adapt_startime_to_t(data, dt, starttime, origintime, power_2_sized=True)

### Description
Zero-pads data in order to make the start time coincide with the event origin time.

### Parameters
- **data** (ndarray) - Required - Input data array.
- **dt** (float) - Required - Time sampling interval.
- **starttime** (obspy.UTCDateTime.timestamp) - Required - Starttime of the waveform.
- **origintime** (obspy.UTCDateTime.timestamp) - Required - Origin time of the event.
- **power_2_sized** (bool) - Optional - If True, the returned data size will be a power of 2. Default is True.

### Returns
- **numpy.ndarray** - Padded data.
```

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

### Example of triplets.pickle dictionary structure

Source: https://seislib.readthedocs.io/en/latest/seislib.eq.html

Shows the dictionary format saved at $self.savedir/triplets.pickle, mapping station pairs to lists of event timestamps.

```python
{ (net1.sta1, net2.sta2) : ['1222701570.84',
                            '1237378863.3', 
                            '1237486660.74',
                            '1238981562.62',
                            '1239825695.33'],

  (net3.sta3, net4.sta4) : ['1222701570.84',
                            '1237378863.3', 
                            '1237486660.74',
                            '1238981562.62',
                            '1239825695.33']
  }
```

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

### stations dictionary example

Source: https://seislib.readthedocs.io/en/latest/seislib.eq.html

Example of the stations dictionary where each key is a station code (network.station) and each value is a tuple of latitude and longitude.

```python
{ net1.sta1 : (lat1, lon1),
  net1.sta2 : (lat2, lon2),
  net2.sta3 : (lat3, lon3)
  }

```

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

### triplets dictionary example

Source: https://seislib.readthedocs.io/en/latest/seislib.eq.html

Example of the triplets dictionary where each key is a tuple of station codes and each value is a list of event origin times that are aligned on the same great circle path.

```python
{ (net1.sta1, net2.sta2) : ['1222701570.84',
                            '1237378863.3', 
                            '1237486660.74',
                            '1238981562.62',
                            '1239825695.33'],

  (net3.sta3, net4.sta4) : ['1222701570.84',
                            '1237378863.3', 
                            '1237486660.74',
                            '1238981562.62',
                            '1239825695.33']
  }

```

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

### Initialize AmbientNoiseVelocity instance

Source: https://seislib.readthedocs.io/en/latest/seislib.an.html

Creates an AmbientNoiseVelocity instance with component 'Z' and prepares data. This is the first step before calling prepare_input_tomography.

```python
an = AmbientNoiseVelocity(src=SRC,
                          component='Z')
an.prepare_data()
```

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

### Initialize EQVelocity and prepare data

Source: https://seislib.readthedocs.io/en/latest/seislib.eq.html

Creates an EQVelocity instance for vertical-component Rayleigh waves, then calls prepare_data with azimuth tolerance, distance limits, and minimum event count. The print output shows the class summary.

```python
>>> from seislib.eq import EQVelocity
>>> eq = EQVelocity(src, component='Z')
>>> eq.prepare_data(azimuth_tolerance=7, 
                    distmin=None, 
                    distmax=2500, 
                    min_no_events=8)
>>> print(eq)
RAYLEIGH-WAVE VELOCITY FROM TELESEISMIC EARTHQUAKES (TWO-STATION METHOD)
        =========================================================================
        EVENTS: X
        RECEIVERS: N.A.
        TRIPLETS (EPICENTER-RECEIVERS) AVAILABLE: N.A.
        DISPERSION CURVES RETRIEVED: Y
        =========================================================================
        SOURCE DIR: /path/to/data
        SAVE DIR: /path/to/eq_velocity/Z
```

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

### ANDownloader constructor

Source: https://seislib.readthedocs.io/en/latest/seislib.an.html

Initializes an ANDownloader instance to download continuous seismograms. Configure the download directory, inventory name, data provider, and various processing parameters.

```APIDOC
## ANDownloader(savedir, inventory_name, provider='iris', user=None, password=None, duration=43200, sampling_rate=1, units='disp', prefilter=(0.005, 0.01, 0.25, 0.5), attach_response=False, stations_config={}, sleep_time_after_exception=10, verbose=True, reversed_iterations=False, max_final_stream_duration=126144000)

### Description
Initializes an ANDownloader object to download continuous seismograms for ambient noise tomography. Data is saved in the format required by seislib.an.AmbientNoiseVelocity and seislib.an.AmbientNoiseAttenuation.

### Parameters
- **savedir** (str) - Required - Absolute path to the directory where data will be saved. A sub-directory 'data' will be created inside.
- **inventory_name** (str) - Required - Name of the inventory (obspy.core.inventory.inventory.Inventory) associated with the downloads. Saved in XML format in savedir.
- **provider** (str) - Optional - Provider of seismic data, passed to obspy.clients.fdsn.Client. Default is 'iris'.
- **user** (str) - Optional - User name for accessing restricted data. Passed to obspy.clients.fdsn.Client.
- **password** (str) - Optional - Password for accessing restricted data. Passed to obspy.clients.fdsn.Client.
- **duration** (float) - Optional - Duration (in seconds) of individual seismic waveforms to download. Default is 43200 (12h).
- **sampling_rate** (float) - Optional - Final sampling rate of waveforms in Hz. Default is 1 Hz.
- **prefilter** (tuple of floats) - Optional - Bandpass filter applied before removing instrument response. Default is (0.005, 0.01, 0.25, 0.5).
- **units** ({'DISP', 'VEL', 'ACC'}) - Optional - Physical units of final waveforms. Default is 'DISP'.
- **attach_response** (bool) - Optional - If True, attach instrument response details to waveform headers. Default is False.
- **stations_config** (dict) - Optional - Dictionary of optional keys and values passed to obspy.clients.fdsn.Client.get_stations.
- **sleep_time_after_exception** (float) - Optional - Time to wait (seconds) after an FDSNException. Default is 10.
- **verbose** (bool) - Optional - If True, print download information to console. Default is True.
- **reversed_iterations** (bool) - Optional - If True, iterate over station inventory in reversed order. Default is False.
- **max_final_stream_duration** (float) - Optional - Maximum length (seconds) of continuous waveforms. Default is 126144000 (4 years).

### Example
```python
from obspy import UTCDateTime as UTC

stations_config = dict(network='II',
                       channel='BH*',
                       starttime=UTC(2020, 1, 1),
                       endtime=UTC(2021, 1, 1),
                       includerestricted=False,
                       maxlatitude=12,
                       minlatitude=-18,
                       minlongitude=90,
                       maxlongitude=140)
```
```

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

### get_times_and_coords(files)

Source: https://seislib.readthedocs.io/en/latest/seislib.an.html

Retrieves the geographic coordinates and the starting and ending time associated with each continuous seismogram.

```APIDOC
## get_times_and_coords(files)

### Description
Retrieves the geographic coordinates and the starting and ending time associated with each continuous seismogram.

### Parameters
- **files** (list of str) - Required - Names of the files corresponding with the continuous seismograms, located in the src directory.

### Returns
- **times** (dict) - Each key corresponds to a station code ($network_code.$station_code) and each value is a tuple containing the starttime and endtime (in timestamp format, see obspy documentation on UTCDateTime.timestamp) of the continuous seismogram associated with the station. For example:
```
{ net1.sta1 : (starttime1, endtime1),
  net1.sta2 : (starttime2, endtime2),
  net2.sta3 : (starttime3, endtime3)
}
```
```

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

### prepare_data()

Source: https://seislib.readthedocs.io/en/latest/seislib.an.html

Prepares the data by reading the continuous seismograms and saving a station.pickle file in the savedir directory.

```APIDOC
## prepare_data()

### Description
Prepares the data by reading the continuous seismograms and saving a station.pickle file in the savedir directory.

### Method
prepare_data()

### Parameters
None

### Returns
None

### Notes
- The files must have a .sac extension and a proper SAC header, or the user must create a station.pickle file manually.
- File names should be in the format net.sta.loc.cha (e.g., TA.N38A..LHZ.sac).
- The station.pickle file should contain a dictionary mapping station codes (net.sta) to (latitude, longitude) tuples.

### Example
```python
an.prepare_data()
```
```

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

### get_times_and_coords(files)

Source: https://seislib.readthedocs.io/en/latest/seislib.an.html

Retrieves the geographic coordinates and the starting and ending time associated with each continuous seismogram.

```APIDOC
## get_times_and_coords(files)

### Description
Retrieves the geographic coordinates and the starting and ending time associated with each continuous seismogram.

### Method
get_times_and_coords

### Parameters
- **files** (list) - List of files to process.

### Returns
- **times_and_coords** (dict or similar) - Geographic coordinates and start/end times for each seismogram.
```

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

### Instantiate AmbientNoiseAttenuation and prepare data

Source: https://seislib.readthedocs.io/en/latest/seislib.an.html

Creates an AmbientNoiseAttenuation instance with source and save directories, then calls prepare_data(). This automatically saves a station.pickle file in the save directory. The waveform data must be in .sac format with proper headers.

```python
src = '/path/to/data'
save = '/savedir'
an = AmbientNoiseAttenuation(src=src, savedir=save, verbose=True)
an.prepare_data()
```

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

### fetch_catalog(t1, t2, **kwargs)

Source: https://seislib.readthedocs.io/en/latest/seislib.eq.html

Fetch catalog of seismic events between the given start and end times.

```APIDOC
## fetch_catalog(t1, t2, **kwargs)

### Description
Fetch catalog of seismic events between the given start and end times.

### Method
fetch_catalog

### Parameters
- **t1** (obspy.core.utcdatetime.UTCDateTime) - Required - Start time of the catalog.
- **t2** (obspy.core.utcdatetime.UTCDateTime) - Required - End time of the catalog.
- **kwargs** (dict, optional) - Additional keyword arguments passed to obspy.clients.fdsn.client.Client.get_events.

### Returns
- **obspy.core.event.catalog.Catalog** - Catalog of seismic events.
```

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

### adapt_times

Source: https://seislib.readthedocs.io/en/latest/seislib.eq.html

Zero-pads and slices two traces so that their starting and ending times coincide. Returns modified copies of the input traces.

```APIDOC
## adapt_times(tr1, tr2)

### Description
Zero-pads and slices the two traces so that their starting and ending times coincide.

### Parameters
- **tr1** (obspy.Trace) - Required - First trace.
- **tr2** (obspy.Trace) - Required - Second trace.

### Returns
- **tr1** (obspy.Trace) - Modified copy of the first trace.
- **tr2** (obspy.Trace) - Modified copy of the second trace.
```

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

### build_inventory(**kwargs)

Source: https://seislib.readthedocs.io/en/latest/seislib.eq.html

Builds an obspy inventory containing stations information. Downloads inventory information at station level and then instrument response for each channel.

```APIDOC
## build_inventory(**kwargs)

### Description
Builds an obspy inventory containing stations information. The strategy is to first download inventory information at station level. Then, for each station, the instrument response is downloaded for each channel. This may increase the downloading time, but prevents possible 'timed out errors'.

### Method
build_inventory

### Parameters
- **kwargs** (dict, optional) - Additional keyword arguments passed to the get_stations method of obspy.clients.fdsn.client.

### Returns
- **inv** (obspy.core.inventory.inventory.Inventory) - The built inventory.
```

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

### EQVelocity.__init__

Source: https://seislib.readthedocs.io/en/latest/seislib.eq.html

Initializes an EQVelocity instance to calculate surface-wave phase velocities from teleseismic earthquakes using the two-station method.

```APIDOC
## EQVelocity.__init__

### Description
Initializes an EQVelocity instance to calculate surface-wave phase velocities from teleseismic earthquakes using the two-station method.

### Method
Constructor

### Signature
`EQVelocity(src, savedir=None, component='Z', verbose=True)`

### Parameters
- **src** (str) - Required - Absolute path to the directory containing the files associated with the earthquake recordings. The directory should contain, for each event, a sub-directory named after the origin time of the earthquake in timestamp format (see obspy.UTCDateTime.timestamp). Inside each sub-directory, the seismograms associated with the respective event recorded at all the available receivers should be stored into sacfiles. These should be named after the trace id, i.e., net.sta.loc.cha.sac (see obspy.Trace.id). Furthermore, inside each event directory there should be either an xml containing the event coordinates (latitude, longitude), or these coordinates should be stored in the sac header of the related seismograms.
- **savedir** (str, optional) - Optional - Absolute path to the directory where the results are saved. If not provided, its value will be set to the parent directory of src (i.e., $src/..). All the results will be saved into the directory $savedir/eq_velocity/$component (see the component parameter).
- **component** ({'Z', 'R', 'T'}) - Optional - Either 'Z', 'R', (corresponding to vertically and radially polarized Rayleigh waves, respectively), or 'T' (for Love waves).
- **verbose** (bool) - Optional - Whether or not information on progress is printed in the console.

### Example
```
>>> from seislib.eq import EQVelocity
>>> eq = EQVelocity(src, component='Z')
```
```

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

### preprocess

Source: https://seislib.readthedocs.io/en/latest/seislib.eq.html

Reads SAC infos and prepares for pv extraction.

```APIDOC
## preprocess(st1, st2, otime, fs=None)

### Description
Read sac infos and prepare to pv extraction.

### Parameters
- **st1** - Required - First stream.
- **st2** - Required - Second stream.
- **otime** - Required - Origin time.
- **fs** - Optional - Sampling frequency.

### Returns
- Not documented in the source.
```

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

### Prepare data with an.prepare_data()

Source: https://seislib.readthedocs.io/en/latest/seislib.an.html

Runs the prepare_data method to extract station coordinates and time windows from SAC file headers. This creates stations.pickle and timespans.pickle files in the save directory.

```python
an.prepare_data()
```

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

### AmbientNoiseVelocity.__init__

Source: https://seislib.readthedocs.io/en/latest/seislib.an.html

Constructor for the AmbientNoiseVelocity class. Initializes the object with source directory, save directory, component, and verbosity settings.

```APIDOC
## AmbientNoiseVelocity.__init__

### Description
Initializes an AmbientNoiseVelocity object to calculate surface-wave phase velocities from continuous seismograms via cross-correlation of seismic ambient noise.

### Method
Constructor

### Parameters
- **src** (str) - Required - Absolute path to the directory containing the files associated with the continuous seismograms.
- **savedir** (str, optional) - Optional - Absolute path to the directory where results are saved. If not provided, set to parent directory of src. Results saved in $savedir/an_velocity/$component.
- **component** ({'Z', 'R', 'T'}) - Required - Either 'Z', 'R' (Rayleigh waves) or 'T' (Love waves).
- **verbose** (bool) - Required - Whether to print progress information to console.

### Example
```python
>>> from seislib.an import AmbientNoiseVelocity
>>> an = AmbientNoiseVelocity(
...         src=src,
...         component='Z')
>>> print(an)
RAYLEIGH-WAVE VELOCITY FROM SEISMIC AMBIENT NOISE
==================================================
RECEIVERS: X
STATION PAIRS AVAILABLE: Y
DISPERSION CURVES RETRIEVED: 0
==================================================
SOURCE DIR: /path/to/data
SAVE DIR: /path/to/an_velocity/Z
```
```

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

### Interpolate dispersion curves

Source: https://seislib.readthedocs.io/en/latest/seislib.eq.html

Example of interpolating dispersion curves at specified periods using the interpolate_dispcurves method. Returns codes, coordinates, and measurements.

```python
period = [20, 30, 40, 50]
codes, coords, measurements = eq.interpolate_dispcurves(period)  

```

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

### prepare_inversion(_src_velocity_, _freqmin=0.05_, _freqmax=0.4_, _nfreq=300_, _smooth=False_, _smoothing_window=25_, _smoothing_poly=2_)

Source: https://seislib.readthedocs.io/en/latest/seislib.an.html

Prepares the data set to be inverted for Rayleigh-wave attenuation. The data set used in the inversion, for each station pair, consists of (i) envelope of the cross-spectrum, (ii) envelope of the associated Bessel function J0, (iii) phase velocity, (iv) inter-station distance. These objects are collected, for each grid cell associated with the parameterization, for all station pairs available, and stored into a dictionary object that is written on disk at $self.savedir/inversion_dataset.

```APIDOC
## prepare_inversion(_src_velocity_, _freqmin=0.05_, _freqmax=0.4_, _nfreq=300_, _smooth=False_, _smoothing_window=25_, _smoothing_poly=2_)

### Description
Prepares the data set to be inverted for Rayleigh-wave attenuation. The data set used in the inversion, for each station pair, consists of (i) envelope of the cross-spectrum, (ii) envelope of the associated Bessel function J0, (iii) phase velocity, (iv) inter-station distance. These objects are collected, for each grid cell associated with the parameterization, for all station pairs available, and stored into a dictionary object that is written on disk at $self.savedir/inversion_dataset.

### Parameters
- **src_velocity** (str) - Required - Absolute path to the directory containing the phase-velocity dispersion curves associated with the station pairs for which cross-spectra are available.
- **freqmin** (float) - Optional - Frequency range to analyse. Default is 0.05 Hz.
- **freqmax** (float) - Optional - Frequency range to analyse. Default is 0.4 Hz.
- **nfreq** (float) - Optional - The frequency range in question will be subdivided in nfreq points geometrically spaced (see numpy.geomspace). Default is 300.
- **smooth** (bool) - Optional - If True, the cross-spectra envelopes are smoothing with a Savitzky-Golay filter. Default is False.
- **smoothing_window** (odd int) - Optional - Passed to scipy.signal.savgol_filter. Default is 25.
- **smoothing_poly** (int) - Optional - Passed to scipy.signal.savgol_filter. Default is 2.
```

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

### Triplets dictionary structure example

Source: https://seislib.readthedocs.io/en/latest/seislib.eq.html

Shows the structure of the triplets.pickle file: a dictionary mapping station pairs to lists of event origin times (as strings). Each list has at least min_no_events entries (8 in this context).

```python
{ 
(net1.sta1, net2.sta2) : ['1222701570.84',
                          '1237378863.3', 
                          '1237486660.74',
                          '1238981562.62',
                          '1239825695.33',
                          etc.],

(net3.sta3, net4.sta4) : ['1222701570.84',
                          '1237378863.3',
                          '1237486660.74',
                          '1238981562.62',
                          '1239825695.33',
                          etc.]
    }
```

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

### Get and plot attenuation map

Source: https://seislib.readthedocs.io/en/latest/seislib.an.html

Calculates an attenuation map at a period of 4 s with an equal-area grid of pixel-size 1 degree. Only grid cells with at least 2 attenuation curves (min_overlapping_pixels=2) are attributed an attenuation value. The map is then plotted.

```python
grid, attenuation = an.get_attenuation_map(period=4,
                                           cell_size=1,
                                           min_overlapping_pixels=2)
an.plot_map(grid, attenuation)

```

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

### Grid.load

Source: https://seislib.readthedocs.io/en/latest/seislib.tomography.html

Load a grid from disk, returning the appropriate subclass.

```APIDOC
## Grid.load(path, fmt=None, verbose=None)

### Description
Load a grid saved with Grid.save. If called as Grid.load(…), the method inspects the saved class name and returns the appropriate subclass (EqualAreaGrid or RegularGrid). If called as EqualAreaGrid.load(…) or RegularGrid.load(…), it enforces that the file contains the expected subclass.

### Method
classmethod

### Parameters
- **path** (str or pathlib.Path) - Required - Input file path.
- **fmt** ({'npz', 'pickle'}, optional) - Storage format. If None, inferred from file extension.
- **verbose** (bool, optional) - If not None, overrides the verbose attribute of the loaded grid.

### Returns
- **Grid** - An EqualAreaGrid or RegularGrid instance.
```

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

### zeropad(tr, starttime, endtime)

Source: https://seislib.readthedocs.io/en/latest/seislib.utils.html

Zeropads an obspy.Trace to cover the specified time window.

```APIDOC
## zeropad(tr, starttime, endtime)

### Description
Zeropads an obspy.Trace to cover the specified time window.

### Parameters
- **tr** (obspy.Trace) - Required - Input trace.
- **starttime, endtime** (obspy.UTCDateTime) - Required - Time window to cover.

### Returns
- **trace** (obspy.Trace) - Zeropadded copy of the input trace.
```

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

### Format y-axis ticks with scientific_label

Source: https://seislib.readthedocs.io/en/latest/seislib.plotting.html

Example usage of the scientific_notation function to format y-axis tick labels in scientific notation. It creates a plot of y = x^2 * 1e-5, retrieves the y-tick values, and replaces them with labels generated by scientific_label(i, 1). Requires numpy and matplotlib.

```python
>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> x = np.linspace(-2, 2, 150)
>>> y = x**2 * 1e-5
>>> plt.plot(x, y)
>>> ticks = plt.gca().get_yticks()
>>> labels = [r'$%s$'%scientific_label(i, 1) for i in ticks]
>>> plt.yticks(ticks=ticks, labels=labels)
>>> plt.show()
```