Update docs: add metadata statistics

Author: jaydu1

delphi_epidata/_endpoints.py

@@ -347,7 +347,69 @@ def covid_hosp_state_timeseries(
         )
 
     def covidcast_meta(self) -> CALL_TYPE:
-        """Fetch Delphi's COVID-19 Surveillance Streams metadata"""
+        """Fetch COVIDcast surveillance stream metadata.
+
+        Obtains a data frame of metadata describing all publicly available data
+        streams from the COVIDcast API. See the `data source and signals
+        documentation
+        <https://cmu-delphi.github.io/delphi-epidata/api/covidcast_signals.html>`_
+        for descriptions of the available sources.
+
+        :returns: A `EpiDataCall` object containing the following information:
+
+            ``data_source``
+                Data source name.
+
+            ``signal``
+                Signal name.
+
+            ``time_type``
+                Temporal resolution at which this signal is reported. "day", for
+                example, means the signal is reported daily.
+
+            ``geo_type``
+                Geographic level for which this signal is available, such as county,
+                state, msa, hss, hrr, or nation. Most signals are available at multiple geographic
+                levels and will hence be listed in multiple rows with their own
+                metadata.
+
+            ``min_time``
+                First day for which this signal is available. For weekly signals, will be
+                the first day of the epiweek.
+
+            ``max_time``
+                Most recent day for which this signal is available. For weekly signals, will be
+                the first day of the epiweek.
+
+            ``num_locations``
+                Number of distinct geographic locations available for this signal. For
+                example, if `geo_type` is county, the number of counties for which this
+                signal has ever been reported.
+
+            ``min_value``
+                The smallest value that has ever been reported.
+
+            ``max_value``
+                The largest value that has ever been reported.
+
+            ``mean_value``
+                The arithmetic mean of all reported values.
+
+            ``stdev_value``
+                The sample standard deviation of all reported values.
+
+            ``last_update``
+                The UTC datetime for when the signal value was last updated.
+
+            ``max_issue``
+                Most recent date data was issued.
+
+            ``min_lag``
+                Smallest lag from observation to issue, in days.
+
+            ``max_lag``
+                Largest lag from observation to issue, in days.
+        """
         return self._create_call(
             "covidcast_meta/",
             {},

docs/signals_covid.rst

@@ -4,16 +4,25 @@ Fetching Data
 Signals
 -------
 
+This package provides a key function to obtain any signal of interest as a
+Pandas data frame. Detailed examples are provided in the :ref:`usage examples
+<getting-started>`.
 
 
 
+Sometimes you would like to work with multiple signals -- for example, to obtain
+several signals at every location, as part of building models of features at
+each location. For convenience, the package provides a function to produce a
+single data frame containing multiple signals at each location.
+
+
 
 
 Metadata
 --------
 
 Many data sources and signals are available, so one can also obtain a data frame
-of all signals and their associated metadata
+of all signals and their associated metadata:
 
 >>> from delphi_epidata.request import CovidcastEpidata
 >>> covid_ds = CovidcastEpidata()
@@ -28,3 +37,9 @@ More details of the two data frames are listed below.
 .. autoclass:: delphi_epidata.request.CovidcastDataSources()
     :members:
 
+More metadata statistics can also be obtained as follows:
+
+>>> from delphi_epidata.request import Epidata
+>>> df = Epidata.covidcast_meta().df()
+
+.. autofunction:: delphi_epidata.request.Epidata.covidcast_meta()