lightstack 0.3.2__tar.gz → 0.4.0__tar.gz

{lightstack-0.3.2/src/lightstack.egg-info → lightstack-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: lightstack
-Version: 0.3.2
+Version: 0.4.0
 Summary: Tools for building and processing multi-filter astrophysical datacubes
 Author: Andressa Wille, Thallis Pessi
 License: MIT License
@@ -36,13 +36,13 @@ Requires-Dist: scipy
 Requires-Dist: photutils
 Requires-Dist: pandas
 
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19393438.svg)](https://doi.org/10.5281/zenodo.20360028)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19393438.svg)](https://doi.org/10.5281/zenodo.22148981)
 
 <img src="https://raw.githubusercontent.com/AndressaWille/lightstack/master/images/logo.png" width="120">
 
 # Lightstack
 
-Tools for building and processing multi-filter astrophysical datacubes. 
+Tools for building and processing multi-filter (and multi-servey) astrophysical datacubes. 
 
 ## Features
 
@@ -60,4 +60,4 @@ pip install lightstack
 
 https://lightstack.readthedocs.io/en/latest/
 
-See the tutorial notebook (in the "examples" folder)! 
+See the tutorial notebooks (in the "examples" folder)! 

{lightstack-0.3.2 → lightstack-0.4.0}/README.md

@@ -1,10 +1,10 @@
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19393438.svg)](https://doi.org/10.5281/zenodo.20360028)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19393438.svg)](https://doi.org/10.5281/zenodo.22148981)
 
 <img src="https://raw.githubusercontent.com/AndressaWille/lightstack/master/images/logo.png" width="120">
 
 # Lightstack
 
-Tools for building and processing multi-filter astrophysical datacubes. 
+Tools for building and processing multi-filter (and multi-servey) astrophysical datacubes. 
 
 ## Features
 
@@ -22,4 +22,4 @@ pip install lightstack
 
 https://lightstack.readthedocs.io/en/latest/
 
-See the tutorial notebook (in the "examples" folder)! 
+See the tutorial notebooks (in the "examples" folder)! 

{lightstack-0.3.2 → lightstack-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lightstack"
-version = "0.3.2"
+version = "0.4.0"
 description = "Tools for building and processing multi-filter astrophysical datacubes"
 readme = "README.md"
 authors = [{name = "Andressa Wille"}, {name="Thallis Pessi"}]

{lightstack-0.3.2 → lightstack-0.4.0}/src/lightstack/__init__.py

@@ -34,6 +34,7 @@ from .datacube import (
     build_valid_datacube,
     remove_filter,
     update_cube_header,
+    apply_reference_nan_mask,
 )
 
 # =========================
@@ -52,6 +53,8 @@ from .psf import (
     oversample_psf,
     add_arcsec_axis,
     encircled_energy,
+    measure_psf_fwhm,
+    print_psf_fwhm,
     clean_stellar_cutouts_radially,
     plot_stellar_radial_profiles,
     plot_psf_stars,
@@ -83,6 +86,7 @@ from .plot import (
 # =========================
 from .utils import (
     identify_filter,
+    check_filenames,
     get_filter_info,
     select_filters,
     add_custom_dataset,
@@ -94,6 +98,7 @@ from .utils import (
     MJy_sr_to_jy,
     get_pixel_scale,
     get_pixel_scale_from_wcs,
+    print_fits_spatial_info,
 )
 
 # =========================
@@ -117,6 +122,7 @@ __all__ = [
     "build_valid_datacube",
     "remove_filter",
     "update_cube_header",
+    "apply_reference_nan_mask",
 
     # psf
     "get_psf_input_files",
@@ -131,6 +137,8 @@ __all__ = [
     "oversample_psf",
     "add_arcsec_axis",
     "encircled_energy",
+    "measure_psf_fwhm",
+    "print_psf_fwhm",
     "clean_stellar_cutouts_radially",
     "plot_stellar_radial_profiles",
     "plot_psf_stars",
@@ -155,6 +163,7 @@ __all__ = [
     # utils
     "find_ext",
     "identify_filter",
+    "check_filenames",
     "get_filter_info",
     "select_filters",
     "add_custom_dataset",
@@ -165,5 +174,6 @@ __all__ = [
     "MJy_sr_to_jy",
     "get_pixel_scale",
     "get_pixel_scale_from_wcs",
+    "print_fits_spatial_info",
     
 ]

{lightstack-0.3.2 → lightstack-0.4.0}/src/lightstack/datacube.py

@@ -1,6 +1,7 @@
 import numpy as np
 import os
 import glob
+import re
 
 from astropy.io import fits
 from astropy.wcs import WCS
@@ -41,6 +42,25 @@ def load_image_fits(folder_path):
     return fits_files
 
 
+def _is_aligned_output(fpath):
+    """
+    Check whether a FITS file was written by ``align_reproject_fits``
+    (i.e. its name ends in ``_aligned_interp`` or ``_aligned_exact``).
+
+    Parameters
+    ----------
+    fpath : str or pathlib.Path
+        FITS filename.
+
+    Returns
+    -------
+    bool
+        True if the file is an output of ``align_reproject_fits``.
+    """
+    stem = os.path.splitext(os.path.basename(fpath))[0]
+    return re.search(r"_aligned_(interp|exact)$", stem) is not None
+
+
 def align_reproject_fits(
     fits_list,
     ref_file,
@@ -50,6 +70,11 @@ def align_reproject_fits(
     """
     Align and optionally reproject FITS images to a common WCS.
 
+    Files produced by a previous run of this function (names ending in
+    ``_aligned_interp.fits`` or ``_aligned_exact.fits``) are skipped, so
+    that only the original images are aligned and previous outputs are
+    overwritten instead of being aligned again.
+
     Parameters
     ----------
     fits_list : list of tuples
@@ -57,7 +82,8 @@ def align_reproject_fits(
         [(fits_path, dataset, filter_name), ...]
 
     ref_file : str
-        Reference FITS file.
+        Reference FITS file. It must be an original image, not a previous
+        ``*_aligned_*`` output.
 
     method : str, optional
         Reprojection method: "interp" or "exact".
@@ -86,6 +112,28 @@ def align_reproject_fits(
             "method must be 'interp' or 'exact'"
         )
 
+    # Skip outputs of previous runs to avoid duplicated filters
+    if _is_aligned_output(ref_file):
+        raise ValueError(
+            f"Reference file '{os.path.basename(ref_file)}' is the output "
+            "of a previous alignment. Use the original image instead."
+        )
+
+    skipped = [fpath for fpath, _, _ in fits_list if _is_aligned_output(fpath)]
+
+    if skipped:
+        print(
+            f"Skipping {len(skipped)} previously aligned file(s) "
+            "(they will be overwritten):"
+        )
+        for fpath in skipped:
+            print(f"  {os.path.basename(fpath)}")
+
+    fits_list = [
+        entry for entry in fits_list
+        if not _is_aligned_output(entry[0])
+    ]
+
     # --------------------------------------------------
     # 2. Open reference FITS
     # --------------------------------------------------
@@ -688,6 +736,14 @@ def remove_filter(cube_fits_file, output_cube, filter_to_remove):
         Path to save the new datacube.
     filter_to_remove : str
         Name of the filter to be removed.
+
+    Returns
+    -------
+    cube : ndarray
+        Datacube without the removed filter. If the filter is not found,
+        the original datacube is returned and no file is written.
+    filters : list of str
+        Filter names of the returned datacube.
     """
 
     # Open FITS
@@ -840,3 +896,73 @@ def update_cube_header(
         hdul.writeto(output_file, overwrite=overwrite)
 
     print(f"Updated header saved to: {output_file}")
+   
+def apply_reference_nan_mask(
+    cube_file,
+    reference_slice=0,
+    output_path=None,
+):
+    """
+    Propagate the NaN mask of a reference slice to all slices
+    of a datacube.
+
+    Parameters
+    ----------
+    cube_file : str or pathlib.Path
+        Input datacube FITS file.
+
+    reference_slice : int, optional
+        Index of the slice whose valid-pixel footprint will be used
+        as the reference mask. Default is 0.
+
+    output_path : str or pathlib.Path, optional
+        Output FITS file. If None, the cube is not saved.
+
+    Returns
+    -------
+    cube : ndarray
+        Cube with the reference NaN mask propagated to all slices.
+
+    header : fits.Header
+        FITS header from the input cube.
+    """
+
+    with fits.open(cube_file) as hdul:
+
+        cube = hdul[0].data.copy()
+        header = hdul[0].header.copy()
+
+    # Validate reference slice
+    if not 0 <= reference_slice < cube.shape[0]:
+        raise ValueError(
+            f"reference_slice={reference_slice} is outside the "
+            f"cube range (0-{cube.shape[0] - 1})."
+        )
+
+    # Reference mask
+    ref_mask = np.isfinite(
+        cube[reference_slice]
+    )
+
+    if not np.any(ref_mask):
+        raise ValueError(
+            f"Reference slice {reference_slice} contains no "
+            "valid pixels."
+        )
+
+    # Propagate mask
+    for i in range(cube.shape[0]):
+        cube[i][~ref_mask] = np.nan
+
+    # Save
+    if output_path is not None:
+
+        fits.PrimaryHDU(
+            cube,
+            header=header,
+        ).writeto(
+            output_path,
+            overwrite=True,
+        )
+
+    return cube, header

{lightstack-0.3.2 → lightstack-0.4.0}/src/lightstack/psf.py

@@ -3,6 +3,7 @@ from pathlib import Path
 import numpy as np
 import pandas as pd
 import os
+import warnings
 import matplotlib.pyplot as plt
 
 from astropy.visualization import simple_norm
@@ -12,7 +13,9 @@ from astropy.convolution import convolve_fft
 from photutils.centroids import centroid_com, centroid_quadratic
 from scipy.ndimage import shift, zoom, gaussian_filter, affine_transform
 from astropy.nddata import Cutout2D
-from astropy.stats import sigma_clip, sigma_clipped_stats
+from astropy.stats import gaussian_sigma_to_fwhm, sigma_clip, sigma_clipped_stats
+from astropy.modeling import fitting, models
+from astropy.utils.exceptions import AstropyWarning
 
 
 from .utils import (
@@ -43,7 +46,10 @@ def get_psf_input_files(data_dir, dataset):
     """
     data_dir = Path(data_dir)
 
-    fits_files = sorted(data_dir.glob("*.fits"))
+    fits_files = sorted(
+        f for f in data_dir.glob("*.fits")
+        if not f.name.lower().startswith("empirical_psf_")
+    )
 
     if not fits_files:
         raise FileNotFoundError(
@@ -81,7 +87,6 @@ def get_psf_input_files(data_dir, dataset):
 
     return inputs
 
-
 def extract_cutouts(image, stars, size):
     """
     Extract square cutouts centered on selected stars.
@@ -166,28 +171,87 @@ def subtract_background(cutout, border, sigma=3, clip_negative=True, noise_thres
 
     return corrected, background, background_std
 
-def measure_centers(cutouts):
+def measure_centers(cutouts, fallback="peak"):
     """
-    Measure quadratic centroids for a dictionary of stellar cutouts.
+    Measure stellar centers using quadratic centroids, with an optional
+    peak-based fallback.
 
     Parameters
     ----------
     cutouts : dict
-        Mapping of star names to two-dimensional image arrays.
+        Dictionary of stellar cutouts.
+
+    fallback : str or None, optional
+        Method used when the quadratic centroid fails.
+        Currently supports ``"peak"`` or ``None``.
 
     Returns
     -------
-    dict
-        Mapping of star names to dictionaries with ``x`` and ``y`` centroid
-        coordinates in pixels.
+    centers : dict
+        Dictionary containing the measured x and y centers and
+        the method used for each star.
     """
+
     centers = {}
+
     for name, image in cutouts.items():
-        x_center, y_center = centroid_quadratic(np.asarray(image))
-        centers[name] = {"x": x_center, "y": y_center}
+
+        image = np.asarray(image, dtype=float)
+
+        # Try quadratic centroid
+        x_center, y_center = centroid_quadratic(image)
+
+        if (
+            np.isfinite(x_center)
+            and np.isfinite(y_center)
+        ):
+            centers[name] = {
+                "x": float(x_center),
+                "y": float(y_center),
+                "method": "quadratic",
+            }
+
+            continue
+
+        # Fallback
+        if fallback == "peak":
+
+            if not np.any(np.isfinite(image)):
+                raise ValueError(
+                    f"Cannot determine center for star '{name}': "
+                    "cutout contains no finite pixels."
+                )
+
+            y_peak, x_peak = np.unravel_index(
+                np.nanargmax(image),
+                image.shape,
+            )
+
+            centers[name] = {
+                "x": float(x_peak),
+                "y": float(y_peak),
+                "method": "peak",
+            }
+
+        elif fallback is None:
+
+            centers[name] = {
+                "x": np.nan,
+                "y": np.nan,
+                "method": "failed",
+            }
+
+        else:
+
+            raise ValueError(
+                f"Unknown fallback method: '{fallback}'. "
+                "Use 'peak' or None."
+            )
+
     return centers
 
 
+
 def recenter_cutouts(cutouts, centers, order=3):
     """
     Shift cutouts so their measured centroids match their geometric centres.
@@ -414,6 +478,85 @@ def encircled_energy(image):
     radius, flux = radius[valid][order], flux[valid][order]
     return radius, np.cumsum(flux) / np.nansum(flux)
 
+def measure_psf_fwhm(psf):
+    """
+    Measure the FWHM of a PSF by fitting a 2D Gaussian to its core.
+
+    Parameters
+    ----------
+    psf : 2D ndarray
+        PSF image. Non-finite pixels are ignored.
+
+    Returns
+    -------
+    float
+        FWHM in pixels, averaged over the two axes of the fitted Gaussian.
+    """
+    data = np.nan_to_num(np.asarray(psf, dtype=float))
+
+    yc, xc = np.unravel_index(np.argmax(data), data.shape)
+
+    # Rough FWHM from the area above half maximum, used to size the fit box
+    fwhm0 = 2 * np.sqrt(np.sum(data > data[yc, xc] / 2) / np.pi)
+    half_size = int(np.ceil(max(5, 3 * fwhm0)))
+
+    y, x = np.mgrid[
+        max(yc - half_size, 0):yc + half_size + 1,
+        max(xc - half_size, 0):xc + half_size + 1,
+    ]
+
+    model = models.Gaussian2D(
+        amplitude=data[yc, xc], x_mean=xc, y_mean=yc,
+        x_stddev=fwhm0 / gaussian_sigma_to_fwhm,
+        y_stddev=fwhm0 / gaussian_sigma_to_fwhm,
+    )
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", AstropyWarning)
+        fitted = fitting.LevMarLSQFitter()(model, x, y, data[y, x])
+
+    sigma = (abs(fitted.x_stddev.value) + abs(fitted.y_stddev.value)) / 2
+
+    return sigma * gaussian_sigma_to_fwhm
+
+
+def print_psf_fwhm(psf_files, pixel_scale=None):
+    """
+    Measure and print the FWHM of a set of PSF FITS files.
+
+    Parameters
+    ----------
+    psf_files : iterable of str or pathlib.Path
+        PSF FITS files.
+    pixel_scale : float, optional
+        Pixel scale in arcsec/pixel. If None, it is read from the
+        ``PIXSCALE`` or ``PIXELSCL`` header keyword, if present.
+
+    Returns
+    -------
+    dict
+        FWHM in pixels for each filename.
+    """
+    results = {}
+
+    for psf_file in psf_files:
+
+        name = Path(psf_file).name
+
+        with fits.open(psf_file) as hdul:
+            hdu = hdul[find_ext(hdul)]
+            fwhm = measure_psf_fwhm(hdu.data)
+            scale = pixel_scale or hdu.header.get("PIXSCALE", hdu.header.get("PIXELSCL"))
+
+        results[name] = fwhm
+
+        if scale:
+            print(f"{name}: FWHM = {fwhm:.2f} px = {fwhm * scale:.4f} arcsec")
+        else:
+            print(f"{name}: FWHM = {fwhm:.2f} px")
+
+    return results
+
 def clean_stellar_cutouts_radially(
     cutouts,
     background_stds,
@@ -1303,19 +1446,19 @@ def build_empirical_psf(
         noise during background subtraction. Default is 0.5.
 
     radial_cleaning : bool, optional
-        If True, remove the outer part of each recentered cutout where its
-        radial profile falls below the background-noise threshold. Default is
-        False.
+        If True, set to zero the pixels of each stellar cutout outside a
+        cleaning radius determined from its radial profile (see
+        ``clean_stellar_cutouts_radially``). Default is False.
 
     cleaning_sigma : float, optional
-        Multiplier of each cutout's background RMS used to determine the
-        radial-cleaning threshold. Used only when ``radial_cleaning`` is
-        True. Default is 1.0.
+        Used only if ``radial_cleaning`` is True. The cleaning radius is
+        where the radial profile falls below ``cleaning_sigma`` times the
+        background standard deviation. Default is 1.0.
 
     cleaning_consecutive_bins : int, optional
-        Number of consecutive radial bins that must remain below the cleaning
-        threshold to define the cleaning radius. Used only when
-        ``radial_cleaning`` is True. Default is 3.
+        Used only if ``radial_cleaning`` is True. Number of consecutive
+        radial bins that must stay below the threshold to define the
+        cleaning radius. Default is 3.
 
     normalization_radius : float, optional
         Radius used to normalize each star. Its unit is controlled by
@@ -1342,23 +1485,24 @@ def build_empirical_psf(
         is used.
 
     plot_stars : bool, optional
-        If True, generate diagnostics for the background-subtracted,
-        recentered, and normalized stellar cutouts. Default is False.
+        If True, plot the stellar cutouts used to build the PSF (see
+        ``plot_psf_stars``). Default is False.
 
     plot_diagnostics : bool, optional
-        If True, generate diagnostic plots for the final native-resolution
-        PSF. Default is False.
+        If True, plot diagnostic figures of the final PSF (see
+        ``plot_psf_diagnostics``). Default is False.
 
     save_figures : bool, optional
-        If True, write the requested diagnostic figures to ``figure_dir``.
-        Default is False.
+        If True, save the figures enabled by ``plot_stars`` and
+        ``plot_diagnostics``. Requires ``figure_dir``. Default is False.
 
     show_figures : bool, optional
-        If True, display the requested diagnostic figures. Default is True.
+        If True, display the figures enabled by ``plot_stars`` and
+        ``plot_diagnostics``. Default is True.
 
     figure_dir : str or pathlib.Path or None, optional
-        Directory for diagnostic figures. Required when ``save_figures`` is
-        True; otherwise ignored.
+        Directory where figures are saved when ``save_figures`` is True.
+        Default is None.
 
     Returns
     -------
@@ -1394,19 +1538,13 @@ def build_empirical_psf(
             Aperture fluxes used for normalization.
 
         ``cutouts``
-            Original ``Cutout2D`` objects extracted around each star.
+            Background-subtracted stellar cutouts.
 
         ``cutouts_centered``
-            Background-subtracted stellar cutouts after centroid recentering.
-
-        ``cutouts_cleaned``
-            Recentered cutouts after optional radial cleaning.
+            Recentered stellar cutouts.
 
         ``cutouts_normalized``
-            Cleaned cutouts normalized by their aperture flux.
-
-        ``cleaning_radii``
-            Radial-cleaning radii in pixels, when radial cleaning is enabled.
+            Normalized stellar cutouts.
 
         ``psf_raw``
             Cropped stacked PSF before final normalization.
@@ -1538,7 +1676,11 @@ def build_empirical_psf(
         background_stds[name] = background_std
 
     # Measure and correct centroids
-    centers = measure_centers(cutouts_subtracted)
+
+    centers = measure_centers(
+        cutouts_subtracted,
+        fallback="peak",
+    )
 
     cutouts_centered = recenter_cutouts(
         cutouts_subtracted,
@@ -1715,6 +1857,7 @@ def build_empirical_psf(
     }
 
 
+
 def pad_psf_for_resampling(
     psf_path,
     target_pixel_scale,

{lightstack-0.3.2 → lightstack-0.4.0}/src/lightstack/utils.py

@@ -67,10 +67,10 @@ FILTER_DATABASE = {
             # ACS SBC
             #"F435W": {"lambda": 1518.84, "instrument": "ACS-SBC", "group": "ACS-SBC"},
 
-            # WFC3 UVIS
-            "F225W": {"lambda": 2357.65, "instrument": "WFC3", "group": "UVIS"},
-            "F275W": {"lambda": 2702.92, "instrument": "WFC3", "group": "UVIS"},
-            "F336W": {"lambda": 3354.60, "instrument": "WFC3", "group": "UVIS"},
+            # WFC3 UVIS ("aliases" covers the grizli "u" suffix, e.g. f225wu)
+            "F225W": {"lambda": 2357.65, "instrument": "WFC3", "group": "UVIS", "aliases": ["F225WU"]},
+            "F275W": {"lambda": 2702.92, "instrument": "WFC3", "group": "UVIS", "aliases": ["F275WU"]},
+            "F336W": {"lambda": 3354.60, "instrument": "WFC3", "group": "UVIS", "aliases": ["F336WU"]},
             "F390W": {"lambda": 3920.70, "instrument": "WFC3", "group": "UVIS"},
             "F680N": {"lambda": 6877.61, "instrument": "WFC3", "group": "UVIS"},
 
@@ -203,10 +203,99 @@ FILTER_DATABASE = {
 }
 
 
+def _naming_hint(dataset):
+    """
+    Explain the expected FITS filename convention for a dataset.
+
+    Parameters
+    ----------
+    dataset : str
+        Dataset key in ``FILTER_DATABASE`` (upper case).
+
+    Returns
+    -------
+    str
+        Message with the naming convention, examples and valid filters.
+    """
+    example_filter = next(iter(FILTER_DATABASE[dataset]["filters"]))
+    valid_filters = ", ".join(FILTER_DATABASE[dataset]["filters"])
+
+    return (
+        "Expected filename convention: the dataset name and the filter name "
+        "must appear as separate words, delimited by '_', '-' or '.' "
+        "(case-insensitive), e.g. "
+        f"'{dataset}_{example_filter}.fits' or "
+        f"'mytarget_{dataset}_{example_filter}_drz.fits'.\n"
+        "Other information is allowed in the filename, but whenever possible "
+        "keep only the dataset and the filter names "
+        f"(e.g. '{dataset}_{example_filter}.fits').\n"
+        f"Valid {dataset} filters: {valid_filters}."
+    )
+
+
+def _has_word(name, word):
+    """
+    Check whether ``word`` appears in ``name`` as a separate word, i.e. not
+    glued to other letters or digits (case-insensitive).
+
+    Parameters
+    ----------
+    name : str
+        Text to search, usually a filename without extension.
+    word : str
+        Word to look for, e.g. a dataset or filter name.
+
+    Returns
+    -------
+    bool
+        True if ``word`` is found as a separate word.
+    """
+    pattern = rf"(?<![A-Z0-9]){re.escape(word.upper())}(?![A-Z0-9])"
+    return re.search(pattern, name.upper()) is not None
+
+
+def _filters_in_name(name, dataset):
+    """
+    Return the dataset filters whose name, or one of its ``aliases``,
+    appears in ``name`` as a separate word.
+
+    Parameters
+    ----------
+    name : str
+        Text to search, usually a filename without extension.
+    dataset : str
+        Dataset key in ``FILTER_DATABASE`` (upper case).
+
+    Returns
+    -------
+    list of str
+        Canonical names of the filters found.
+    """
+    filters = FILTER_DATABASE[dataset]["filters"]
+
+    return [
+        filt
+        for filt, meta in filters.items()
+        if any(
+            _has_word(name, alias)
+            for alias in [filt, *meta.get("aliases", [])]
+        )
+    ]
+
+
 def identify_filter(fits_file, dataset):
     """
     Identify a FITS file's filter using its filename and a dataset registry.
 
+    The dataset name and the filter name (or one of its ``aliases``) must
+    appear in the filename as separate words, delimited by ``_``, ``-`` or
+    ``.`` (case-insensitive). For example, ``LSST_r.fits`` and
+    ``abell370_LSST_r_drz.fits`` are identified as LSST ``r``, while
+    ``abell370_LSST_rband.fits`` is not. Other information is allowed in the
+    filename, but whenever possible keep only the dataset and the filter
+    names (e.g. ``LSST_r.fits``); see ``simplify_fits_filename`` and
+    ``check_filenames``.
+
     Parameters
     ----------
     fits_file : str or pathlib.Path
@@ -222,12 +311,13 @@ def identify_filter(fits_file, dataset):
     Raises
     ------
     ValueError
-        If the dataset is unknown, absent from the filename, or no registered
-        filter can be identified.
+        If the dataset is unknown, absent from the filename, or if zero or
+        more than one registered filter is found in the filename.
     """
 
     dataset = dataset.upper()
-    filename = os.path.basename(fits_file).upper()
+    filename = Path(fits_file).name
+    stem = Path(fits_file).stem
 
     if dataset not in FILTER_DATABASE:
         raise ValueError(
@@ -236,22 +326,93 @@ def identify_filter(fits_file, dataset):
         )
 
     # Check that the dataset appears in the filename
-    if dataset not in filename:
+    if not _has_word(stem, dataset):
         raise ValueError(
-            f"Dataset '{dataset}' not found in filename: "
-            f"{os.path.basename(fits_file)}"
+            f"Dataset '{dataset}' not found in filename '{filename}'.\n"
+            f"{_naming_hint(dataset)}"
         )
 
-    filters = FILTER_DATABASE[dataset]["filters"]
+    matches = _filters_in_name(stem, dataset)
 
-    for filt in sorted(filters, key=len, reverse=True):
-        if filt.upper() in filename:
-            return filt
+    if not matches:
+        raise ValueError(
+            f"Could not identify the {dataset} filter in filename "
+            f"'{filename}'.\n"
+            f"{_naming_hint(dataset)}"
+        )
 
-    raise ValueError(
-        f"Could not identify filter for dataset '{dataset}' "
-        f"in file '{os.path.basename(fits_file)}'."
-    )
+    if len(matches) > 1:
+        raise ValueError(
+            f"Multiple {dataset} filters found in filename "
+            f"'{filename}': {matches}.\n"
+            f"{_naming_hint(dataset)}"
+        )
+
+    return matches[0]
+
+
+def check_filenames(fits_files, dataset, verbose=True):
+    """
+    Check which FITS filenames follow the naming convention expected by
+    ``identify_filter``, before running the rest of the pipeline.
+
+    Parameters
+    ----------
+    fits_files : iterable of str or pathlib.Path
+        FITS filenames to check.
+    dataset : str
+        Dataset key in ``FILTER_DATABASE``. Matching is case-insensitive.
+    verbose : bool, optional
+        If True, print a report with the identified filter of each file and
+        the reason why the others were not identified.
+
+    Returns
+    -------
+    valid : list of tuple
+        ``(fits_path, filter_name)`` for files whose filter was identified.
+    invalid : list of tuple
+        ``(fits_path, reason)`` for files whose filter was not identified.
+    """
+
+    dataset = dataset.upper()
+
+    if dataset not in FILTER_DATABASE:
+        raise ValueError(
+            f"Unknown dataset '{dataset}'. "
+            f"Available datasets: {list(FILTER_DATABASE)}"
+        )
+
+    valid = []
+    invalid = []
+
+    for fpath in fits_files:
+        try:
+            valid.append((fpath, identify_filter(fpath, dataset)))
+        except ValueError as err:
+            # Keep only the first line; the naming hint is printed once below
+            invalid.append((fpath, str(err).splitlines()[0]))
+
+    if verbose:
+        print(f"{dataset}: {len(valid)} file(s) identified, "
+              f"{len(invalid)} not identified.")
+
+        for fpath, filt in valid:
+            print(f"  OK    {filt:>8s}  {Path(fpath).name}")
+
+        for fpath, reason in invalid:
+            print(f"  FAIL  {Path(fpath).name}: {reason}")
+
+        filters_found = [filt for _, filt in valid]
+        repeated = sorted(
+            {filt for filt in filters_found if filters_found.count(filt) > 1}
+        )
+        if repeated:
+            print(f"  Warning: more than one file for filter(s) {repeated}.")
+
+        if invalid:
+            print(_naming_hint(dataset))
+
+    return valid, invalid
 
 
 def get_filter_info(filter_name, dataset):
@@ -377,10 +538,16 @@ def add_custom_dataset(
                     "lambda": 5500.0,
                     "instrument": "TelescopeCam",
                     "group": "broad",
+                    "aliases": ["FILTER1_ALT"],  # optional
                 },
                 ...
             }
 
+        The optional ``aliases`` list contains alternative names under which
+        the filter may appear in filenames (see ``identify_filter``).
+        Filter names and aliases are matched case-insensitively, so they
+        must be unique within the dataset regardless of case.
+
     overwrite : bool, optional
         If True, overwrite existing dataset.
 
@@ -418,6 +585,26 @@ def add_custom_dataset(
                 f"Filter '{filt}': lambda must be numeric."
             )
 
+        aliases = meta.get("aliases", [])
+
+        if isinstance(aliases, str) or not all(
+            isinstance(alias, str) for alias in aliases
+        ):
+            raise TypeError(
+                f"Filter '{filt}': aliases must be a list of strings."
+            )
+
+    # Filenames are matched case-insensitively, so names must not collide
+    seen = {}
+    for filt, meta in filters.items():
+        for name in [filt, *meta.get("aliases", [])]:
+            if name.upper() in seen and seen[name.upper()] != filt:
+                raise ValueError(
+                    f"Name '{name}' of filter '{filt}' collides with filter "
+                    f"'{seen[name.upper()]}' (names are case-insensitive)."
+                )
+            seen[name.upper()] = filt
+
     FILTER_DATABASE[dataset_name] = {
         "filters": filters
     }
@@ -429,6 +616,12 @@ def simplify_fits_filename(fits_file, dataset):
     Create a simplified FITS filename containing the dataset
     and filter name.
 
+    This is the recommended filename format for ``identify_filter``.
+    Unlike ``identify_filter``, the original filename does not need to
+    contain the dataset name, but the filter name (or one of its
+    ``aliases``) must appear as a separate word, delimited by ``_``, ``-``
+    or ``.`` (case-insensitive).
+
     Parameters
     ----------
     fits_file : str or pathlib.Path
@@ -445,27 +638,27 @@ def simplify_fits_filename(fits_file, dataset):
     fits_file = Path(fits_file)
     dataset = dataset.upper()
 
-    filename = fits_file.name.lower()
-
-    filters = FILTER_DATABASE[dataset]["filters"]
+    if dataset not in FILTER_DATABASE:
+        raise ValueError(
+            f"Unknown dataset '{dataset}'. "
+            f"Available datasets: {list(FILTER_DATABASE)}"
+        )
 
-    matches = [
-        filter_name
-        for filter_name in filters
-        if filter_name.lower() in filename
-    ]
+    matches = _filters_in_name(fits_file.stem, dataset)
 
     if not matches:
         raise ValueError(
             f"Could not identify a filter from filename "
-            f"'{fits_file.name}' for dataset '{dataset}'."
+            f"'{fits_file.name}' for dataset '{dataset}'.\n"
+            f"{_naming_hint(dataset)}"
         )
 
     if len(matches) > 1:
         raise ValueError(
             f"Multiple filters found in filename "
             f"'{fits_file.name}' for dataset '{dataset}': "
-            f"{matches}"
+            f"{matches}.\n"
+            f"{_naming_hint(dataset)}"
         )
 
     filter_name = matches[0]
@@ -824,3 +1017,184 @@ def get_pixel_scale_from_wcs(wcs):
         distortion.
     """
     return proj_plane_pixel_scales(wcs)[0] * 3600.0
+    
+
+def print_fits_spatial_info(fits_files):
+    """
+    Print pixel scale and field of view for a set of FITS images.
+
+    The pixel scale is derived from the FITS WCS using the following
+    hierarchy:
+
+    1. CD matrix
+    2. PC matrix + CDELT
+    3. PC matrix
+    4. CDELT
+
+    Parameters
+    ----------
+    fits_files : list of str or pathlib.Path
+        FITS files to inspect.
+
+    Notes
+    -----
+    Pixel scales are reported in arcsec/pixel and FOVs in arcsec.
+    """
+
+    print(
+        f"{'File':40} "
+        f"{'PixScale X':>12} {'PixScale Y':>12} "
+        f"{'FOV X':>12} {'FOV Y':>12}"
+    )
+
+    print(
+        f"{'':40} "
+        f"{'(arcsec/pix)':>12} {'(arcsec/pix)':>12} "
+        f"{'(arcsec)':>12} {'(arcsec)':>12}"
+    )
+
+    print("-" * 92)
+
+    for fits_file in fits_files:
+
+        fits_file = Path(fits_file)
+
+        with fits.open(fits_file) as hdul:
+
+            ext = find_ext(hdul)
+
+            if ext is None:
+                print(
+                    f"{fits_file.name:40} "
+                    f"{'No image extension':>12}"
+                )
+                continue
+
+            hdr = hdul[ext].header
+            data = hdul[ext].data
+
+            if data is None or data.ndim < 2:
+                print(
+                    f"{fits_file.name:40} "
+                    f"{'Invalid image':>12}"
+                )
+                continue
+
+            ny, nx = data.shape[-2:]
+
+            # CD matrix
+            if all(
+                k in hdr
+                for k in [
+                    "CD1_1",
+                    "CD1_2",
+                    "CD2_1",
+                    "CD2_2",
+                ]
+            ):
+
+                pixscale_x = 3600 * np.sqrt(
+                    hdr["CD1_1"]**2
+                    + hdr["CD2_1"]**2
+                )
+
+                pixscale_y = 3600 * np.sqrt(
+                    hdr["CD1_2"]**2
+                    + hdr["CD2_2"]**2
+                )
+
+            # PC + CDELT
+            elif (
+                all(
+                    k in hdr
+                    for k in [
+                        "PC1_1",
+                        "PC1_2",
+                        "PC2_1",
+                        "PC2_2",
+                    ]
+                )
+                and "CDELT1" in hdr
+                and "CDELT2" in hdr
+            ):
+
+                cd11 = (
+                    hdr["PC1_1"]
+                    * hdr["CDELT1"]
+                )
+
+                cd12 = (
+                    hdr["PC1_2"]
+                    * hdr["CDELT1"]
+                )
+
+                cd21 = (
+                    hdr["PC2_1"]
+                    * hdr["CDELT2"]
+                )
+
+                cd22 = (
+                    hdr["PC2_2"]
+                    * hdr["CDELT2"]
+                )
+
+                pixscale_x = 3600 * np.sqrt(
+                    cd11**2 + cd21**2
+                )
+
+                pixscale_y = 3600 * np.sqrt(
+                    cd12**2 + cd22**2
+                )
+
+            # PC only
+            elif all(
+                k in hdr
+                for k in [
+                    "PC1_1",
+                    "PC1_2",
+                    "PC2_1",
+                    "PC2_2",
+                ]
+            ):
+
+                pixscale_x = 3600 * np.sqrt(
+                    hdr["PC1_1"]**2
+                    + hdr["PC2_1"]**2
+                )
+
+                pixscale_y = 3600 * np.sqrt(
+                    hdr["PC1_2"]**2
+                    + hdr["PC2_2"]**2
+                )
+
+            # CDELT
+            elif (
+                "CDELT1" in hdr
+                and "CDELT2" in hdr
+            ):
+
+                pixscale_x = (
+                    abs(hdr["CDELT1"]) * 3600
+                )
+
+                pixscale_y = (
+                    abs(hdr["CDELT2"]) * 3600
+                )
+
+            # No valid WCS scale
+            else:
+
+                pixscale_x = np.nan
+                pixscale_y = np.nan
+
+            # FOV
+            fov_x = nx * pixscale_x
+            fov_y = ny * pixscale_y
+
+            print(
+                f"{fits_file.name:40} "
+                f"{pixscale_x:12.4f} "
+                f"{pixscale_y:12.4f} "
+                f"{fov_x:12.1f} "
+                f"{fov_y:12.1f}"
+            )

{lightstack-0.3.2 → lightstack-0.4.0/src/lightstack.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: lightstack
-Version: 0.3.2
+Version: 0.4.0
 Summary: Tools for building and processing multi-filter astrophysical datacubes
 Author: Andressa Wille, Thallis Pessi
 License: MIT License
@@ -36,13 +36,13 @@ Requires-Dist: scipy
 Requires-Dist: photutils
 Requires-Dist: pandas
 
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19393438.svg)](https://doi.org/10.5281/zenodo.20360028)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19393438.svg)](https://doi.org/10.5281/zenodo.22148981)
 
 <img src="https://raw.githubusercontent.com/AndressaWille/lightstack/master/images/logo.png" width="120">
 
 # Lightstack
 
-Tools for building and processing multi-filter astrophysical datacubes. 
+Tools for building and processing multi-filter (and multi-servey) astrophysical datacubes. 
 
 ## Features
 
@@ -60,4 +60,4 @@ pip install lightstack
 
 https://lightstack.readthedocs.io/en/latest/
 
-See the tutorial notebook (in the "examples" folder)! 
+See the tutorial notebooks (in the "examples" folder)!