advs docs plus

docs/noirlab/noirlab.rst

@@ -6,16 +6,31 @@
 NOIRLab Queries (`astroquery.noirlab`)
 **************************************
 
+The methods in this module are wrappers around a set of web-services
+which can be accessed at
+`Rest API documentation <https://astroarchive.noao.edu/api/docs/>`_
+(which is the most
+up-to-date info on the web-services).
+This data archive is hosted at
+`NOIR-CSDC <https://nationalastro.org/programs/csdc/>`_.
 
-Getting started
-===============
+
+Getting started (SIA)
+=====================
 
 This module supports fetching the table of observation summaries from
-the `NOIRLab data archive <https://astroarchive.noao.edu/>`_. The `Rest API
-documentation <https://astroarchive.noao.edu/api/docs/>`_ is the most
-up-to-date info on the web-services used by this module.
-The archive is hosted at
-`NOIR-CSDC <https://nationalastro.org/programs/csdc/>`_.
+the `NOIRLab data archive <https://astroarchive.noao.edu/>`_ given
+your *Region Of Interest* query values.
+
+In general, you can query the
+`NOIRLab data archive <https://astroarchive.noao.edu/>`_
+against full FITS files or against HDUs of those FITS files.  Most
+users will likely prefer results against full FITS files (the
+default). The search will likely be faster when searching files
+compared to searching HDUs. If you are trying to retrieve HDU specific
+image data from large files that contain many HDUs (such as DECam),
+you can reduce your download time considerably by getting only
+matching HDUs.
 
 The results are returned in a `~astropy.table.Table`. The service
 can be queried using the :meth:`~astroquery.noirlab.NoirlabClass.query_region`. The
@@ -45,7 +60,11 @@ to query.  Specify the coordinates using the appropriate coordinate system from
     /net/archive/mtn/20151120/kp4m/2015B-2001/k4m_151121_031258_ori.fits.fz 2015-11-21 ... 2020-02-09T01:24:37.873559+00:00
     /net/archive/mtn/20151120/kp4m/2015B-2001/k4m_151121_041031_ori.fits.fz 2015-11-21 ... 2020-02-09T01:24:38.951230+00:00
 
+This is an example of searching by HDU.
+**NOTE: Only some instruments have pipeline processing that populates the RA, DEC fields used for this search.** 
 
+.. code-block:: python
+
     >>> noirlab_hdu = Noirlab(which='hdu')
     >>> results_hdu = noirlab_hdu.query_region(coord, radius='0.1')
     >>> print(results_hdu)
@@ -62,6 +81,41 @@ to query.  Specify the coordinates using the appropriate coordinate system from
                 /net/archive/pipe/20151120/kp4m/k4m_151121_031124_ooi_zd_v1.fits.fz 2015-11-20 2015-11-21 ... 10.58549      kp4m
 
 
+Advanced Search
+===============
+
+This set of methods supports **arbitrary searches of any fields**
+stored in the FITS headers of the Archive.  Common fields ("core"
+fields) are optimized for search speed. Less common fields ("aux"
+fields) will be slower to search. You can search by File or HDU. The
+primary method for doing the search in ``query_metadata``. That query
+requires a ``JSON`` structure to define the query.  Many of the other
+methods with this module are here to provide you with the information
+you need to construct the ``JSON`` structure.
+
+There are three methods who's sole purpose if providing you with
+information to help you with the content of your ``JSON`` structure.
+They are:
+
+#. aux_fields()
+#. core_fields()
+#. categoricals()
+
+See the Reference/API below for details. The categoricals() method
+returns a list of all the "category strings" such as names of
+Instruments and Telescopes.  The aux/core_fields methods
+tell you what fields are available to search. The core fields are
+available for all instruments are the search for them is fast. The aux
+fields require you to specify instrument and proctype.  The set of
+fields available is highly dependent on those two fields. The
+Instrument determines aux fields in raw files. Proctype determines
+what kind of pipeline processing was done.  Pipeline processing often
+adds important (aux) fields.
+
+
+
+
+
 
 Reference/API
 =============