fix many formatting issues within docstrings, add biblioghraphy to ma…

…nual

README.rst

@@ -68,7 +68,7 @@ Protocol (HTTP) so there is no need to install external ODBC drivers, configure
 ODBC connections or deal with the security vulnerabilities associated with
 them. Most functions have a parameter, return_header which by default is set
 to FALSE. If the user decides to set return_header to TRUE, then that function
-will return a python 3 AQS_DATAMART_APIv2 object. An AQS_DATAMART_APIv2 object
+will return a python 3 AQSAPI_V2 object. An AQSAPI_V2 object
 has instance methods for retrieving the data requested, header information,
 and other metadata related to the API call. After each call to the API a five
 second stall is invoked to help prevent overloading the Data Mart API server

docs/_build/html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 76a68937cbe1e6a63755071eed15d2c3
+config: 0abb323b0f8e893bc66a17fa59e0f212
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_build/html/_sources/index.rst.txt

@@ -1,27 +1,30 @@
 .. pyaqsapi documentation master file, created by
-   sphinx-quickstart on Mon Oct  4 14:40:23 2021.
+   sphinx-quickstart on Mon Oct 4 14:40:23 2021.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-.. sectionauthor:: Clinton Mccrowey <mccrowey.clinton <AT> epa.gov>
+
+.. sectionauthor:: Clinton Mccrowey <mccrowey <DOT> clinton <AT> epa.gov>
 
 ===========================
 pyaqsapi user documentation
 ===========================
 
 .. toctree::
-  :maxdepth: 2
-  :numbered:
-  :hidden:
+   :maxdepth: 2
+   :numbered:
+   :hidden:
 
 .. include:: manual/EPA_Disclaimer.rst
 .. include:: manual/Introduction.rst
 .. include:: manual/TimelinessofAQSdata.rst
-.. include:: manual/RAQSAPI.rst
 .. include:: manual/Install_pyaqsapi.rst
 .. include:: manual/Load_pyaqsapi.rst
 .. include:: manual/Using_pyaqsapi.rst
+.. include:: manual/pyaqsapiusagetipsandprecautions.rst
 .. include:: manual/pyaqsapiFunctions-Long.rst
+.. include:: manual/Troubleshooting.rst
+.. include:: manual/RAQSAPI.rst
 
 
 pyaqsapi API reference documentation
@@ -34,3 +37,10 @@ pyaqsapi index
 --------------
 
 * :ref:`genindex`
+
+References
+----------
+.. bibliography::
+   :style: plain
+   :list: enumerated
+   :filter: docname in docnames

docs/_build/html/_sources/manual/Introduction.rst.txt

@@ -3,19 +3,19 @@ Introduction
 The pyaqsapi package for the python 3 programming environment allows a python 3
 programming environment to connect to and retrieve data from the United States
 Environmental Protection Agency’s (US EPA) Air Quality System (AQS) Data Mart
-API v2 (Air Quality System)1 interface directly. This package enables the data
-user to omit legacy challenges including coercing data from a JSON object to a
-usable python 3 object, retrieving multiple years of data, formatting API
-requests, retrieving results, handling credentials, requesting multiple
-pollutant data and rate limiting data requests. All the basic functionality
-of the API have been implemented that are available from the AQS API Data Mart
-server. The library connects to AQS Data Mart API via Hypertext Transfer
-Protocol (HTTP) so there is no need to install external ODBC drivers, configure
-ODBC connections or deal with the security vulnerabilities associated with
-them. Most functions have a parameter, return_header which by default is set
-to FALSE. If the user decides to set return_header to TRUE, then that function
-will return a python 3 AQS_DATAMART_APIv2 object. An AQS_DATAMART_APIv2 object
-has instance methods for retrieving the data requested, header information,
-and other metadata related to the API call. After each call to the API a five
-second stall is invoked to help prevent overloading the Data Mart API server
-and to serve as a simple rate limit.
+API v2 (Air Quality System) :cite:t:`AQSDataMartWelcome` interface directly.
+This package enables the data user to omit legacy challenges including coercing
+data from a JSON object to a usable python 3 object, retrieving multiple years
+of data, formatting API requests, retrieving results, handling credentials,
+requesting multiple pollutant data and rate limiting data requests.
+All the basic functionality of the API have been implemented that are available
+from the AQS API Data Mart server. The library connects to AQS Data Mart API
+via Hypertext Transfer Protocol (HTTP) so there is no need to install external
+ODBC drivers, configure ODBC connections or deal with the security
+vulnerabilities associated with them. Most functions have a parameter,
+return_header which by default is set to FALSE. If the user decides to
+set return_header to TRUE, then that function will return a python 3 
+AQSAPI_V2 object. An AQSAPI_V2 object has instance methods for retrieving the
+data requested, header information, and other metadata related to the API call.
+After each call to the API a five second stall is invoked to help prevent
+overloading the Data Mart API server and to serve as a simple rate limit.

