diff --git a/docs/_static/astroquery.css b/docs/_static/astroquery.css new file mode 100644 index 0000000000..09dff169b8 --- /dev/null +++ b/docs/_static/astroquery.css @@ -0,0 +1,9 @@ + +.sd-card .sd-card-img-top { + height: 52px; + width: 52px; + margin-left: auto; + margin-right: auto; + margin-top: 10px; +} + diff --git a/docs/_static/astroquery_banner.png b/docs/_static/astroquery_banner.png new file mode 100644 index 0000000000..891c0999f9 Binary files /dev/null and b/docs/_static/astroquery_banner.png differ diff --git a/docs/_static/astroquery_banner.svg b/docs/_static/astroquery_banner.svg new file mode 100644 index 0000000000..0007d4660a --- /dev/null +++ b/docs/_static/astroquery_banner.svg @@ -0,0 +1,197 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Astroquery + + diff --git a/docs/_static/astroquery_logo.ico b/docs/_static/astroquery_logo.ico new file mode 100644 index 0000000000..2dfa9da00e Binary files /dev/null and b/docs/_static/astroquery_logo.ico differ diff --git a/docs/_static/astroquery_logo.png b/docs/_static/astroquery_logo.png new file mode 100644 index 0000000000..b2c5f9c773 Binary files /dev/null and b/docs/_static/astroquery_logo.png differ diff --git a/docs/_static/astroquery_logo.svg b/docs/_static/astroquery_logo.svg new file mode 100644 index 0000000000..3347d76348 --- /dev/null +++ b/docs/_static/astroquery_logo.svg @@ -0,0 +1,163 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/_static/index_images/alphabetical-order-svgrepo-com.svg b/docs/_static/index_images/alphabetical-order-svgrepo-com.svg new file mode 100644 index 0000000000..0ce068c637 --- /dev/null +++ b/docs/_static/index_images/alphabetical-order-svgrepo-com.svg @@ -0,0 +1,22 @@ + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/_static/index_images/installation.svg b/docs/_static/index_images/installation.svg new file mode 100644 index 0000000000..335778aafa --- /dev/null +++ b/docs/_static/index_images/installation.svg @@ -0,0 +1,18 @@ + + + + + + + + + + \ No newline at end of file diff --git a/docs/_static/index_images/license-svgrepo-com.svg b/docs/_static/index_images/license-svgrepo-com.svg new file mode 100644 index 0000000000..92bb2b05b3 --- /dev/null +++ b/docs/_static/index_images/license-svgrepo-com.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/_static/index_images/list-ul-alt-svgrepo-com.svg b/docs/_static/index_images/list-ul-alt-svgrepo-com.svg new file mode 100644 index 0000000000..c36a06d15e --- /dev/null +++ b/docs/_static/index_images/list-ul-alt-svgrepo-com.svg @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/docs/_static/index_images/readme-svgrepo-com.svg b/docs/_static/index_images/readme-svgrepo-com.svg new file mode 100644 index 0000000000..f65313d013 --- /dev/null +++ b/docs/_static/index_images/readme-svgrepo-com.svg @@ -0,0 +1,2 @@ + + \ No newline at end of file diff --git a/docs/_static/index_images/user-plus-svgrepo-com.svg b/docs/_static/index_images/user-plus-svgrepo-com.svg new file mode 100644 index 0000000000..b986bdb029 --- /dev/null +++ b/docs/_static/index_images/user-plus-svgrepo-com.svg @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index dcc9dfabc4..be4ce70f34 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -31,7 +31,7 @@ # Load all of the global Astropy configuration try: - from sphinx_astropy.conf.v1 import * # noqa + from sphinx_astropy.conf.v2 import * # noqa except ImportError: print('ERROR: the documentation requires the sphinx-astropy package to ' 'be installed') @@ -72,6 +72,10 @@ 'pyvo': ('https://pyvo.readthedocs.io/en/stable', None), }) +extensions += [ + "sphinx_design", +] + # -- Project information ------------------------------------------------------ # This does not *have* to match the package name, but typically does @@ -102,11 +106,26 @@ # variables set in the global configuration. The variables set in the # global configuration are listed below, commented out. -html_theme_options = { - 'logotext1': 'astro', # white, semi-bold - 'logotext2': 'query', # orange, light - 'logotext3': ':docs', # white, light -} + + +html_theme_options.update( + { + "logo": { + "image_light": "_static/astroquery_banner.png", + "image_dark": "_static/astroquery_banner.png", + }, + # https://github.com/pydata/pydata-sphinx-theme/issues/1492 + "navigation_with_keys": False, + "navbar_align": "right" + } +) + + + +html_favicon = "_static/astroquery_logo.ico" +html_static_path = ["_static"] +html_css_files = ["astroquery.css"] +html_copy_source = False # Add any paths that contain custom themes here, relative to this directory. # To use a different custom theme, add the directory containing the theme. @@ -175,9 +194,9 @@ def __getattr__(cls, name): return Mock() -MOCK_MODULES = ['atpy', 'beautifulsoup4', 'vo', 'lxml', 'keyring', 'bs4'] -for mod_name in MOCK_MODULES: - sys.modules[mod_name] = Mock() +#MOCK_MODULES = ['atpy', 'beautifulsoup4', 'vo', 'lxml', 'keyring', 'bs4'] +#for mod_name in MOCK_MODULES: +# sys.modules[mod_name] = Mock() # -- Options for the edit_on_github extension ---------------------------------------- # diff --git a/docs/developer.rst b/docs/developer.rst new file mode 100644 index 0000000000..fabef43327 --- /dev/null +++ b/docs/developer.rst @@ -0,0 +1,38 @@ +Developer documentation +----------------------- + +The modules and their maintainers are listed on the +`Maintainers `_ +wiki page. + + +The :doc:`api` is intended to be kept as consistent as possible, such +that any web service can be used with a minimal learning curve imposed on the +user. + +.. toctree:: + :maxdepth: 1 + + api.rst + template.rst + testing.rst + +The following Astroquery modules are mostly meant for internal use of +services in Astroquery, you can use them for your scripts, but we don't guarantee API stability. + +.. toctree:: + :maxdepth: 1 + + utils.rst + query.rst + utils/tap.rst + +To debug astroquery, logging level can be configured with the following: + +.. doctest-skip:: + + >>> from astroquery import log + >>> log.setLevel(level) + +If ``level`` is set to ``"DEBUG"``, then HTTP requests are logged. +If ``level`` is set to ``"TRACE"``, then HTTP requests and responses are logged. diff --git a/docs/genindex.rst b/docs/genindex.rst new file mode 100644 index 0000000000..c07da40d10 --- /dev/null +++ b/docs/genindex.rst @@ -0,0 +1,4 @@ +.. This file is a placeholder and will be replaced + +Index +##### diff --git a/docs/index.rst b/docs/index.rst index 1f6f5e7850..ae360f69c0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,494 +1,154 @@ -Astroquery -========== - -This is the documentation for the Astroquery coordinated package of `astropy -`__. - -Code and issue tracker are on `GitHub `_. - -If you use astroquery, please `cite `__ the -paper `Ginsburg, Sipőcz, Brasseur et al 2019 `_. - -Introduction ------------- - -Astroquery is a set of tools for querying astronomical web forms and databases. - -There are two other packages with complimentary functionality as Astroquery: -`pyvo `_ is an Astropy affiliated package, and -`Simple-Cone-Search-Creator `_ to -generate a cone search service complying with the -`IVOA standard `_. -They are more oriented to general `virtual observatory `_ -discovery and queries, whereas Astroquery has web service specific interfaces. - - -Installation ------------- - -Uniquely in the Astropy ecosystem, Astroquery is operating with a **continuous deployment model**. -It means that a release is instantaneously available after a pull request has been merged. These -releases are automatically uploaded to `PyPI `__, -and therefore the latest version of astroquery can be pip installed. -The version number of these automated releases contain the ``'dev'`` tag, thus pip needs to be told -to look for these releases during an upgrade, using the ``--pre`` install option. If astroquery is -already installed, please make sure you use the ``--upgrade`` (or ``-U``) install option as well. - -.. code-block:: bash - - $ python -m pip install -U --pre astroquery - -To install all the mandatory and optional dependencies add the ``[all]`` -identifyer to the pip command above (or use ``[docs]`` or ``[test]`` for the -dependencies required to build the documentation or run the tests): - -.. code-block:: bash - - $ python -m pip install -U --pre astroquery[all] - -In addition to the automated releases, we also keep doing regular, tagged version for maintenance -and packaging purposes. These can be ``pip`` installed without the ``--pre`` option and -are also available from the ``conda-forge`` conda channel. - -.. code-block:: bash - - $ conda install -c conda-forge astroquery - -To review recent changes and fixes, please have a look at the changelog: - -.. toctree:: - :maxdepth: 1 - - changelog - - -Building from source -^^^^^^^^^^^^^^^^^^^^ - -The development version can be obtained and installed from github: - -.. code-block:: bash - - $ # If you have a github account: - $ git clone git@github.com:astropy/astroquery.git - $ # If you do not: - $ git clone https://github.com/astropy/astroquery.git - $ cd astroquery - $ python -m pip install . - - -To install all the optional dependencies (listed below), add the option -``[all]``. To install dependencies required for running the tests locally -use ``[test]``, and for documentation build ``[docs]``. -If you would like to modify the source, you can install -``astroquery`` in editable mode, which means you don't need to rerun the -install command after you made the changes. - -To install all dependencies, including those required for local testing and -building the documentation, in editable mode: - -.. code-block:: bash - - $ python -m pip install -e .[all,test,docs] - - -Requirements ------------- - -Astroquery works with Python 3.9 or later. - -The following packages are required for astroquery installation & use: - -* `numpy `_ >= 1.20 -* `astropy `__ (>=5.0) -* `pyVO`_ (>=1.5) -* `requests `_ -* `keyring `_ -* `Beautiful Soup `_ -* `html5lib `_ - -and for running the tests: - -* `curl `__ -* `pytest-astropy `__ -* `pytest-rerunfailures `__ - -The following packages are optional dependencies and are required for the -full functionality of the `~astroquery.mocserver`, `~astroquery.alma`, and `~astroquery.xmatch` modules: - -* `astropy-healpix `_ -* `regions `_ -* `mocpy `_ >= 0.9 - -For the `~astroquery.vamdc` module: - -* `vamdclib `_ install version from - personal fork: ``python -m pip install git+https://github.com/keflavich/vamdclib-1.git`` - -The following packages are optional dependencies and are required for the -full functionality of the `~astroquery.mast` module: - -* `boto3 `_ - -Using astroquery ----------------- - -All astroquery modules are supposed to follow the same API. In its simplest form, the API involves -queries based on coordinates or object names. Some simple examples, using SIMBAD: - -.. doctest-remote-data:: - - >>> from astroquery.simbad import Simbad - >>> result_table = Simbad.query_object("m1") - >>> result_table.pprint() - - main_id ra dec coo_err_maj coo_err_min coo_err_angle coo_wavelength coo_bibcode matched_id - deg deg mas mas deg - ------- ------- ------- ----------- ----------- ------------- -------------- ------------------- ---------- - M 1 83.6324 22.0174 5000.0 5000.0 90 X 2022A&A...661A..38P M 1 - -All query tools allow coordinate-based queries: - -.. doctest-remote-data:: - - >>> from astropy import coordinates - >>> import astropy.units as u - >>> c = coordinates.SkyCoord("05h35m17.3s -05d23m28s", frame='icrs') - >>> r = 5 * u.arcminute - >>> result_table = Simbad.query_region(c, radius=r) - >>> result_table.pprint(show_unit=True, max_width=80, max_lines=5) - main_id ra ... coo_bibcode - deg ... - ---------------------------- -------------- ... ------------------- - ALMA J053514.4142-052220.792 83.8100591667 ... 2023MNRAS.522...56V - ... ... ... ... - 2MASS J05351163-0522515 83.79846499816 ... 2020yCat.1350....0G - [H97b] 9009 83.79990004111 ... 2020yCat.1350....0G - Length = 3324 rows - -For additional guidance and examples, read the documentation for the individual services below. - -.. _default_config: - -Default configuration file --------------------------- - -To customize this, copy the default configuration to ``$HOME/.astropy/config/astroquery.cfg``, -uncomment the relevant configuration item(s), and insert your desired value(s). - .. toctree:: - :maxdepth: 1 - - configuration - - -.. _astroquery_cache: - -Caching -------- - -By default Astroquery employs query caching with a timeout of 1 week. -The user can clear their cache at any time, as well as suspend cache usage, -and change the cache location. Caching persists between Astroquery sessions. -If you know the service you are using has released new data recently, or if you believe you are -not receiving the newest data, try clearing the cache. - -Service specific settings -^^^^^^^^^^^^^^^^^^^^^^^^^ - -The Astroquery cache location is specific to individual services, -so each service's cache should be managed individually. -The cache location can be viewed with the following command -(using :ref:`VizieR ` as an example): + :maxdepth: 1 + :hidden: -.. code-block:: python + genindex + py-modindex - >>> from astroquery.vizier import Vizier - >>> print(Vizier.cache_location) # doctest: +IGNORE_OUTPUT - /Users/username/.astropy/cache/astroquery/Vizier + +.. rst-class:: image-no-text-wrap +.. figure:: _static/astroquery_logo.svg + :align: left + :width: 250px -Each service's cache is cleared with the ``clear_cache`` function within that service. +| +| -.. code-block:: python +################################################################### +Astroquery: Tools for querying astronomical web forms and databases +################################################################### - >>> import os - >>> from astroquery.vizier import Vizier - ... - >>> os.listdir(Vizier.cache_location) # doctest: +IGNORE_OUTPUT - ['8abafe54f49661237bdbc2707179df53b6ee0d74ca6b7679c0e4fac0.pickle', - '0e4766a7673ddfa4adaee2cfa27a924ed906badbfae8cc4a4a04256c.pickle'] - >>> Vizier.clear_cache() - >>> os.listdir(Vizier.cache_location) # doctest: +IGNORE_OUTPUT - [] +.. |clearfloat| raw:: html -Astroquery-wide settings -^^^^^^^^^^^^^^^^^^^^^^^^ +
-Whether caching is active and when cached files expire are controlled centrally through the -astroquery ``cache_conf`` module, and shared among all services. -Astroquery uses the Astropy configuration infrastructure, information about -temporarily or permanently changing configuration values can be found -`here `_. +|clearfloat| -.. code-block:: python - - >>> from astroquery import cache_conf - ... - >>> # Is the cache active? - >>> print(cache_conf.cache_active) - True - >>> # Cache timout in seconds - >>> print(cache_conf.cache_timeout) - 604800 - - -Available Services -================== - -The following modules have been completed using a common API: - -.. toctree:: - :maxdepth: 1 - - alma/alma.rst - atomic/atomic.rst - besancon/besancon.rst - cadc/cadc.rst - casda/casda.rst - linelists/cdms/cdms.rst - esa/euclid/euclid.rst - esa/hsa/hsa.rst - esa/hubble/hubble.rst - esa/integral/integral.rst - esa/iso/iso.rst - esa/jwst/jwst.rst - esa/xmm_newton/xmm_newton.rst - esasky/esasky.rst - eso/eso.rst - image_cutouts/first/first.rst - gaia/gaia.rst - gama/gama.rst - gemini/gemini.rst - heasarc/heasarc.rst - hips2fits/hips2fits.rst - hitran/hitran.rst - ipac/irsa/most.rst - ipac/irsa/irsa_dust/irsa_dust.rst - ipac/irsa/ibe/ibe.rst - ipac/irsa/irsa.rst - jplspec/jplspec.rst - magpis/magpis.rst - mast/mast.rst - mocserver/mocserver.rst - mpc/mpc.rst - nasa_ads/nasa_ads.rst - ipac/ned/ned.rst - nist/nist.rst - nvas/nvas.rst - simbad/simbad.rst - skyview/skyview.rst - splatalogue/splatalogue.rst - svo_fps/svo_fps.rst - ukidss/ukidss.rst - vamdc/vamdc.rst - vizier/vizier.rst - vo_conesearch/vo_conesearch.rst - vsa/vsa.rst - xmatch/xmatch.rst - - -These others are functional, but do not follow a common & consistent API: - -.. toctree:: - :maxdepth: 1 - - alfalfa/alfalfa.rst - cosmosim/cosmosim.rst - exoplanet_orbit_database/exoplanet_orbit_database.rst - fermi/fermi.rst - jplhorizons/jplhorizons.rst - jplsbdb/jplsbdb.rst - lamda/lamda.rst - ipac/nexsci/nasa_exoplanet_archive.rst - oac/oac.rst - ogle/ogle.rst - open_exoplanet_catalogue/open_exoplanet_catalogue.rst - sdss/sdss.rst - -There are also subpackages that serve as the basis of others. - -.. toctree:: - :maxdepth: 1 - - wfau/wfau.rst +This is the documentation for the Astroquery coordinated package of `astropy +`__. -Catalog, Archive, and Other -=========================== +Code and issue tracker are on `GitHub `_. + +.. Important:: If you use astroquery for work presented in a publication or talk, please + `cite `__ + the paper + `Ginsburg, Sipőcz, Brasseur et al 2019 `_. -A second index of the services by the type of data they serve. Some services -perform many tasks and are listed more than once. +.. grid:: 2 + + .. grid-item-card:: + :img-top: _static/index_images/installation.svg + :text-align: center -Catalogs --------- + Installation + ^^^^^^^^^^^^ -The first serve catalogs, which generally return one row of information for -each source (though they may return many catalogs that *each* have one row -for each source) + New to Astroquery? Click here for our installation guide. -.. toctree:: - :maxdepth: 1 - - alfalfa/alfalfa.rst - exoplanet_orbit_database/exoplanet_orbit_database.rst - gama/gama.rst - ipac/irsa/irsa_dust/irsa_dust.rst - ipac/irsa/ibe/ibe.rst - ipac/irsa/irsa.rst - mast/mast.rst - ipac/nexsci/nasa_exoplanet_archive.rst - ipac/ned/ned.rst - ogle/ogle.rst - open_exoplanet_catalogue/open_exoplanet_catalogue.rst - sdss/sdss.rst - simbad/simbad.rst - ukidss/ukidss.rst - vizier/vizier.rst - vo_conesearch/vo_conesearch.rst - vsa/vsa.rst - xmatch/xmatch.rst - -Archives --------- - -Archive services provide data, usually in FITS images or spectra. They will -generally return a table listing the available data first. + +++ + + .. button-ref:: install + :expand: + :color: primary + :click-parent: -.. toctree:: - :maxdepth: 1 - - alfalfa/alfalfa.rst - alma/alma.rst - cadc/cadc.rst - casda/casda.rst - esa/hubble/hubble.rst - esa/jwst/jwst.rst - esa/xmm_newton/xmm_newton.rst - eso/eso.rst - fermi/fermi.rst - gaia/gaia.rst - gemini/gemini.rst - heasarc/heasarc.rst - ipac/irsa/ibe/ibe.rst - ipac/irsa/irsa.rst - magpis/magpis.rst - mast/mast.rst - ipac/ned/ned.rst - nvas/nvas.rst - sdss/sdss.rst - skyview/skyview.rst - ukidss/ukidss.rst - vsa/vsa.rst - -Simulations ------------ - -These services query databases of simulated or synthetic data: + Installation Guide + + .. grid-item-card:: + :img-top: _static/index_images/readme-svgrepo-com.svg + :text-align: center -.. toctree:: - :maxdepth: 1 + Documentation + ^^^^^^^^^^^^^ - besancon/besancon.rst - cosmosim/cosmosim.rst + Need general information about Astroquery? Click here for information about how the package works as a whole, and common configurations. -Line List Services ------------------- + +++ + + .. button-ref:: overview + :expand: + :color: primary + :click-parent: -There are several web services that provide atomic or molecular line lists, as -well as cross section and collision rates. Those services are: + General Documentation + -.. toctree:: - :maxdepth: 1 + .. grid-item-card:: + :img-top: _static/index_images/list-ul-alt-svgrepo-com.svg + :text-align: center - atomic/atomic.rst - linelists/cdms/cdms.rst - hitran/hitran.rst - jplspec/jplspec.rst - lamda/lamda.rst - nist/nist.rst - splatalogue/splatalogue.rst - vamdc/vamdc.rst + Services By Type + ^^^^^^^^^^^^^^^^ -Other ------ + Want to find specific types of services? Click here for services grouped by type (Catalogs, Archives, Simulations, Line List Services, Other). -There are other astronomically significant services, that don't fit the -above categories. Those services are here: + +++ + + .. button-ref:: services_type + :expand: + :color: primary + :click-parent: -.. toctree:: - :maxdepth: 1 + Services by Type - astrometry_net/astrometry_net.rst - imcce/imcce.rst - jplhorizons/jplhorizons.rst - jplsbdb/jplsbdb.rst - nasa_ads/nasa_ads.rst - solarsystem/neodys/neodys.rst - utils/tap.rst + .. grid-item-card:: + :img-top: _static/index_images/alphabetical-order-svgrepo-com.svg + :text-align: center -Topical Collections -=================== + Services Alphebetically + ^^^^^^^^^^^^^^^^^^^^^^^ -Some services focusing on similar topics are also collected in -topical submodules: + Know the name of the service you need? Click here for a full alphabetical list. -.. toctree:: - :maxdepth: 1 + +++ + + .. button-ref:: services_alph + :expand: + :color: primary + :click-parent: - image_cutouts/image_cutouts.rst - solarsystem/solarsystem.rst + Services listed alphabetically + .. grid-item-card:: + :img-top: _static/index_images/user-plus-svgrepo-com.svg + :text-align: center -Developer documentation ------------------------ + Developer Documentation + ^^^^^^^^^^^^^^^^^^^^^^^ -The modules and their maintainers are listed on the -`Maintainers `_ -wiki page. + Interested in contributing to Astroquery? Click here for the developer documentation. This includes Astroquery API specification, a template module, and information on writing tests and documentation. + +++ + + .. button-ref:: developer + :expand: + :color: primary + :click-parent: -The :doc:`api` is intended to be kept as consistent as possible, such -that any web service can be used with a minimal learning curve imposed on the -user. + Developer documentation -.. toctree:: - :maxdepth: 1 + .. grid-item-card:: + :img-top: _static/index_images/license-svgrepo-com.svg + :text-align: center - api.rst - template.rst - testing.rst + License + ^^^^^^^ -The following Astroquery modules are mostly meant for internal use of -services in Astroquery, you can use them for your scripts, but we don't guarantee API stability. - -.. toctree:: - :maxdepth: 1 + Astroquery is licensed under a 3-clause BSD style license. - utils.rst - query.rst - utils/tap.rst + +++ + + .. button-ref:: license + :expand: + :color: primary + :click-parent: -To debug astroquery, logging level can be configured with the following: + License + + -.. doctest-skip:: - >>> from astroquery import log - >>> log.setLevel(level) -If ``level`` is set to ``"DEBUG"``, then HTTP requests are logged. -If ``level`` is set to ``"TRACE"``, then HTTP requests and responses are logged. -License -------- -Astroquery is licensed under a 3-clause BSD style license - see :doc:`license`. diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 0000000000..9b39dd68a3 --- /dev/null +++ b/docs/install.rst @@ -0,0 +1,107 @@ + +Installation +============ + +Uniquely in the Astropy ecosystem, Astroquery is operating with a **continuous deployment model**. +It means that a release is instantaneously available after a pull request has been merged. These +releases are automatically uploaded to `PyPI `__, +and therefore the latest version of astroquery can be pip installed. +The version number of these automated releases contain the ``'dev'`` tag, thus pip needs to be told +to look for these releases during an upgrade, using the ``--pre`` install option. If astroquery is +already installed, please make sure you use the ``--upgrade`` (or ``-U``) install option as well. + +.. code-block:: bash + + $ python -m pip install -U --pre astroquery + +To install all the mandatory and optional dependencies add the ``[all]`` +identifyer to the pip command above (or use ``[docs]`` or ``[test]`` for the +dependencies required to build the documentation or run the tests): + +.. code-block:: bash + + $ python -m pip install -U --pre astroquery[all] + +In addition to the automated releases, we also keep doing regular, tagged version for maintenance +and packaging purposes. These can be ``pip`` installed without the ``--pre`` option and +are also available from the ``conda-forge`` conda channel. + +.. code-block:: bash + + $ conda install -c conda-forge astroquery + +To review recent changes and fixes, please have a look at the changelog: + +.. toctree:: + :maxdepth: 1 + + changelog + + +Building from source +-------------------- + +The development version can be obtained and installed from github: + +.. code-block:: bash + + $ # If you have a github account: + $ git clone git@github.com:astropy/astroquery.git + $ # If you do not: + $ git clone https://github.com/astropy/astroquery.git + $ cd astroquery + $ python -m pip install . + + +To install all the optional dependencies (listed below), add the option +``[all]``. To install dependencies required for running the tests locally +use ``[test]``, and for documentation build ``[docs]``. +If you would like to modify the source, you can install +``astroquery`` in editable mode, which means you don't need to rerun the +install command after you made the changes. + +To install all dependencies, including those required for local testing and +building the documentation, in editable mode: + +.. code-block:: bash + + $ python -m pip install -e .[all,test,docs] + + +Requirements +------------ + +Astroquery works with Python 3.9 or later. + +The following packages are required for astroquery installation & use: + +* `numpy `_ >= 1.20 +* `astropy `__ (>=5.0) +* `pyVO`_ (>=1.5) +* `requests `_ +* `keyring `_ +* `Beautiful Soup `_ +* `html5lib `_ + +and for running the tests: + +* `curl `__ +* `pytest-astropy `__ +* `pytest-rerunfailures `__ + +The following packages are optional dependencies and are required for the +full functionality of the `~astroquery.mocserver`, `~astroquery.alma`, and `~astroquery.xmatch` modules: + +* `astropy-healpix `_ +* `regions `_ +* `mocpy `_ >= 0.9 + +For the `~astroquery.vamdc` module: + +* `vamdclib `_ install version from + personal fork: ``python -m pip install git+https://github.com/keflavich/vamdclib-1.git`` + +The following packages are optional dependencies and are required for the +full functionality of the `~astroquery.mast` module: + +* `boto3 `_ diff --git a/docs/overview.rst b/docs/overview.rst new file mode 100644 index 0000000000..66e10a2fd8 --- /dev/null +++ b/docs/overview.rst @@ -0,0 +1,127 @@ +Astroquery +========== + + +Introduction +------------ + +Astroquery is a set of tools for querying astronomical web forms and databases. + +There are two other packages with complimentary functionality as Astroquery: +`pyvo `_ is an Astropy affiliated package, and +`Simple-Cone-Search-Creator `_ to +generate a cone search service complying with the +`IVOA standard `_. +They are more oriented to general `virtual observatory `_ +discovery and queries, whereas Astroquery has web service specific interfaces. + +Using astroquery +---------------- + +All astroquery modules are supposed to follow the same API. In its simplest form, the API involves +queries based on coordinates or object names. Some simple examples, using SIMBAD: + +.. doctest-remote-data:: + + >>> from astroquery.simbad import Simbad + >>> result_table = Simbad.query_object("m1") + >>> result_table.pprint() + + main_id ra dec coo_err_maj coo_err_min coo_err_angle coo_wavelength coo_bibcode matched_id + deg deg mas mas deg + ------- ------- ------- ----------- ----------- ------------- -------------- ------------------- ---------- + M 1 83.6324 22.0174 5000.0 5000.0 90 X 2022A&A...661A..38P M 1 + +All query tools allow coordinate-based queries: + +.. doctest-remote-data:: + + >>> from astropy import coordinates + >>> import astropy.units as u + >>> c = coordinates.SkyCoord("05h35m17.3s -05d23m28s", frame='icrs') + >>> r = 5 * u.arcminute + >>> result_table = Simbad.query_region(c, radius=r) + >>> result_table.pprint(show_unit=True, max_width=80, max_lines=5) + main_id ra ... coo_bibcode + deg ... + ---------------------------- -------------- ... ------------------- + ALMA J053514.4142-052220.792 83.8100591667 ... 2023MNRAS.522...56V + ... ... ... ... + 2MASS J05351163-0522515 83.79846499816 ... 2020yCat.1350....0G + [H97b] 9009 83.79990004111 ... 2020yCat.1350....0G + Length = 3324 rows + +For additional guidance and examples, read the documentation for the individual services, indexed :doc:`alphabetically`, or by :doc:`type`. + +.. _default_config: + +Default configuration file +-------------------------- + +To customize this, copy the default configuration to ``$HOME/.astropy/config/astroquery.cfg``, +uncomment the relevant configuration item(s), and insert your desired value(s). + +.. toctree:: + :maxdepth: 1 + + configuration + + +.. _astroquery_cache: + +Caching +------- + +By default Astroquery employs query caching with a timeout of 1 week. +The user can clear their cache at any time, as well as suspend cache usage, +and change the cache location. Caching persists between Astroquery sessions. +If you know the service you are using has released new data recently, or if you believe you are +not receiving the newest data, try clearing the cache. + +Service specific settings +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Astroquery cache location is specific to individual services, +so each service's cache should be managed individually. +The cache location can be viewed with the following command +(using :ref:`VizieR ` as an example): + +.. code-block:: python + + >>> from astroquery.vizier import Vizier + >>> print(Vizier.cache_location) # doctest: +IGNORE_OUTPUT + /Users/username/.astropy/cache/astroquery/Vizier + +Each service's cache is cleared with the ``clear_cache`` function within that service. + +.. code-block:: python + + >>> import os + >>> from astroquery.vizier import Vizier + ... + >>> os.listdir(Vizier.cache_location) # doctest: +IGNORE_OUTPUT + ['8abafe54f49661237bdbc2707179df53b6ee0d74ca6b7679c0e4fac0.pickle', + '0e4766a7673ddfa4adaee2cfa27a924ed906badbfae8cc4a4a04256c.pickle'] + >>> Vizier.clear_cache() + >>> os.listdir(Vizier.cache_location) # doctest: +IGNORE_OUTPUT + [] + +Astroquery-wide settings +^^^^^^^^^^^^^^^^^^^^^^^^ + +Whether caching is active and when cached files expire are controlled centrally through the +astroquery ``cache_conf`` module, and shared among all services. +Astroquery uses the Astropy configuration infrastructure, information about +temporarily or permanently changing configuration values can be found +`here `_. + +.. code-block:: python + + >>> from astroquery import cache_conf + ... + >>> # Is the cache active? + >>> print(cache_conf.cache_active) + True + >>> # Cache timout in seconds + >>> print(cache_conf.cache_timeout) + 604800 diff --git a/docs/py-modindex.rst b/docs/py-modindex.rst new file mode 100644 index 0000000000..e46ba28913 --- /dev/null +++ b/docs/py-modindex.rst @@ -0,0 +1,4 @@ +.. This file is a placeholder and will be replaced + +Modules +####### diff --git a/docs/services_alph.rst b/docs/services_alph.rst new file mode 100644 index 0000000000..7fe73c606f --- /dev/null +++ b/docs/services_alph.rst @@ -0,0 +1,90 @@ +Services Alphabetically +======================= + +Common API Services +------------------- + +The following modules have been completed using a common API: + +.. toctree:: + :maxdepth: 1 + + alma/alma.rst + atomic/atomic.rst + besancon/besancon.rst + cadc/cadc.rst + casda/casda.rst + linelists/cdms/cdms.rst + esa/euclid/euclid.rst + esa/hsa/hsa.rst + esa/hubble/hubble.rst + esa/integral/integral.rst + esa/iso/iso.rst + esa/jwst/jwst.rst + esa/xmm_newton/xmm_newton.rst + esasky/esasky.rst + eso/eso.rst + image_cutouts/first/first.rst + gaia/gaia.rst + gama/gama.rst + gemini/gemini.rst + heasarc/heasarc.rst + hips2fits/hips2fits.rst + hitran/hitran.rst + ipac/irsa/most.rst + ipac/irsa/irsa_dust/irsa_dust.rst + ipac/irsa/ibe/ibe.rst + ipac/irsa/irsa.rst + jplspec/jplspec.rst + magpis/magpis.rst + mast/mast.rst + mocserver/mocserver.rst + mpc/mpc.rst + nasa_ads/nasa_ads.rst + ipac/ned/ned.rst + nist/nist.rst + nvas/nvas.rst + simbad/simbad.rst + skyview/skyview.rst + splatalogue/splatalogue.rst + svo_fps/svo_fps.rst + ukidss/ukidss.rst + vamdc/vamdc.rst + vizier/vizier.rst + vo_conesearch/vo_conesearch.rst + vsa/vsa.rst + xmatch/xmatch.rst + + +Non-conforming Services +----------------------- + +These services are functional, but do not follow a common & consistent API: + +.. toctree:: + :maxdepth: 1 + + alfalfa/alfalfa.rst + cosmosim/cosmosim.rst + exoplanet_orbit_database/exoplanet_orbit_database.rst + fermi/fermi.rst + jplhorizons/jplhorizons.rst + jplsbdb/jplsbdb.rst + lamda/lamda.rst + ipac/nexsci/nasa_exoplanet_archive.rst + oac/oac.rst + ogle/ogle.rst + open_exoplanet_catalogue/open_exoplanet_catalogue.rst + sdss/sdss.rst + + +Basis packages +-------------- +There are also subpackages that serve as the basis of others. + +.. toctree:: + :maxdepth: 1 + + wfau/wfau.rst + + diff --git a/docs/services_type.rst b/docs/services_type.rst new file mode 100644 index 0000000000..98d10471e2 --- /dev/null +++ b/docs/services_type.rst @@ -0,0 +1,124 @@ +Astroquery Services by Type +=========================== + +An index of the services by the type of data they serve. Some services +perform many tasks and are listed more than once. + +Catalogs +-------- + +The first serve catalogs, which generally return one row of information for +each source (though they may return many catalogs that *each* have one row +for each source) + +.. toctree:: + :maxdepth: 1 + + alfalfa/alfalfa.rst + exoplanet_orbit_database/exoplanet_orbit_database.rst + gama/gama.rst + ipac/irsa/irsa_dust/irsa_dust.rst + ipac/irsa/ibe/ibe.rst + ipac/irsa/irsa.rst + mast/mast.rst + ipac/nexsci/nasa_exoplanet_archive.rst + ipac/ned/ned.rst + ogle/ogle.rst + open_exoplanet_catalogue/open_exoplanet_catalogue.rst + sdss/sdss.rst + simbad/simbad.rst + ukidss/ukidss.rst + vizier/vizier.rst + vo_conesearch/vo_conesearch.rst + vsa/vsa.rst + xmatch/xmatch.rst + +Archives +-------- + +Archive services provide data, usually in FITS images or spectra. They will +generally return a table listing the available data first. + +.. toctree:: + :maxdepth: 1 + + alfalfa/alfalfa.rst + alma/alma.rst + cadc/cadc.rst + casda/casda.rst + esa/hubble/hubble.rst + esa/jwst/jwst.rst + esa/xmm_newton/xmm_newton.rst + eso/eso.rst + fermi/fermi.rst + gaia/gaia.rst + gemini/gemini.rst + heasarc/heasarc.rst + ipac/irsa/ibe/ibe.rst + ipac/irsa/irsa.rst + magpis/magpis.rst + mast/mast.rst + ipac/ned/ned.rst + nvas/nvas.rst + sdss/sdss.rst + skyview/skyview.rst + ukidss/ukidss.rst + vsa/vsa.rst + +Simulations +----------- + +These services query databases of simulated or synthetic data. + +.. toctree:: + :maxdepth: 1 + + besancon/besancon.rst + cosmosim/cosmosim.rst + +Line List Services +------------------ + +Services that provide atomic or molecular line lists, as +well as cross section and collision rates. + +.. toctree:: + :maxdepth: 1 + + atomic/atomic.rst + linelists/cdms/cdms.rst + hitran/hitran.rst + jplspec/jplspec.rst + lamda/lamda.rst + nist/nist.rst + splatalogue/splatalogue.rst + vamdc/vamdc.rst + +Other +----- + +Other astronomically significant services, that don't fit the +above categories. + +.. toctree:: + :maxdepth: 1 + + astrometry_net/astrometry_net.rst + imcce/imcce.rst + jplhorizons/jplhorizons.rst + jplsbdb/jplsbdb.rst + nasa_ads/nasa_ads.rst + solarsystem/neodys/neodys.rst + utils/tap.rst + +Topical Collections +------------------- + +Some services focusing on similar topics are also collected in +topical submodules. + +.. toctree:: + :maxdepth: 1 + + image_cutouts/image_cutouts.rst + solarsystem/solarsystem.rst