astroimred 0.4.0__py3-none-any.whl

astroimred/__init__.py

@@ -0,0 +1,18 @@
+"""astroimred: astronomical image reduction and FITS utilities."""
+
+from . import _core, external, fitsmgmt, imutil, phot, viz
+from ._core.astropy_helpers import *
+from ._core.geometry import *
+from ._core.numeric import *
+from ._core.scales import *
+from ._core.system import *
+from .fitsmgmt.airmass import *
+from .fitsmgmt.header import *
+from .fitsmgmt.io import *
+from .fitsmgmt.naming import *
+from .fitsmgmt.table import *
+from .fitsmgmt.wcs import *
+from .imutil.ccdops import *
+from .imutil.imstat import *
+from .imutil.pixels import *
+from .logging import enable_console_logging, logger, set_log_level

astroimred/_core/__init__.py

@@ -0,0 +1,9 @@
+"""Low-level helpers shared by astroimred subpackages."""
+
+from .astropy_helpers import *
+from .geometry import *
+from .numeric import *
+from .scales import *
+from .system import *
+from .types import *
+from .wcs import *

astroimred/_core/astropy_helpers.py

@@ -0,0 +1,299 @@
+"""Small helpers built around Astropy units, modeling, and visualization."""
+
+import copy
+
+import numpy as np
+from astropy import units as u
+from astropy.modeling.fitting import LevMarLSQFitter
+from astropy.modeling.functional_models import Gaussian2D
+from astropy.time import Time
+from astropy.visualization import (
+    AsinhStretch,
+    AsymmetricPercentileInterval,
+    BaseInterval,
+    BaseStretch,
+    LinearStretch,
+    LogStretch,
+    PercentileInterval,
+    PowerStretch,
+    SinhStretch,
+    SqrtStretch,
+    SquaredStretch,
+    ZScaleInterval,
+)
+
+from .numeric import normalize
+
+__all__ = [
+    "as_quantity",
+    "str_now",
+    "parse_stretch",
+    "parse_interval",
+    "Gaussian2D_correct",
+    "fit_astropy_model",
+    "fit_Gaussian2D",
+    "gaussian_kernel",
+]
+
+_STRETCH_CLASS_MAP: dict[str, type[BaseStretch]] = {
+    "linear": LinearStretch,
+    "sqrt": SqrtStretch,
+    "asinh": AsinhStretch,
+    "log": LogStretch,
+    "power": PowerStretch,
+    "sinh": SinhStretch,
+    "square": SquaredStretch,
+    "squared": SquaredStretch,
+}
+
+_STRETCH_DEFAULTS: dict[str, dict[str, float]] = {
+    "asinh": {"a": 0.1},
+    "log": {"a": 1000.0},
+    "power": {"a": 1.0},
+    "sinh": {"a": 0.3},
+}
+
+
+def as_quantity(
+    value: object,
+    unit: str | u.Unit = "",
+    to_value: bool = False,
+) -> u.Quantity | object:
+    """Convert an object to an Astropy Quantity or scalar in the requested unit.
+
+    Non-Quantity inputs are multiplied by ``unit`` unless ``to_value=True``.
+    Objects that cannot be multiplied by a unit are copied and returned as-is.
+    """
+    if value is None:
+        return None
+
+    try:
+        return value.to(unit).value if to_value else value.to(unit)
+    except AttributeError:
+        if to_value:
+            return _copy(value)
+        if isinstance(unit, str):
+            unit = u.Unit(unit)
+        try:
+            return value * unit
+        except TypeError:
+            return _copy(value)
+    except TypeError:
+        return _copy(value)
+    except u.UnitConversionError as err:
+        raise ValueError(
+            "If you use astropy.Quantity, you should use unit convertible to `unit`."
+            + f'\nYou gave "{value.unit}", unconvertible with "{unit}".'
+        ) from err
+
+
+def _copy(x: object) -> object:
+    try:
+        return x.copy()
+    except AttributeError:
+        return copy.deepcopy(x)
+
+
+def str_now(
+    precision: int = 3,
+    fmt: str = "{:.>72s}",
+    t_ref: Time | None = None,
+    dt_fmt: str = "(dt = {:.3f} s)",
+    return_time: bool = False,
+) -> str | tuple:
+    """Get stringified time now in UT ISOT format.
+
+    Parameters
+    ----------
+    precision : `int`, optional.
+        The precision of the isot format time.
+        Default: ``3``.
+
+    fmt : `str`, optional.
+        The Python 3 format string to format the time. Examples::
+
+          * ``"{:s}"``: plain time ``2020-01-01T01:01:01.23``
+          * ``"({:s})"``: plain time in parentheses ``(2020-01-01T01:01:01.23)``
+          * ``"{:_^72s}"``: center align, filling with _.
+        Default: ``'{:.>72s}'``.
+
+    t_ref : `~astropy.time.Time`, optional.
+        The reference time. If not `None`, delta time is calculated.
+        Default: `None`.
+
+    dt_fmt : `str`, optional.
+        The Python 3 format string to format the delta time.
+        Default: ``'(dt = {:.3f} s)'``.
+
+    return_time : `bool`, optional.
+        Whether to return the time at the start of this function and the delta
+        time (`dt`), as well as the time information string. If `t_ref` is
+        `None`, `dt` is automatically set to `None`.
+        Default: `False`.
+    """
+    now = Time(Time.now(), precision=precision)
+    timestr = now.isot
+    if t_ref is not None:
+        dt = (now - Time(t_ref)).sec
+        timestr = dt_fmt.format(dt) + " " + timestr
+    else:
+        dt = None
+
+    if return_time:
+        return fmt.format(timestr), now, dt
+    return fmt.format(timestr)
+
+
+def parse_stretch(
+    stretch: str | BaseStretch,
+    *,
+    asinh_a: float | None = None,
+    log_a: float | None = None,
+    power: float | None = None,
+    sinh_a: float | None = None,
+    **kwargs: object,
+) -> BaseStretch:
+    """Resolve a stretch specification to an Astropy stretch instance.
+
+    Accepts a `~astropy.visualization.BaseStretch` instance, bare names such as
+    `"sqrt"`, and full class-style names such as `"SqrtStretch"`. Extra
+    keyword arguments are forwarded to the stretch class constructor.
+    Named tuning parameters (`asinh_a`, `log_a`, `power`, `sinh_a`) override
+    the package defaults for the corresponding stretches.
+    """
+    if isinstance(stretch, BaseStretch):
+        return stretch
+
+    key = stretch.strip().lower()
+    if key.endswith("stretch"):
+        key = key[: -len("stretch")]
+    if key not in _STRETCH_CLASS_MAP:
+        supported = ", ".join(sorted(_STRETCH_CLASS_MAP))
+        raise ValueError(f"Unknown stretch {stretch!r}. Supported names: {supported}")
+
+    params = {**_STRETCH_DEFAULTS.get(key, {})}
+    if key == "asinh" and asinh_a is not None:
+        params["a"] = asinh_a
+    elif key == "log" and log_a is not None:
+        params["a"] = log_a
+    elif key == "power" and power is not None:
+        params["a"] = power
+    elif key == "sinh" and sinh_a is not None:
+        params["a"] = sinh_a
+    params.update(kwargs)
+    return _STRETCH_CLASS_MAP[key](**params)
+
+
+def parse_interval(
+    interval: str | BaseInterval | None = None,
+    *,
+    percent: float | None = None,
+    min_percent: float | None = None,
+    max_percent: float | None = None,
+) -> BaseInterval | None:
+    """Resolve an interval specification to an Astropy interval instance.
+
+    Accepts a `~astropy.visualization.BaseInterval` instance, `"zscale"`,
+    `percent`, or asymmetric `min_percent`/`max_percent` bounds. Returns
+    `None` when no interval shortcut is requested.
+    """
+    if isinstance(interval, str):
+        if interval.lower() == "zscale":
+            return ZScaleInterval()
+        raise ValueError(
+            f"Unknown interval string {interval!r}. "
+            "Use 'zscale' or a BaseInterval instance."
+        )
+
+    if interval is not None:
+        return interval
+
+    if percent is not None:
+        return PercentileInterval(percent)
+
+    if min_percent is not None or max_percent is not None:
+        lo = min_percent if min_percent is not None else 0.0
+        hi = max_percent if max_percent is not None else 100.0
+        return AsymmetricPercentileInterval(lo, hi)
+
+    return None
+
+
+def Gaussian2D_correct(
+    model, theta_lower: float = -np.pi / 2, theta_upper: float = np.pi / 2
+):
+    """Return a Gaussian2D-like model with x as semimajor axis.
+
+    The returned copy has positive ``x_stddev``/``y_stddev``, ``x_stddev`` as
+    the semimajor-axis sigma, and ``theta`` normalized into the requested
+    interval.
+    """
+    new_model = model.copy()
+    sig_x = np.abs(model.x_stddev.value)
+    sig_y = np.abs(model.y_stddev.value)
+    theta = model.theta.value
+
+    if sig_x > sig_y:
+        theta_norm = normalize(theta, theta_lower, theta_upper)
+        new_model.x_stddev.value = sig_x
+        new_model.y_stddev.value = sig_y
+        new_model.theta.value = theta_norm
+    else:
+        theta_norm = normalize(theta + np.pi / 2, theta_lower, theta_upper)
+        new_model.x_stddev.value = sig_y
+        new_model.y_stddev.value = sig_x
+        new_model.theta.value = theta_norm
+
+    return new_model
+
+
+def fit_astropy_model(data, model_init, sigma=None, fitter=None, **kwargs):
+    """Fit an Astropy 2D model to image data.
+
+    ``sigma`` is interpreted as per-pixel 1-sigma uncertainty and passed to
+    Astropy as ``weights=1/sigma``.
+    """
+    yy, xx = np.mgrid[: data.shape[0], : data.shape[1]]
+    weights = 1 / sigma if sigma is not None else None
+    if fitter is None:
+        fitter = LevMarLSQFitter()
+    fitted = fitter(model_init, xx, yy, data, weights=weights, **kwargs)
+    return fitted, fitter
+
+
+def fit_Gaussian2D(data, model_init, correct=True, sigma=None, fitter=None, **kwargs):
+    """Fit a Gaussian2D-like Astropy model and optionally normalize orientation."""
+    fitted, fitter = fit_astropy_model(
+        data=data, model_init=model_init, sigma=sigma, fitter=fitter, **kwargs
+    )
+    if correct:
+        fitted = Gaussian2D_correct(fitted)
+    return fitted, fitter
+
+
+def gaussian_kernel(fwhm=None, sigma=None, theta=0, nsigma=5, normalize_area=False):
+    """Generate a 2D Gaussian kernel array.
+
+    Exactly one of ``fwhm`` and ``sigma`` must be supplied. Scalar widths are
+    applied to both axes; two-element widths are interpreted as ``(x, y)``.
+    """
+    if ((fwhm is None) + (sigma is None)) != 1:
+        raise ValueError("One and only one of `fwhm` and `sigma` should be given.")
+    elif fwhm is not None:
+        sigma = fwhm / (2 * np.sqrt(2 * np.log(2)))
+    sigma = np.atleast_1d(sigma)
+    if len(sigma) == 1:
+        sigma = np.repeat(sigma, 2)
+    amp = 1 / (2 * np.pi * sigma[0] * sigma[1]) if normalize_area else 1
+    gauss = Gaussian2D(
+        amplitude=amp,
+        x_mean=0,
+        y_mean=0,
+        x_stddev=sigma[0],
+        y_stddev=sigma[1],
+        theta=theta,
+    )
+    shape = np.ceil(nsigma * sigma[::-1]).astype(int)
+    return gauss(
+        *np.ogrid[-shape[0] / 2 : shape[0] / 2 + 1, -shape[1] / 2 : shape[1] / 2 + 1]
+    )

