Skip to content

Commit

Permalink
docs: improve docstrings
Browse files Browse the repository at this point in the history
  • Loading branch information
@schmidni
schmidni committed Feb 24, 2025
1 parent 8e4d778 commit ebefcf9
Show file tree
Hide file tree
Showing 2 changed files with 92 additions and 69 deletions.
83 changes: 54 additions & 29 deletions seismostats/io/client.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,18 +8,19 @@


class FDSNWSEventClient():
"""
Client for downloading earthquake catalogs from the FDSNWS event service.
Args:
url: base url of the FDSNWS event service
(eg. 'https://earthquake.usgs.gov/fdsnws/event/1/query')
"""

def __init__(self, url: str):
"""
Client for downloading earthquake catalogs from the
FDSNWS event service.
Args:
url: base url of the FDSNWS event service
(eg. 'https://earthquake.usgs.gov/fdsnws/event/1/query')
"""
self.url = url

def get_events(self, start_time: datetime | None = None,
def get_events(self,
start_time: datetime | None = None,
end_time: datetime | None = None,
min_latitude: float | None = None,
max_latitude: float | None = None,
Expand All @@ -36,29 +37,53 @@ def get_events(self, start_time: datetime | None = None,
"""Downloads an earthquake catalog based on a URL.
Args:
start_time: start time of the catalog.
end_time: end time of the catalog. defaults to
current time.
min_latitude: minimum latitude of catalog.
max_latitude: maximum latitude of catalog.
min_longitude: minimum longitude of catalog.
max_longitude: maximum longitude of catalog.
min_magnitude: minimum magnitude of catalog.
max_magnitude: maximum magnitude of catalog.
include_all_magnitudes: whether to include all magnitudes.
event_type: type of event to download.
delta_m: magnitude bin size. if >0, then events of
magnitude >= (min_magnitude - delta_m/2)
will be downloaded.
include_uncertainty: whether to include uncertainty columns.
include_ids: whether to include event, magnitude
and origin IDs.
include_quality: whether to include quality columns.
start_time: Start time of the catalog.
end_time: End time of the catalog.
min_latitude: Minimum latitude of the catalog.
max_latitude: Maximum latitude of the catalog.
min_longitude: Minimum longitude of the catalog.
max_longitude: Maximum longitude of the catalog.
min_magnitude: Minimum magnitude of the catalog.
max_magnitude: Maximum magnitude of the catalog.
include_all_magnitudes: Whether to include all magnitudes.
event_type: Filter by the type of events.
delta_m: Magnitude bin size. If >0, then events of
`magnitude >= (min_magnitude - delta_m/2)`
will be downloaded.
include_uncertainty: Whether to include uncertainty columns.
include_ids: Whether to include event,
magnitude and origin IDs.
include_quality: Whether to include quality columns.
Returns:
The catalog as a Catalog Object.
catalog: The catalog as a Catalog Object.
Examples:
Create a Catalog from a dictionary.
>>> from seismostats.io import FDSNWSClient
>>> from datetime import datetime
>>> url = 'http://eida.ethz.ch/fdsnws/event/1/query'
>>> client = FDSNWSClient(url)
>>> df = client.get_events(
... start_time=datetime(2020, 1, 1),
... end_time=datetime(2022, 1, 1),
... min_magnitude=0.5,
... min_longitude=5,
... max_longitude=11,
... min_latitude=45,
... max_latitude=48)
>>> print(df)
event_type time latitude longitude magnitude
0 earthquake 2021-12-30 07:43:14 46.051445 7.388025 2.510115 ...
1 earthquake 2021-12-30 01:35:37 46.778985 9.476219 1.352086 ...
2 earthquake 2021-12-29 08:48:59 47.779511 7.722354 0.817480 ...
3 earthquake 2021-12-29 00:14:32 47.715341 7.634432 1.252432 ...
4 earthquake 2021-12-28 11:51:38 45.752843 7.080092 0.897306 ...
... ... ... ... ... ...
"""

request_url = self.url + '?'
date_format = "%Y-%m-%dT%H:%M:%S"

Expand Down
78 changes: 38 additions & 40 deletions seismostats/io/parser.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -83,10 +83,17 @@ def _select_origin_by_id(origins: list, id: str) -> tuple[dict, list]:
return preferred, origins


def _select_secondary_magnitudes(magnitudes: list):
def _select_secondary_magnitudes(magnitudes: list) -> list:
"""
Check the magnitudes for multiple magnitudes of the same type and
select the one with the highest version number and creation time.
Args:
magnitudes: The magnitudes to select from and check for multiple
versions.
Returns:
selected: The selected magnitudes.
"""
magnitude_types = set(m['magnitudetype'] for m in magnitudes)

Expand Down Expand Up @@ -150,27 +157,27 @@ def _extract_secondary_magnitudes(magnitudes: list) -> dict:
return magnitude_dict


def _parse_to_dict(event: dict, origins: list, magnitudes: list,
def _parse_to_dict(event: dict,
origins: list[dict],
magnitudes: list[dict],
include_all_magnitudes: bool = True,
include_quality: bool = True) -> dict:
"""
Parse earthquake event information dictionaries as produced by the
QuakeMLHandler and return a dictionary of event parameters.
Args:
event : dict
A dictionary representing the earthquake event.
origins : list
A list of dictionaries representing the earthquake origins.
magnitudes : list
A list of dictionaries representing the earthquake magnitudes.
include_all_magnitudes : bool, optional
If True, include all magnitudes in the output dictionary.
Otherwise, only include the preferred magnitude.
event: The earthquake event.
origins: The earthquake origins.
magnitudes: The earthquake magnitudes.
include_all_magnitudes: If True, include all magnitudes in the
output dictionary. Otherwise, only include
the preferred magnitude.
include_quality: If True, include quality information in the output
dictionary.
Returns:
dict
A dictionary of earthquake event parameters.
event_params: Full dictionary of earthquake event parameters.
"""
preferred_origin, _ = \
_select_origin_by_id(origins,
Expand Down Expand Up @@ -200,11 +207,9 @@ class QuakeMLHandler(xml.sax.ContentHandler):
earthquake event information.
Args:
catalog : Catalog
A Catalog object to store the extracted earthquake events.
include_all_magnitudes : bool, optional
If True, include all magnitudes in the catalog. Otherwise,
only include the preferred magnitude.
catalog: Object to store the extracted earthquake events.
include_all_magnitudes: If True, include all magnitudes in the catalog.
Otherwise, only include the preferred magnitude.
Notes:
This class is a SAX ContentHandler, and is used in conjunction
with an xml.sax parser to extract earthquake event information
Expand Down Expand Up @@ -271,20 +276,18 @@ def endDocument(self):
pass


def parse_quakeml_file(
file_path: str, include_all_magnitudes: bool = True,
include_quality: bool = True) -> list[dict]:
def parse_quakeml_file(file_path: str,
include_all_magnitudes: bool = True,
include_quality: bool = True) -> list[dict]:
"""
Parse a QuakeML file and return a list of earthquake event information
dictionaries.
Args:
file_path : str
Path to the QuakeML file.
file_path : Path to the QuakeML file.
Returns:
list[dict]
A list of earthquake event information dictionaries.
events: A list of earthquake event information dictionaries.
"""
data = []
handler = QuakeMLHandler(data, include_all_magnitudes, include_quality)
Expand All @@ -299,20 +302,18 @@ def parse_quakeml_file(
return data


def parse_quakeml(
quakeml: str, include_all_magnitudes: bool = True,
include_quality: bool = True) -> list[dict]:
def parse_quakeml(quakeml: str,
include_all_magnitudes: bool = True,
include_quality: bool = True) -> list[dict]:
"""
Parse a QuakeML string and return a list of earthquake event information
dictionaries.
Args:
quakeml : str
A QuakeML string.
quakeml : A QuakeML string.
Returns:
list[dict]
A list of earthquake event information dictionaries.
events: A list of earthquake event information dictionaries.
"""
data = []

Expand All @@ -324,21 +325,18 @@ def parse_quakeml(
return data


def parse_quakeml_response(
response: Response,
include_all_magnitudes: bool = True,
include_quality: bool = True) -> list[dict]:
def parse_quakeml_response(response: Response,
include_all_magnitudes: bool = True,
include_quality: bool = True) -> list[dict]:
"""
Parse a QuakeML response and return a list of earthquake event information
dictionaries.
Args:
response : Response
A response object from a QuakeML request.
response: A response object from a QuakeML request.
Returns:
list[dict]
A list of earthquake event information dictionaries.
events: A list of earthquake event information dictionaries.
"""
response.raw.decode_content = True # if content-encoding is used decode
data = []
Expand Down

0 comments on commit ebefcf9

Please sign in to comment.