docs/_build/html/_sources/manual/RAQSAPI.rst.txt

@@ -2,11 +2,10 @@
 
 About RAQSAPI
 =============
-pyaqsapi is a port of `RAQSAPI <https://github.com/USEpa/RAQSAPI>`_ to the
+pyaqsapi is a port of :cite:t:`Rpackage:RAQSAPI` to the
 python 3 programming environment. For anyone that is familiar with RAQSAPI, 
 the pyaqsapi API will feel familiar to you, most of the functions are similar 
 and the parameters sent to each functions are the same. pyaqsapi aims to have 
 feature parity with RAQSAPI and neither project will have features that the
 other project does not - other than programming language environment or
-language preference there is no benefit to using one package over the other.
-
+language preference there is no benefit to using one package over the other.

docs/_build/html/_sources/manual/TimelinessofAQSdata.rst.txt

@@ -5,6 +5,6 @@ About the timeliness of AQS Data
 
 EPA's AQS Datamart API, the service that pyaqsapi retrieves data from, does not
 host real time (collected now/today) data. If real time data is needed, please
-use the AirNow API and direct all questions toward real time data there. RAQSAPI
-does not work with AirNow and cannot retrieve real time data. For more details
-see section 7.1 of the About AQS Data page.
+use the AirNow API and direct all questions toward real time data there.
+pyaqsapi does not work with AirNow and cannot retrieve real time data. For more
+details see section 7.1 of the About AQS Data page :cite:t:`AboutAQSdata`.

docs/_build/html/_sources/manual/Troubleshooting.rst.txt

@@ -0,0 +1,9 @@
+.. index:: Troubleshooting
+
+Troubleshooting
+===============
+
+Parameters must be supplied exactly as they are specified, for example the
+stateFIPS for Alabama is "01", entering a value of "1" for the stateFIPS
+may lead to unexpected results. Do not omit leading zeros in parameters that
+expect them.

docs/_build/html/_sources/manual/Using_pyaqsapi.rst.txt

@@ -2,16 +2,17 @@
 
 Using pyaqsapi
 ==============
-For those who are already familiar with using RAQSAPI then the pyaqsapi API
-should feel familiar with a few minor differences regarding how the data is
-returned.
+For those who are already familiar with using :cite:t:`Rpackage:RAQSAPI`
+RAQSAPI then the pyaqsapi API should feel familiar with a few minor differences
+regarding how the data is returned.
 
-All data is returned using pandas Data Frames. Exported functions from pyaqsapi
-have a parameter RETURN_HEADER, by default this parameter is False. When False
-these functions simply return the requested data as a pandas Data Frame. If
-RETURN_HEADER is manually set to True an AQSAPI_V2 python 3 object is returned.
-Use the get_data() class method to retrieve the data, get_header() class
-method to retrieve header information.
+By default data is returned as a pandas Data Frames :cite:t:`pandas_DataFrame`.
+Exported functions from pyaqsapi have a parameter RETURN_HEADER, by default
+this parameter is False. When False functions simply return the requested
+data as a pandas Data Frame. If RETURN_HEADER is manually set to True a list of
+AQSAPI_V2 python 3 objects are returned. Use the get_data() class method to
+retrieve the data and the get_header() class method to retrieve header
+information.
 
 .. index:: sign_up
 

docs/_build/html/_sources/manual/pyaqsapiusagetipsandprecautions.rst.txt

