Docs

Author: snbianco

astroquery/mast/missions.py

@@ -998,8 +998,8 @@ def read_product(self, uri, *, mission=None, **kwargs):
             The mission to which the file belongs. If not provided, the current value of the ``mission`` attribute
             will be used.
         **kwargs
-            Additional keyword arguments to be passed to the file reading function (e.g., `astropy.io.fits.open`
-            or `asdf.open`).
+            Additional keyword arguments to be passed to the file reading function (e.g., `~astropy.io.fits.open`
+            or `~asdf.open`).
         """
         # Construct the full data URL based on mission
         download_url = self._get_download_url(uri, mission=mission)

astroquery/mast/tests/test_mast_remote.py

@@ -32,6 +32,11 @@
 )
 from ..utils import ResolverError
 
+try:
+    import asdf
+except ImportError:
+    asdf = None
+
 
 @pytest.fixture(scope="module")
 def msa_product_table():
@@ -432,7 +437,7 @@ def test_missions_read_product_fits(self, uri, mission):
         ('jwst', {'fileSetName': 'jw01189001001_02101_00001'}),
         ('classy', {'Target': 'J0021+0052'}),
         ('ullyses', {'host_galaxy_name': 'WLM', 'select_cols': ['observation_id']}),
-        ('roman', {'program': 3, 'pass_id': 1}),
+        ('roman', {'program': 163}),
         ('iue', {'iue_data_id': 'LWR08496'}),
     ])
     def test_missions_workflow(self, tmp_path, mission, query_params):
@@ -461,6 +466,17 @@ def test_missions_workflow(self, tmp_path, mission, query_params):
             if row['Status'] == 'COMPLETE':
                 assert (row['Local Path']).is_file()
 
+        # Read a product
+        product = None
+        for prod in prods:
+            if prod['filename'].endswith(('.fits', '.asdf')):
+                product = prod
+                break
+        obj = m.read_product(product['uri'], mission=mission)
+        if mission == 'roman' and asdf is not None:
+            assert isinstance(obj, asdf.AsdfFile)
+        assert isinstance(obj, fits.HDUList)
+
     ###################
     # MastClass tests #
     ###################

docs/conf.py

@@ -12,11 +12,11 @@
 # See astropy.sphinx.conf for which values are set there.
 
 import datetime
-import os
 import sys
-import tomllib
 from pathlib import Path
 
+import tomllib
+
 # Load all of the global Astropy configuration
 try:
     from sphinx_astropy.conf.v1 import *  # noqa
@@ -56,6 +56,7 @@
     'regions': ('https://astropy-regions.readthedocs.io/en/stable', None),
     'mocpy': ('https://cds-astro.github.io/mocpy', None),
     'pyvo': ('https://pyvo.readthedocs.io/en/stable', None),
+    'asdf': ('https://asdf.readthedocs.io/en/stable/', None),
 })
 
 # -- Project information ------------------------------------------------------

docs/mast/mast_missions.rst

@@ -3,7 +3,7 @@
 Mission-Specific Queries
 ************************
 
-The `~astroquery.mast.MastMissionsClass` class allows for search queries based on mission-specific 
+The `~astroquery.mast.MastMissionsClass` class allows for search queries based on mission-specific
 metadata for a given data collection. This metadata includes header keywords, proposal information, and observational parameters.
 The following missions/products are currently available for search:
 
@@ -49,12 +49,12 @@ To search for JWST metadata, the ``mission`` attribute is reassigned to ``'JWST'
 Querying Missions
 ==================
 
-The MastMissions interface provides three closely related query methods. All three methods return results as an `~astropy.table.Table` 
-and all three support column-based filtering, sorting, and result limiting. The primary difference between them is how positional 
+The MastMissions interface provides three closely related query methods. All three methods return results as an `~astropy.table.Table`
+and all three support column-based filtering, sorting, and result limiting. The primary difference between them is how positional
 constraints are specified.
 
 At a high level:
-  - `~astroquery.mast.MastMissionsClass.query_criteria` is the most flexible method. It supports purely column-based queries, 
+  - `~astroquery.mast.MastMissionsClass.query_criteria` is the most flexible method. It supports purely column-based queries,
     purely positional queries, or a combination of both.
 
   - `~astroquery.mast.MastMissionsClass.query_region` is a convenience wrapper for positional queries using coordinates.
@@ -78,7 +78,7 @@ using the `~astroquery.mast.MastMissionsClass.get_column_list` method.
 
 Keyword arguments can also be used to refine results further. The following parameters are available:
 
-- ``radius``: For positional searches only. Only return results within a certain distance from an object or set of coordinates. 
+- ``radius``: For positional searches only. Only return results within a certain distance from an object or set of coordinates.
   Default is 3 arcminutes.
 
 - ``limit``: The maximum number of results to return. Default is 5000.
@@ -99,25 +99,25 @@ Writing Queries
 ----------------
 
 The `~astroquery.mast.MastMissionsClass.query_criteria` method supports both positional parameters and column-based filters.
-Positional constraints are optional. 
+Positional constraints are optional.
 
 Supported positional parameters include:
 
   - ``coordinates`` : Sky coordinates around which to perform a cone search.
   - ``object_name`` : Name(s) of the object(s) around which to perform a cone search.
   - ``resolver`` : Resolver service to use for object name resolution.
-  - ``radius`` : Radius of the cone searches around the specified coordinates or object names. Can be defined as an `~astropy.units.Quantity`, 
+  - ``radius`` : Radius of the cone searches around the specified coordinates or object names. Can be defined as an `~astropy.units.Quantity`,
     a string with units (e.g., ``"10 arcsec"``), or a numeric value interpreted as degrees.
 
-Multiple coordinates or objects may be queried in a single request. The ``coordinates`` and ``object_names`` parameters 
+Multiple coordinates or objects may be queried in a single request. The ``coordinates`` and ``object_names`` parameters
 accept a single value, an iterable of values, or a comma-separated string. When multiple values are provided for either parameter,
 results matching *any* of the supplied positions are returned.
 
 .. doctest-remote-data::
 
    >>> from astropy.coordinates import SkyCoord
    >>> select_cols = ["sci_targname", "sci_pep_id", "sci_status"]
-   >>> results = missions.query_criteria(coordinates=[SkyCoord(245.89675, -26.52575, unit='deg'), "205.54842 28.37728"], 
+   >>> results = missions.query_criteria(coordinates=[SkyCoord(245.89675, -26.52575, unit='deg'), "205.54842 28.37728"],
    ...                                   object_names=["M2", "M9"],
    ...                                   radius=0.1,
    ...                                   select_cols=select_cols,
@@ -168,13 +168,13 @@ Criteria syntax supports several operations:
 
 - For numeric or date columns, select an inclusive range with the syntax ``'#..#'``.
 
-- Wildcards are special characters used in search patterns to represent one or more unknown characters, 
+- Wildcards are special characters used in search patterns to represent one or more unknown characters,
   allowing for flexible matching of strings. The wildcard character is ``*`` and it replaces any number
   of characters preceding, following, or in between existing characters, depending on its placement.
 
 .. note::
 
-  For the Roman mission, query methods also support the ``pass_id`` parameter as an alias for the ``pass`` column, 
+  For the Roman mission, query methods also support the ``pass_id`` parameter as an alias for the ``pass`` column,
   which refers to a single iteration of a pass plan. This is to avoid conflicts with the reserved Python keyword.
 
 .. doctest-remote-data::
@@ -196,7 +196,7 @@ Criteria syntax supports several operations:
         N4A702010 GAL-CLUS-0026+1653-ARCC         F110W        IMAGE
         N4A705010 GAL-CLUS-0026+1653-ARCC         F110W        IMAGE
 
-The `~astroquery.mast.MastMissionsClass.query_region` and `~astroquery.mast.MastMissionsClass.query_object` methods are 
+The `~astroquery.mast.MastMissionsClass.query_region` and `~astroquery.mast.MastMissionsClass.query_object` methods are
 convenience wrappers around `~astroquery.mast.MastMissionsClass.query_criteria`:
 
   - `~astroquery.mast.MastMissionsClass.query_region` requires ``coordinates``.
@@ -209,7 +209,7 @@ Both methods also accept column-based criteria, which are applied in the same wa
 
    >>> regionCoords = SkyCoord(210.80227, 54.34895, unit=('deg', 'deg'))
    >>> select_cols = ["sci_stop_time", "sci_targname", "sci_start_time", "sci_status"]
-   >>> results = missions.query_region(regionCoords, 
+   >>> results = missions.query_region(regionCoords,
    ...                                 radius=3,
    ...                                 sci_pep_id=12556,
    ...                                 select_cols=select_cols,
@@ -226,8 +226,8 @@ Both methods also accept column-based criteria, which are applied in the same wa
 
 .. doctest-remote-data::
 
-   >>> results = missions.query_object('M101', 
-   ...                                 radius=3, 
+   >>> results = missions.query_object('M101',
+   ...                                 radius=3,
    ...                                 select_cols=select_cols,
    ...                                 sort_by='sci_targname')
    >>> results[:5]  # doctest: +IGNORE_OUTPUT
@@ -248,11 +248,11 @@ Getting Product Lists
 ----------------------
 
 Each observation returned from a MAST query can have one or more associated data products. Given
-one or more datasets or dataset IDs, the `~astroquery.mast.MastMissionsClass.get_product_list` function 
+one or more datasets or dataset IDs, the `~astroquery.mast.MastMissionsClass.get_product_list` function
 will return a `~astropy.table.Table` containing the associated data products.
 
-`~astroquery.mast.MastMissionsClass.get_product_list` also includes an optional ``batch_size`` parameter, 
-which controls how many datasets are sent to the MAST service per request. This can be useful for managing 
+`~astroquery.mast.MastMissionsClass.get_product_list` also includes an optional ``batch_size`` parameter,
+which controls how many datasets are sent to the MAST service per request. This can be useful for managing
 memory usage or avoiding timeouts when requesting product lists for large numbers of datasets.
 If not provided, batch_size defaults to 1000.
 
@@ -262,7 +262,7 @@ If not provided, batch_size defaults to 1000.
    ...                                    sci_hlsp='>1')
    >>> products = missions.get_product_list(datasets[:2], batch_size=1000)
    >>> print(products[:5])  # doctest: +IGNORE_OUTPUT
-           product_key          access  dataset  ...  category     size     type 
+           product_key          access  dataset  ...  category     size     type
    ---------------------------- ------ --------- ... ---------- --------- -------
    JBTAA0010_jbtaa0010_asn.fits PUBLIC JBTAA0010 ...        AUX     11520 science
    JBTAA0010_jbtaa0010_drz.fits PUBLIC JBTAA0010 ... CALIBRATED 214655040 science
@@ -298,8 +298,8 @@ and any other of the product fields.
 The **AND** operation is applied between filters, and the **OR** operation is applied within each filter set, except in the case of negated values.
 
 A filter value can be negated by prefiing it with ``!``, meaning that rows matching that value will be excluded from the results.
-When any negated value is present in a filter set, any positive values in that set are combined with **OR** logic, and the negated 
-values are combined with **AND** logic against the positives. 
+When any negated value is present in a filter set, any positive values in that set are combined with **OR** logic, and the negated
+values are combined with **AND** logic against the positives.
 
 For example:
   - ``file_suffix=['A', 'B', '!C']`` → (file_suffix != C) AND (file_suffix == A OR file_suffix == B)
@@ -318,28 +318,53 @@ The filter below returns FITS products that are "science" type **and** less than
    >>> filtered = missions.filter_products(products,
    ...                                     extension='fits',
    ...                                     type='science',
-   ...                                     size='<=20000',        
+   ...                                     size='<=20000',
    ...                                     file_suffix=['ASN', 'JIF'])
    >>> print(filtered)  # doctest: +IGNORE_OUTPUT
-         product_key          access  dataset  ...    category     size   type 
+         product_key          access  dataset  ...    category     size   type
    ---------------------------- ------ --------- ... -------------- ----- -------
    JBTAA0010_jbtaa0010_asn.fits PUBLIC JBTAA0010 ...            AUX 11520 science
    JBTAA0020_jbtaa0020_asn.fits PUBLIC JBTAA0020 ...            AUX 11520 science
 
 
+Reading Data Products
+======================
+
+The `~astroquery.mast.MastMissionsClass.read_product` function allows you to read a data product directly into memory as an `~astropy.io.fits.HDUList`
+or an `~asdf.AsdfFile` object. The function accepts a product URI or a direct filename (for certain missions) as input.
+
+Products from the Roman Space Telescope mission are returned as ASDF files and can be read into memory as `~asdf.AsdfFile` objects.
+This requires the `~asdf` and ``fsspec`` packages to be installed. Other optional packages for reading products may be required depending on the product
+type and file format. These packages are ``gwcs``, ``lz4``, and ``roman_datamodels``. To install astroquery with all optional dependencies,
+use ``pip install astroquery[all]``.
+
+Remember that this method returns an open file object, so it is the user's responsibility to close the file when finished. This can be done
+with a context manager or by calling the ``close()`` method on the returned object.
+
+.. doctest-remote-data::
+   >>> obj = missions.read_product("jbtaa0010_asn.fits")  # doctest: +IGNORE_OUTPUT
+   >>> print(type(obj))
+   <class 'astropy.io.fits.hdu.hdulist.HDUList'>
+   >>> obj.info()  # doctest: +IGNORE_OUTPUT
+   Filename: /Users/user/.astropy/cache/download/url/6555b8e890752df0de737940d3afb19d/contents
+   No.    Name      Ver    Type      Cards   Dimensions   Format
+     0  PRIMARY       1 PrimaryHDU      44   ()
+     1  ASN           1 BinTableHDU     25   3R x 3C   [14A, 14A, L]
+   >>> obj.close()
+
 Downloding Data
 ===============
 
 Downloading Data Products
 -------------------------
 
-The `~astroquery.mast.MastMissionsClass.download_products` function accepts a table of products like the one above 
-and will download the products to your local machine. Products may also be provided as dataset IDs with product filters, 
+The `~astroquery.mast.MastMissionsClass.download_products` function accepts a table of products like the one above
+and will download the products to your local machine. Products may also be provided as dataset IDs with product filters,
 or as JSON product metadata sent by the MAST subscription service (either as a local JSON file or as in-memory data).
 
 By default, products will be downloaded into the current working directory, in a subdirectory called ``mastDownload``.
-The full local filepaths will have the form ``mastDownload/<mission>/<Dataset ID>/file.`` You can change the download 
-directory using the ``download_dir`` parameter. If ``flat=True`` is specified, all files will be downloaded directly into the 
+The full local filepaths will have the form ``mastDownload/<mission>/<Dataset ID>/file.`` You can change the download
+directory using the ``download_dir`` parameter. If ``flat=True`` is specified, all files will be downloaded directly into the
 ``download_dir`` without any subdirectories.
 
 .. doctest-remote-data::
@@ -349,14 +374,14 @@ directory using the ``download_dir`` parameter. If ``flat=True`` is specified, a
    Downloading URL https://mast.stsci.edu/search/hst/api/v0.1/retrieve_product?product_name=JBTAA0020%2Fjbtaa0020_asn.fits to mastDownload/hst/JBTAA0020/jbtaa0020_asn.fits ... [Done]
    Downloading URL https://mast.stsci.edu/search/hst/api/v0.1/retrieve_product?product_name=JBTAA0020%2Fjbtaa0020_jif.fits to mastDownload/hst/JBTAA0020/jbtaa0020_jif.fits ... [Done]
    >>> print(manifest)  # doctest: +IGNORE_OUTPUT
-                     Local Path                   Status  Message URL 
+                     Local Path                   Status  Message URL
    --------------------------------------------- -------- ------- ----
    mastDownload/hst/JBTAA0010/jbtaa0010_asn.fits COMPLETE    None None
    mastDownload/hst/JBTAA0010/jbtaa0010_jif.fits COMPLETE    None None
    mastDownload/hst/JBTAA0020/jbtaa0020_asn.fits COMPLETE    None None
    mastDownload/hst/JBTAA0020/jbtaa0020_jif.fits COMPLETE    None None
 
-The function also accepts dataset IDs and product filters as input for a more streamlined workflow. 
+The function also accepts dataset IDs and product filters as input for a more streamlined workflow.
 
 .. doctest-remote-data::
    >>> missions.download_products(['JBTAA0010', 'JBTAA0020'],
@@ -374,7 +399,7 @@ Downloading a Single File
 To download a single data product file, use the `~astroquery.mast.MastMissionsClass.download_file` function with
 a MAST URI as input. Some missions (e.g., HST, JWST) accept direct filenames as input, but others require a fully-qualified ``mast:`` URI.
 
-The default is to download the file to the current working directory, but you can specify the download directory or filepath with 
+The default is to download the file to the current working directory, but you can specify the download directory or filepath with
 the ``local_path`` keyword argument.
 
 .. doctest-remote-data::

pyproject.toml

@@ -54,6 +54,7 @@ docs = [
    "sphinx-astropy>=1.5",
    "scipy",
    "fsspec[http]",
+   "asdf"
 ]
 all = [
    "mocpy>=0.12",