New function to get TESS sectors for a position and cutout size (#168)

snbianco · web-flow · commit db9a1eae1ea8 · 2025-11-03T08:46:07.000-05:00
* get_tess_sectors function

* docstrings, changelog

* Add note about private functions in docstring

* More tests, better handling for invalid coordinates

* Fix test

* Fix table creation for other versions
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -3,6 +3,8 @@ Unreleased
 
 - Added support in `ra_dec_crossmatch` for a cutout size of zero, enabling single-point matching to FFIs that contain
   the specified coordinates. [#166]
+- Added ``get_tess_sectors`` function to return TESS sector information for sectors whose footprints overlap with 
+  the given sky coordinates and cutout size. [#168]
 
 
 1.1.0 (2025-09-15)
diff --git a/astrocut/__init__.py b/astrocut/__init__.py
@@ -39,4 +39,4 @@
     from .asdf_cutout import ASDFCutout, asdf_cut, get_center_pixel  # noqa
     from .tess_cube_cutout import TessCubeCutout  # noqa
     from .footprint_cutout import ra_dec_crossmatch # noqa
-    from .tess_footprint_cutout import TessFootprintCutout, cube_cut_from_footprint  # noqa
+    from .tess_footprint_cutout import TessFootprintCutout, cube_cut_from_footprint, get_tess_sectors  # noqa
diff --git a/astrocut/footprint_cutout.py b/astrocut/footprint_cutout.py
@@ -13,6 +13,7 @@
 from spherical_geometry.vector import radec_to_vector
 
 from .cutout import Cutout
+from .exceptions import InvalidInputError
 
 FFI_TTLCACHE = TTLCache(maxsize=10, ttl=900)  # Cache for FFI footprint files
 
@@ -55,20 +56,6 @@ def __init__(self, coordinates: Union[SkyCoord, str],
             sequence = [sequence]  # Convert to list
         self._sequence = sequence
 
-        # Populate these in child classes 
-        self._s3_footprint_cache = None  # S3 URI to footprint cache file
-        self._arcsec_per_px = None  # Number of arcseconds per pixel in an image
-    
-    @abstractmethod
-    def _get_files_from_cone_results(self, cone_results: Table) -> dict:
-        """
-        Converts a `~astropy.table.Table` of cone search results to a list of dictionaries containing
-        metadata for each cloud file that intersects with the cutout.
-        
-        This method is abstract and should be implemented in subclasses.
-        """
-        raise NotImplementedError('Subclasses must implement this method.')
-
     @abstractmethod
     def cutout(self):
         """
@@ -314,7 +301,10 @@ def ra_dec_crossmatch(all_ffis: Table, coordinates: Union[SkyCoord, str], cutout
     """
     # Convert coordinates to SkyCoord
     if not isinstance(coordinates, SkyCoord):
-        coordinates = SkyCoord(coordinates, unit='deg')
+        try:
+            coordinates = SkyCoord(coordinates, unit='deg')
+        except ValueError as e:
+            raise InvalidInputError(f'Invalid coordinates input: {e}')
     ra, dec = coordinates.ra, coordinates.dec
 
     px_size = np.zeros(2, dtype=object)
diff --git a/astrocut/tess_footprint_cutout.py b/astrocut/tess_footprint_cutout.py
@@ -65,6 +65,12 @@ class TessFootprintCutout(FootprintCutout):
         Write the cutouts as Target Pixel Files (TPFs) to the specified directory.
     """
 
+    # Mission-specific defaults
+    ARCSEC_PER_PX = 21  # Number of arcseconds per pixel in a TESS image
+    S3_FOOTPRINT_CACHE = 's3://stpubdata/tess/public/footprints/tess_ffi_footprint_cache.json'
+    S3_BASE_FILE_PATH = 's3://stpubdata/tess/public/mast/'
+
+
     @deprecated_renamed_argument('product', None, since='1.1.0', message='Astrocut no longer supports cutouts from '
                                  'TESS Image Calibrator (TICA) products. '
                                  'The `product` argument is deprecated and will be removed in a future version.')
@@ -78,101 +84,9 @@ def __init__(self, coordinates: Union[SkyCoord, str],
         if product.upper() != 'SPOC':
             raise InvalidInputError('Product for TESS cube cutouts must be "SPOC".')
         self._product = 'SPOC'
-        self._arcsec_per_px = 21  # Number of arcseconds per pixel in a TESS image
-
-        # Set S3 URIs to footprint cache file and base file path
-        self._s3_footprint_cache = 's3://stpubdata/tess/public/footprints/tess_ffi_footprint_cache.json'
-        self._s3_base_file_path = 's3://stpubdata/tess/public/mast/'
 
         # Make the cutouts upon initialization
         self.cutout()
-    
-    def _extract_sequence_information(self, sector_name: str) -> dict:
-        """
-        Extract the sector, camera, and ccd information from the sector name.
-
-        Parameters
-        ----------
-        sector_name : str
-            The name of the sector.
-
-        Returns
-        -------
-        dict
-            A dictionary containing the sector name, sector number, camera number, and CCD number.
-        """
-        # Example sector name format: "tess-s0001-4-4"
-        pattern = re.compile(r"(tess-s)(?P<sector>\d{4})-(?P<camera>\d{1,4})-(?P<ccd>\d{1,4})")
-        sector_match = re.match(pattern, sector_name)
-
-        if not sector_match:
-            # Return an empty dictionary if the name does not match the product pattern
-            return {}
-
-        # Extract the sector, camera, and ccd information
-        sector = sector_match.group("sector")
-        camera = sector_match.group("camera")
-        ccd = sector_match.group("ccd")
-
-        return {"sectorName": sector_name, "sector": sector, "camera": camera, "ccd": ccd}
-    
-    def _create_sequence_list(self, observations: Table) -> List[dict]:
-        """
-        Extracts sequence information from a list of observations.
-
-        Parameters
-        ----------
-        observations : `~astropy.table.Table`
-            A table of FFI observations.
-
-        Returns
-        -------
-        list of dict
-            A list of dictionaries, each containing the sector name, sector number, camera number, and CCD number.
-        """
-        # Filter observations by target name to get only the FFI observations
-        obs_filtered = [obs for obs in observations if obs["target_name"].upper() == "TESS FFI"]
-
-        sequence_results = []
-        for row in obs_filtered:
-            # Extract the sector information for each FFI observation
-            sequence_extraction = self._extract_sequence_information(row["obs_id"])
-            if sequence_extraction:
-                sequence_results.append(sequence_extraction)
-
-        return sequence_results
-    
-    def _get_files_from_cone_results(self, cone_results: Table) -> List[dict]:
-        """
-        Converts a `~astropy.table.Table` of cone search results to a list of dictionaries containing 
-        information for each cloud cube file that intersects with the cutout.
-
-        Parameters
-        ----------
-        cone_results : `~astropy.table.Table`
-            A table containing observation results, including sector information.
-
-        Returns
-        -------
-        cube_files : list of dict
-            A list of dictionaries, each containing:
-            - "folder": The folder name corresponding to the sector, prefixed with 's' and zero-padded to 4 digits.
-            - "cube": The expected filename for the cube FITS file in the format "{sectorName}-cube.fits".
-            - "sectorName": The sector name.
-        """
-        # Create a list of dictionaries containing the sector information
-        seq_list = self._create_sequence_list(cone_results)
-
-        # Create a list of dictionaries containing the cube file information
-        cube_files = [
-            {
-                "folder": "s" + sector["sector"].rjust(4, "0"),
-                "cube": sector["sectorName"] + "-cube.fits",
-                "sectorName": sector["sectorName"],
-            }
-            for sector in seq_list
-        ]
-        return cube_files
 
     def cutout(self):
         """
@@ -185,7 +99,7 @@ def cutout(self):
             If the given coordinates are not found within the specified sequence(s).
         """
         # Get footprints from the cloud
-        all_ffis = get_ffis(self._s3_footprint_cache)
+        all_ffis = get_ffis(self.S3_FOOTPRINT_CACHE)
         log.debug('Found %d footprint files.', len(all_ffis))
 
         # Filter footprints by sequence
@@ -200,15 +114,15 @@ def cutout(self):
                       ', '.join(str(s) for s in self._sequence))
 
         # Get sequence names and files that contain the cutout
-        cone_results = ra_dec_crossmatch(all_ffis, self._coordinates, self._cutout_size, self._arcsec_per_px)
+        cone_results = ra_dec_crossmatch(all_ffis, self._coordinates, self._cutout_size, self.ARCSEC_PER_PX)
         if not cone_results:
             raise InvalidQueryError('The given coordinates were not found within the specified sequence(s).')
-        files_mapping = self._get_files_from_cone_results(cone_results)
+        files_mapping = _get_files_from_cone_results(cone_results)
         log.debug('Found %d matching files.', len(files_mapping))
 
         # Generate the cube cutouts
         log.debug('Generating cutouts...')
-        input_files = [f"{self._s3_base_file_path}{file['cube']}" for file in files_mapping]
+        input_files = [f"{self.S3_BASE_FILE_PATH}{file['cube']}" for file in files_mapping]
         tess_cube_cutout = TessCubeCutout(input_files, self._coordinates, self._cutout_size, 
                                           self._fill_value, self._limit_rounding_method, threads=8, 
                                           verbose=self._verbose)
@@ -237,6 +151,102 @@ def write_as_tpf(self, output_dir: Union[str, Path] = '.') -> List[str]:
         return self.tess_cube_cutout.write_as_tpf(output_dir)
 
 
+def _extract_sequence_information(sector_name: str) -> dict:
+    """
+    Extract the sector, camera, and ccd information from the sector name.
+
+    This is a helper function and should be left private.
+
+    Parameters
+    ----------
+    sector_name : str
+        The name of the sector.
+
+    Returns
+    -------
+    dict
+        A dictionary containing the sector name, sector number, camera number, and CCD number.
+    """
+    # Example sector name format: "tess-s0001-4-4"
+    pattern = re.compile(r"(tess-s)(?P<sector>\d{4})-(?P<camera>\d{1,4})-(?P<ccd>\d{1,4})")
+    sector_match = re.match(pattern, sector_name)
+
+    if not sector_match:
+        # Return an empty dictionary if the name does not match the product pattern
+        return {}
+
+    # Extract the sector, camera, and ccd information
+    sector = sector_match.group("sector")
+    camera = sector_match.group("camera")
+    ccd = sector_match.group("ccd")
+
+    return {"sectorName": sector_name, "sector": sector, "camera": camera, "ccd": ccd}
+
+
+def _create_sequence_list(observations: Table) -> List[dict]:
+    """
+    Extracts sequence information from a list of observations.
+
+    This is a helper function and should be left private.
+
+    Parameters
+    ----------
+    observations : `~astropy.table.Table`
+        A table of FFI observations.
+
+    Returns
+    -------
+    list of dict
+        A list of dictionaries, each containing the sector name, sector number, camera number, and CCD number.
+    """
+    # Filter observations by target name to get only the FFI observations
+    obs_filtered = [obs for obs in observations if obs["target_name"].upper() == "TESS FFI"]
+
+    sequence_results = []
+    for row in obs_filtered:
+        # Extract the sector information for each FFI observation
+        sequence_extraction = _extract_sequence_information(row["obs_id"])
+        if sequence_extraction:
+            sequence_results.append(sequence_extraction)
+
+    return sequence_results
+
+
+def _get_files_from_cone_results(cone_results: Table) -> List[dict]:
+    """
+    Converts a `~astropy.table.Table` of cone search results to a list of dictionaries containing 
+    information for each cloud cube file that intersects with the cutout.
+
+    This is a helper function and should be left private.
+
+    Parameters
+    ----------
+    cone_results : `~astropy.table.Table`
+        A table containing observation results, including sector information.
+
+    Returns
+    -------
+    cube_files : list of dict
+        A list of dictionaries, each containing:
+        - "folder": The folder name corresponding to the sector, prefixed with 's' and zero-padded to 4 digits.
+        - "cube": The expected filename for the cube FITS file in the format "{sectorName}-cube.fits".
+        - "sectorName": The sector name.
+    """
+    # Create a list of dictionaries containing the sector information
+    seq_list = _create_sequence_list(cone_results)
+
+    # Create a list of dictionaries containing the cube file information
+    cube_files = [
+        {
+            "folder": "s" + sector["sector"].rjust(4, "0"),
+            "cube": sector["sectorName"] + "-cube.fits",
+            "sectorName": sector["sectorName"],
+        }
+        for sector in seq_list
+    ]
+    return cube_files
+
+
 @deprecated_renamed_argument('product', None, since='1.1.0', message='Astrocut no longer supports cutouts from '
                              'TESS Image Calibrator (TICA) products. '
                              'The `product` argument is deprecated and will be removed in a future version.')
@@ -295,11 +305,62 @@ def cube_cut_from_footprint(coordinates: Union[str, SkyCoord], cutout_size,
     ['./cutouts/tess-s0001-4-4/tess-s0001-4-4_83.406310_-62.489771_64x64_astrocut.fits',
      './cutouts/tess-s0002-4-1/tess-s0002-4-1_83.406310_-62.489771_64x64_astrocut.fits']
     """
-
+    # Create the TessFootprintCutout object
     cutouts = TessFootprintCutout(coordinates, cutout_size, sequence=sequence, product=product, verbose=verbose)
 
+    # Return cutouts as memory objects
     if memory_only:
         return cutouts.tpf_cutouts
     
     # Write cutouts
     return cutouts.write_as_tpf(output_dir)
+
+
+def get_tess_sectors(coordinates: Union[str, SkyCoord],
+                     cutout_size: Union[int, u.Quantity, List[int], Tuple[int]]) -> Table:
+    """
+    Return the TESS sectors (sequence, camera, CCD) whose FFI footprints overlap
+    the given cutout defined by position and size.
+
+    Parameters
+    ----------
+    coordinates : str or `astropy.coordinates.SkyCoord` object
+        The position around which to cutout. It may be specified as a string ("ra dec" in degrees)
+        or as the appropriate `~astropy.coordinates.SkyCoord` object.
+    cutout_size : int, array-like, or `~astropy.units.Quantity`
+        The size of the cutout array. If ``cutout_size``
+        is a scalar number or a scalar `~astropy.units.Quantity`,
+        then a square cutout of ``cutout_size`` will be used.  If
+        ``cutout_size`` has two elements, they should be in ``(ny, nx)``
+        order.  Scalar numbers in ``cutout_size`` are assumed to be in
+        units of pixels. `~astropy.units.Quantity` objects must be in pixel or
+        angular units.
+
+        If a cutout size of zero is provided, the function will return sectors that contain 
+        the exact RA and Dec position. If a non-zero cutout size is provided, the function 
+        will return sectors whose footprints overlap with the cutout area.
+
+    Returns
+    -------
+    `~astropy.table.Table`
+        A table containing the sector name, sector number, camera number, and CCD number
+        for each sector that contains the specified coordinates within the cutout size.
+    """
+    column_names = ['sectorName', 'sector', 'camera', 'ccd']
+    column_dtypes = ['S20', 'i4', 'i4', 'i4']
+
+    # Get footprints from the cloud
+    ffis = get_ffis(TessFootprintCutout.S3_FOOTPRINT_CACHE)
+
+    # Crossmatch to find matching FFIs
+    matched_ffis = ra_dec_crossmatch(ffis, coordinates, cutout_size, TessFootprintCutout.ARCSEC_PER_PX)
+    if len(matched_ffis) == 0:  # Return empty table if no matches
+        return Table(names=column_names, dtype=column_dtypes)
+
+    # Create a list of unique sector entries
+    sector_list = _create_sequence_list(matched_ffis)
+
+    return Table(rows=[
+        (entry['sectorName'], int(entry['sector']), int(entry['camera']), int(entry['ccd']))
+        for entry in sector_list
+    ], names=column_names, dtype=column_dtypes)
diff --git a/astrocut/tests/test_tess_footprint_cutout.py b/astrocut/tests/test_tess_footprint_cutout.py