astroimred/_core/geometry.py

@@ -0,0 +1,268 @@
+"""
+Objects that are
+(1) too fundamental, so used in various places,
+(2) completely INDEPENDENT of all other modules of this package.
+"""
+
+import numpy as np
+from astro_ndslice import listify as listify  # noqa: F401
+
+_numba_available = False
+try:
+    import importlib.util as _ilu
+
+    _numba_available = _ilu.find_spec("numba") is not None
+except Exception:
+    pass
+
+__all__ = [
+    "sigclip_dataerr",
+    "circular_mask",
+    "enclosing_circle_radius",
+    "mask_enclosing_circle_radius",
+    "bezel_mask",
+]
+
+
+# !FIXME: not finished
+# TODO: add err_lower, err_upper, sigma_lower, sigma_upper
+def sigclip_dataerr(
+    val: np.ndarray,
+    err: np.ndarray,
+    cenfunc: str = "wvg",
+    sigma: float = 3,
+    maxiters: int = 3,
+) -> tuple[np.ma.MaskedArray, np.ndarray]:
+    """Sigma-clip values using per-point error estimates.
+
+    Parameters
+    ----------
+    val, err : array-like
+        Values and corresponding 1-sigma errors.
+
+    cenfunc : {"wvg", "avg", "average", "mean"}, optional
+        Center estimator. ``"wvg"`` uses weighted average.
+
+    sigma : float, optional
+        Rejection threshold in units of `err`.
+
+    maxiters : int, optional
+        Maximum clipping iterations.
+    """
+    if cenfunc == "wvg":
+        from .._core.numeric import wvg
+
+        def cenfunc(val, err):
+            return wvg(val, err=err)
+    elif cenfunc in ["avg", "average", "mean"]:
+
+        def cenfunc(val, err):
+            return np.mean(val)[0]  # err is dummy
+    else:
+        raise ValueError(f"{cenfunc=} is not implemented yet.")
+
+    val = np.ma.array(val)
+    val_clipped = val.compressed()
+    err_clipped = err[val.mask]
+    cen = cenfunc(val_clipped, err_clipped)
+
+    for _i in range(maxiters):
+        # calculate deviation for all (even masked) elements:
+        deviation = np.abs(val.data - cen)
+        mask = deviation > sigma * err
+
+    return val, mask
+
+
+def circular_mask(
+    shape: tuple[int, ...],
+    center: tuple | None = None,
+    radius: float | None = None,
+    center_xyz: bool = True,
+) -> np.ndarray:
+    """Creates an N-D circular (circular, spherical, ...) mask.
+
+    Parameters
+    ----------
+    shape : `tuple`
+        The pythonic shape, i.e., `arr.shape` (not xyz order).
+
+    center : `tuple`, `None`, optional.
+        The center of the circular mask. If `None` (default), the central
+        position is used.
+        Default: `None`.
+
+    radius : `float`, `None`, optional.
+        The radius of the mask. If `None`, the distance to the closest edge of
+        the image is used.
+        Default: `None`.
+
+    center_xyz : `bool`, optional.
+        Whether the center is in xyz order.
+        Default: `True`.
+
+    Notes
+    -----
+    Idea copied from
+    https://stackoverflow.com/questions/44865023/how-can-i-create-a-circular-mask-for-a-numpy-array
+
+    Note that this is slow due to the "general" N-D nature of the mask.
+    If you need an aperture-style 2-D mask, use ``astroapers.CircAp``.
+    """
+    if center is None:  # use the middle of the image
+        center = [npix / 2 for npix in shape[::-1]]
+
+    if center_xyz:
+        center = center[::-1]
+
+    shape = np.array(shape)
+    center = np.array(center)
+
+    if radius is None:  # use the smallest distance between the center and image walls
+        radius = np.min([center, shape - center])
+
+    slices = tuple([slice(None, npix, None) for npix in shape])
+
+    zyx = np.ogrid[slices]
+    dist_sq = [((zyx[i] - center[i]) ** 2) for i in range(len(shape))]
+    dist_from_center = np.sqrt(np.sum(np.array(dist_sq, dtype=object)))
+
+    mask = dist_from_center <= radius
+    return mask
+
+
+def _enclosing_circle_radius_numpy(segm, center, segm_id, output):
+    for i in range(len(segm_id)):
+        _segm_id = segm_id[i]
+        mask = segm == _segm_id
+        y, x = np.nonzero(mask)
+        rsq_max = np.max((x - center[i][0]) ** 2 + (y - center[i][1]) ** 2)
+        output[i] = np.sqrt(rsq_max)
+
+
+_enclosing_circle_radius_nb = None
+
+
+def _get_enclosing_circle_radius_nb():
+    global _enclosing_circle_radius_nb
+    if _enclosing_circle_radius_nb is None:
+        import numba as nb
+
+        @nb.njit(fastmath=False, parallel=True)
+        def _kernel(segm, center, segm_id, output):
+            for i in nb.prange(len(segm_id)):
+                _segm_id = segm_id[i]
+                mask = segm == _segm_id
+                y, x = np.nonzero(mask)
+                rsq_max = np.max((x - center[i][0]) ** 2 + (y - center[i][1]) ** 2)
+                output[i] = np.sqrt(rsq_max)
+
+        _enclosing_circle_radius_nb = _kernel
+    return _enclosing_circle_radius_nb
+
+
+def enclosing_circle_radius(
+    segm: np.ndarray,
+    center: np.ndarray,
+    segm_id: np.ndarray | None = None,
+) -> np.ndarray:
+    """
+    Calculate the radius of the smallest enclosing circle for a given mask.
+
+    Parameters
+    ----------
+    segm : 2D array-like
+        The input segmentation map (binary image) where non-zero values are
+        considered as the region of interest.
+
+    center : 2-D array, optional
+        The (x, y) coordinates of the center of the circles. If not provided,
+        the center will be calculated as the centroid of the masked region.
+
+    segm_id : `list` of `int`, optional
+        The `list` of segmentation IDs to calculate the radius for. If not provided,
+        it defaults to `[1]`, which is equivalent to `True` for binary masks.
+        Default: `None`.
+
+    Returns
+    -------
+    `~numpy.ndarray`
+        The radius of the smallest enclosing circle.
+
+    Notes
+    -----
+    Since it calculates distances from the center to the pixel center, one may
+    want to add ~0.5 (or sqrt(2)*0.5) to enclose the full pixel area.
+
+    By using numba, single segmentation radius finding is ~5 times faster than
+    pure numpy, and it is boosted further if `parallel=True` is used.
+    """
+
+    if segm_id is None:
+        segm_id = np.array([1], dtype=segm.dtype)  # same as `True`
+
+    center = np.atleast_2d(center)
+    if center.shape[1] != 2:
+        raise ValueError("Center must be a 2D array with shape (N, 2)")
+
+    radii = np.empty(len(segm_id), dtype=np.float64)
+
+    if _numba_available:
+        _get_enclosing_circle_radius_nb()(segm, center, segm_id, radii)
+    else:
+        _enclosing_circle_radius_numpy(segm, center, segm_id, radii)
+
+    return radii
+
+
+def mask_enclosing_circle_radius(
+    mask: np.ndarray,
+    center: tuple[float, float] | None = None,
+) -> float:
+    """Return the radius enclosing all non-zero pixels in a binary mask."""
+    y, x = np.nonzero(mask)
+
+    if len(x) == 0 or len(y) == 0:
+        return 0.0
+
+    if center is None:
+        center = (float(np.mean(x)), float(np.mean(y)))
+
+    distances = np.sqrt((x - center[0]) ** 2 + (y - center[1]) ** 2)
+    return float(np.max(distances))
+
+
+def bezel_mask(
+    xvals,
+    yvals,
+    nx,
+    ny,
+    bezel=(0, 0),
+    bezel_x=None,
+    bezel_y=None,
+) -> np.ndarray:
+    """Return mask for positions inside the image border bezel."""
+    bezel = np.array(bezel)
+    if len(bezel) == 1:
+        bezel = np.repeat(bezel, 2)
+
+    if bezel_x is None:
+        bezel_x = bezel.copy()
+    else:
+        bezel_x = np.atleast_1d(bezel_x)
+        if len(bezel_x) == 1:
+            bezel_x = np.repeat(bezel_x, 2)
+
+    if bezel_y is None:
+        bezel_y = bezel.copy()
+    else:
+        bezel_y = np.atleast_1d(bezel_y)
+        if len(bezel_y) == 1:
+            bezel_y = np.repeat(bezel_y, 2)
+
+    return (
+        (xvals < bezel_x[0] + 0.5)
+        | (yvals < bezel_y[0] + 0.5)
+        | (xvals > (nx - bezel_x[1]) - 0.5)
+        | (yvals > (ny - bezel_y[1]) - 0.5)
+    )