@@ -0,0 +1,58 @@
+.. index:: Usage tips and precautions
+
+Usage tips and precautions
+==========================
+
+This section contains suggestions for completing certain data related tasks.
+
+* Determine if or how much data exists for a time-parameter-geography
+  combination:
+
+    * Retrieve data using the annualdata service.
+    * If no records are returned, we do not have the data.
+    * If records are returned, use the observation count to determine the
+      temporal and geographic distribution of the data.
+
+* Monthly averages:
+
+    * AQS does not routinely calculate monthly aggregate statistics.
+    * If you need these, you must calculate them yourself.
+    * These can be calculated from the sample data or the daily data without
+      loss of fidelity.
+
+* Determine a single value for a site with collocated monitors:
+
+    * Many sites will have collocated monitors - monitors collecting the same
+      parameter at the same time.
+    * The API currently provides only monitor level values. (site-level values
+      will be added in the future.)
+    * For some criteria pollutants (PM2.5, ozone, lead, and NO2), the
+      regulations define procedures for defining a single site-level value.
+    * For other pollutants, determining a single site-level value is left to
+      the investigator.
+
+* **Please adhere to the following when using the AQS Data Mart API**:
+
+    * *Limit the size of queries*. The AQS Data Mart contains billions of
+       values and you may request more than you intend. If you are unsure of
+       the amount of data, start small and work your way up. Please limit
+       queries to 1,000,000 rows of data each. You can use the
+       "observation count" field on the annualdata service to determine how
+       much data exists for a time-parameter-geography combination.
+    * *Limit the frequency of queries*. The AQS Data Mart can process a limited
+       load. Please wait for one request to complete before submitting another
+       and do not make more than 10 requests per minute.
+    * Be advised that RAQSAPI is capable of retrieving results for multiple
+      pollutants, this can result in the amount of data being returned being
+      multiplied by the number of pollutants being requested.
+    * Be advised that the AQS Data Mart API limits certain data requests to
+      one year of data at a time with the exception of the Monitor service.
+      In order to retrieve multiple years of data for these functions the
+      RAQSAPI library conveniently sends multiple API requests to the Data Mart
+      API server, one request for each year, this can result in the amount of
+      data being returned being multiplied by the number of years of data being
+      requested.
+
+**The AQS Data Mart administrators may disable accounts without notice for
+failure to adhere to these terms (Though they will contact the offending
+user via the email address provided)**

docs/_build/html/genindex.html

@@ -108,23 +108,23 @@ <h2 id="F">F</h2>
 <h2 id="I">I</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="index.html#index-3">install pyaqsapi</a>, <a href="manual/Install_pyaqsapi.html#index-0">[1]</a>
+      <li><a href="index.html#index-2">install pyaqsapi</a>, <a href="manual/Install_pyaqsapi.html#index-0">[1]</a>
 </li>
   </ul></td>
 </tr></table>
 
 <h2 id="L">L</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="index.html#index-4">load pyaqsapi</a>, <a href="manual/Load_pyaqsapi.html#index-0">[1]</a>
+      <li><a href="index.html#index-3">load pyaqsapi</a>, <a href="manual/Load_pyaqsapi.html#index-0">[1]</a>
 </li>
   </ul></td>
 </tr></table>
 
 <h2 id="R">R</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="index.html#index-2">RAQSAPI</a>, <a href="manual/RAQSAPI.html#index-0">[1]</a>
+      <li><a href="index.html#index-9">RAQSAPI</a>, <a href="manual/RAQSAPI.html#index-0">[1]</a>
 </li>
   </ul></td>
 </tr></table>
@@ -136,7 +136,7 @@ <h2 id="S">S</h2>
 </li>
   </ul></td>
   <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="index.html#index-6">sign_up</a>, <a href="manual/Using_pyaqsapi.html#index-1">[1]</a>
+      <li><a href="index.html#index-5">sign_up</a>, <a href="manual/Using_pyaqsapi.html#index-1">[1]</a>
 </li>
   </ul></td>
 </tr></table>
@@ -145,14 +145,22 @@ <h2 id="T">T</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%; vertical-align: top;"><ul>
       <li><a href="index.html#index-1">timeliness of AQS Data</a>, <a href="manual/TimelinessofAQSdata.html#index-0">[1]</a>
+</li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="index.html#index-8">Troubleshooting</a>, <a href="manual/Troubleshooting.html#index-0">[1]</a>
 </li>
   </ul></td>
 </tr></table>
 
 <h2 id="U">U</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%; vertical-align: top;"><ul>
-      <li><a href="index.html#index-5">use pyaqsapi</a>, <a href="manual/Using_pyaqsapi.html#index-0">[1]</a>
+      <li><a href="index.html#index-6">Usage tips and precautions</a>, <a href="manual/pyaqsapiusagetipsandprecautions.html#index-0">[1]</a>
+</li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="index.html#index-4">use pyaqsapi</a>, <a href="manual/Using_pyaqsapi.html#index-0">[1]</a>
 </li>
   </ul></td>
 </tr></table>