diff --git a/csep/__init__.py b/csep/__init__.py index 2ce613af..2710d0f5 100644 --- a/csep/__init__.py +++ b/csep/__init__.py @@ -214,7 +214,7 @@ def query_comcat(start_time, end_time, min_magnitude=2.50, verbose (bool): print catalog summary statistics Returns: - :class:`csep.core.catalogs.CSEPCatalog + :class:`csep.core.catalogs.CSEPCatalog` """ # Timezone should be in UTC @@ -273,7 +273,7 @@ def query_bsi(start_time, end_time, min_magnitude=2.50, verbose (bool): print catalog summary statistics Returns: - :class:`csep.core.catalogs.CSEPCatalog + :class:`csep.core.catalogs.CSEPCatalog` """ # Timezone should be in UTC @@ -429,8 +429,8 @@ class with the region and magnitude members correctly assigned. Args: fname (str): path of grid based forecast loader (func): function to load forecast in bespoke format needs to return :class:`csep.core.forecasts.GriddedForecast` - and first argument should be required and the filename of the forecast to load - called as loader(func, **kwargs). + and should be called with the filename of the forecast to load as the first argument, + followed by additional keyword arguments, like this: ``loader(func, **kwargs)``. **kwargs: passed into loader function diff --git a/csep/core/forecasts.py b/csep/core/forecasts.py index 37860e91..333af409 100644 --- a/csep/core/forecasts.py +++ b/csep/core/forecasts.py @@ -363,7 +363,7 @@ def from_custom(cls, func, func_args=(), **kwargs): """ Creates MarkedGriddedDataSet class from custom parsing function. Args: - func (callable): function will be called as func(*func_args). + func (callable): function will be called as func(func_args). func_args (tuple): arguments to pass to func **kwargs: keyword arguments to pass to the GriddedForecast class constructor. @@ -756,6 +756,7 @@ def load_ascii(cls, fname, **kwargs): fname (str): path to file or directory containing forecast files Returns: - :class:`csep.core.forecasts.CatalogForecast + :class:`csep.core.forecasts.CatalogForecast` + """ raise NotImplementedError("load_ascii is not implemented!") \ No newline at end of file diff --git a/csep/utils/comcat.py b/csep/utils/comcat.py index 1f22cb2a..b0c0feb8 100644 --- a/csep/utils/comcat.py +++ b/csep/utils/comcat.py @@ -80,110 +80,89 @@ def search(starttime=None, host=None, enable_limit=False, verbose=False): - """Search the ComCat database for events matching input criteria. + """ + + Search the ComCat database for events matching input criteria. This search function is a wrapper around the ComCat Web API described here: https://earthquake.usgs.gov/fdsnws/event/1/ Some of the search parameters described there are NOT implemented here, usually because they do not apply to GeoJSON search results, which we are getting here and parsing into Python data structures. This function returns a list of SummaryEvent objects, described elsewhere in this package. - Usage: - TODO: Show usage information. + Args: - starttime (datetime): - Python datetime - Limit to events on or after the specified start time. - endtime (datetime): - Python datetime - Limit to events on or before the specified end time. - updatedafter (datetime): - Python datetime - Limit to events updated after the specified time. - minlatitude (float): - Limit to events with a latitude larger than the specified minimum. - maxlatitude (float): - Limit to events with a latitude smaller than the specified maximum. - minlongitude (float): - Limit to events with a longitude larger than the specified minimum. - maxlongitude (float): - Limit to events with a longitude smaller than the specified maximum. - latitude (float): - Specify the latitude to be used for a radius search. - longitude (float): - Specify the longitude to be used for a radius search. - maxradiuskm (float): - Limit to events within the specified maximum number of kilometers + starttime (datetime): Limit to events on or after the specified start time. + endtime (datetime): Limit to events on or before the specified end time. + updatedafter (datetime): Limit to events updated after the specified time. + minlatitude (float): Limit to events with a latitude larger than the specified minimum. + maxlatitude (float): Limit to events with a latitude smaller than the specified maximum. + minlongitude (float): Limit to events with a longitude larger than the specified minimum. + maxlongitude (float): Limit to events with a longitude smaller than the specified maximum. + latitude (float): Specify the latitude to be used for a radius search. + longitude (float): Specify the longitude to be used for a radius search. + maxradiuskm (float): Limit to events within the specified maximum number of kilometers from the geographic point defined by the latitude and longitude parameters. - maxradius (float): - Limit to events within the specified maximum number of degrees + maxradius (float): Limit to events within the specified maximum number of degrees from the geographic point defined by the latitude and longitude parameters. - catalog (str): - Limit to events from a specified catalog. - contributor (str): - Limit to events contributed by a specified contributor. - limit (int): - Limit the results to the specified number of events. - NOTE, this will be throttled by this Python API to the supported Web API limit of 20,000. - maxdepth (float): - Limit to events with depth less than the specified maximum. - maxmagnitude (float): - Limit to events with a magnitude smaller than the specified maximum. - mindepth (float): - Limit to events with depth more than the specified minimum. - minmagnitude (float): - Limit to events with a magnitude larger than the specified minimum. - offset (int): - Return results starting at the event count specified, starting at 1. - orderby (str): - Order the results. The allowed values are: - - time order by origin descending time - - time-asc order by origin ascending time - - magnitude order by descending magnitude - - magnitude-asc order by ascending magnitude - alertlevel (str): - Limit to events with a specific PAGER alert level. The allowed values are: - - green Limit to events with PAGER alert level "green". - - yellow Limit to events with PAGER alert level "yellow". - - orange Limit to events with PAGER alert level "orange". - - red Limit to events with PAGER alert level "red". - eventtype (str): - Limit to events of a specific type. NOTE: "earthquake" will filter non-earthquake events. - maxcdi (float): - Maximum value for Maximum Community Determined Intensity reported by DYFI. - maxgap (float): - Limit to events with no more than this azimuthal gap. - maxmmi (float): - Maximum value for Maximum Modified Mercalli Intensity reported by ShakeMap. - maxsig (float): - Limit to events with no more than this significance. - mincdi (float): - Minimum value for Maximum Community Determined Intensity reported by DYFI. - minfelt (int): - Limit to events with this many DYFI responses. - mingap (float): - Limit to events with no less than this azimuthal gap. - minsig (float): - Limit to events with no less than this significance. - producttype (str): - Limit to events that have this type of product associated. Example producttypes: - - moment-tensor - - focal-mechanism - - shakemap - - losspager - - dyfi - productcode (str): - Return the event that is associated with the productcode. - The event will be returned even if the productcode is not - the preferred code for the event. Example productcodes: - - nn00458749 - - at00ndf1fr - reviewstatus (str): - Limit to events with a specific review status. The different review statuses are: - - automatic Limit to events with review status "automatic". - - reviewed Limit to events with review status "reviewed". - host (str): - Replace default ComCat host (earthquake.usgs.gov) with a custom host. + catalog (str): Limit to events from a specified catalog. + contributor (str): Limit to events contributed by a specified contributor. + limit (int): Limit the results to the specified number of events. + NOTE: this will be throttled by this Python API to the supported Web API limit of 20,000. + maxdepth (float): Limit to events with depth less than the specified maximum. + maxmagnitude (float): Limit to events with a magnitude smaller than the specified maximum. + mindepth (float): Limit to events with depth more than the specified minimum. + minmagnitude (float): Limit to events with a magnitude larger than the specified minimum. + offset (int): Return results starting at the event count specified, starting at 1. + orderby (str): Order the results. The allowed values are: + + - `time`: order by origin descending time + - `time-asc`: order by origin ascending time + - `magnitude`: order by descending magnitude + - `magnitude-asc`: order by ascending magnitude + + alertlevel (str): Limit to events with a specific PAGER alert level. The allowed values are: + + - `green`: Limit to events with PAGER alert level "green". + - `yellow`: Limit to events with PAGER alert level "yellow". + - `orange`: Limit to events with PAGER alert level "orange". + - `red`: Limit to events with PAGER alert level "red". + + eventtype (str): Limit to events of a specific type. NOTE: "earthquake" will filter non-earthquake events. + maxcdi (float): Maximum value for Maximum Community Determined Intensity reported by DYFI. + maxgap (float): Limit to events with no more than this azimuthal gap. + maxmmi (float): Maximum value for Maximum Modified Mercalli Intensity reported by ShakeMap. + maxsig (float): Limit to events with no more than this significance. + mincdi (float): Minimum value for Maximum Community Determined Intensity reported by DYFI. + minfelt (int): Limit to events with this many DYFI responses. + mingap (float): Limit to events with no less than this azimuthal gap. + minsig (float): Limit to events with no less than this significance. + producttype (str): Limit to events that have this type of product associated. Example product types: + + - `moment-tensor` + - `focal-mechanism` + - `shakemap` + - `losspager` + - `dyfi` + + productcode (str): Return the event that is associated with the product code. + The event will be returned even if the product code is not + the preferred code for the event. Example product codes: + + - `nn00458749` + - `at00ndf1fr` + + reviewstatus (str): Limit to events with a specific review status. The different review statuses are: + + - `automatic`: Limit to events with review status "automatic". + - `reviewed`: Limit to events with review status "reviewed". + + host (str): Replace default ComCat host (earthquake.usgs.gov) with a custom host. enable_limit (bool): Enable 20,000 event search limit. Will turn off searching in segments, which is meant to safely avoid that limit. Use only when you are certain your search will be small. + Returns: list: List of SummaryEvent() objects. + """ # getting the inputargs must be the first line of the method! inputargs = locals().copy() diff --git a/docs/concepts/catalogs.rst b/docs/concepts/catalogs.rst index fb351d83..fb12a184 100644 --- a/docs/concepts/catalogs.rst +++ b/docs/concepts/catalogs.rst @@ -187,7 +187,7 @@ Once you have a function that returns an eventlist, you can create the catalog o eventlist = my_custom_web_loader(...) catalog = csep.catalogs.CSEPCatalog(data=eventlist, **kwargs) -The **kwargs represents any other keyword argument that can be passed to +The `**kwargs` represents any other keyword argument that can be passed to :class:`CSEPCatalog`. This could be the ``catalog_id`` or the :class:`CartesianGrid2D`. @@ -216,6 +216,7 @@ provide some getter methods to access the essential catalog data. These return a ``dtype`` defined by the class. .. automodule:: csep.core.catalogs + :no-index: The following functions return :class:`numpy.ndarrays` of the catalog information. @@ -287,7 +288,7 @@ object to filter events using the data type. The filter function can accept a string or a list of filter statements. If the function is called without any arguments the function looks to use the ``catalog.filters`` member. This can be provided during class instantiation or bound -to the class afterward. :ref:`Here` is complete example of how to filter a catalog +to the class afterward. :ref:`Here ` is complete example of how to filter a catalog using the filtering strings. Filtering events in space diff --git a/docs/concepts/evaluations.rst b/docs/concepts/evaluations.rst index 4e26ae81..c01d6b47 100644 --- a/docs/concepts/evaluations.rst +++ b/docs/concepts/evaluations.rst @@ -1,6 +1,7 @@ .. _evaluation-reference: .. automodule:: csep.core.poisson_evaluations + :no-index: ########### Evaluations @@ -94,6 +95,7 @@ details please follow the links below and see the :ref:`example`_. +`here `__. The coordinates (LON, LAT, DEPTH, MAG) describe the independent space-magnitude region of the forecast. The lower @@ -79,7 +79,7 @@ the forecast into the appropriate format in the first place. This function has n expected data. .. automethod:: csep.core.forecasts.GriddedForecast.from_custom - + :no-index: Working with quadtree-gridded forecasts ############################################## @@ -131,7 +131,7 @@ Working with catalog-based forecasts Please see visit :ref:`this` example for an end-to-end tutorial on how to evaluate a catalog-based earthquake forecast. An example of a catalog-based forecast stored in the default pyCSEP format can be found -`here `_. +`here `__. The standard format for catalog-based forecasts a comma separated value ASCII format. This format was chosen to be @@ -139,7 +139,7 @@ human-readable and easy to implement in all programming languages. Information a .. note:: Custom formats can be supported by writing a custom function or sub-classing the - :ref:`AbstractBaseCatalog`. + :class:`AbstractBaseCatalog `. The event format matches the follow specfication: :: diff --git a/docs/concepts/plots.rst b/docs/concepts/plots.rst deleted file mode 100644 index 321b5e03..00000000 --- a/docs/concepts/plots.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. _plots-reference: - -##### -Plots -##### - -PyCSEP provides several functions to produce commonly used plots, such as an earthquake forecast or the evaluation catalog -or perhaps a combination of the two. - -.. contents:: Table of Contents - :local: - :depth: 2 - -************ -Introduction -************ - - - -************** -Plot arguments -************** - -*************** -Available plots -*************** - diff --git a/docs/concepts/regions.rst b/docs/concepts/regions.rst index 9a26fb12..23b1b316 100644 --- a/docs/concepts/regions.rst +++ b/docs/concepts/regions.rst @@ -1,10 +1,11 @@ -.. _regions-reference +.. _regions-reference: ####### Regions ####### .. automodule:: csep.utils.basic_types + :no-index: PyCSEP includes commonly used CSEP testing regions and classes that facilitate working with gridded data sets. This module is early in development and will be a focus of future development. @@ -16,6 +17,7 @@ module is early in development and will be a focus of future development. .. :currentmodule:: csep .. automodule:: csep.core.regions + :no-index: Practically speaking, earthquake forecasts, especially time-dependent forecasts, treat time differently than space and magnitude. If we consider a family of monthly forecasts for the state of California for earthquakes with **M** 3.95+, @@ -98,9 +100,10 @@ mapping defined in (2). The :meth:`get_index_of` consistent with @@ -112,9 +115,10 @@ these regions. italy_csep_region global_region -.. **************** +.. ************* + Region Utilities -######################## +################ PyCSEP also provides some utilities that can facilitate working with regions. As we expand this module, we will include functions to accommodate different use-cases. @@ -192,7 +196,7 @@ Creating spatial regions Here, we describe how the class works starting with the class constructors and how users can create different types regions. Multi-resolution grid based on earthquake catalog ------------------------------------------ +------------------------------------------------- Read a global earthquake catalog in :class:`CSEPCatalog` format and use it to generate a multi-resolution quadtree-based grid constructors. :: @classmethod @@ -200,7 +204,7 @@ Read a global earthquake catalog in :class:`CSEPCatalog