pandoraaperture 0.1.0__tar.gz

pandoraaperture-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pandora Data Processing Center
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pandoraaperture-0.1.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: pandoraaperture
+Version: 0.1.0
+Summary: 
+License-File: LICENSE
+Author: Christina Hedges
+Author-email: christina.l.hedges@nasa.gov
+Requires-Python: >=3.9,<3.13
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: appdirs (>=1.4.4,<2.0.0)
+Requires-Dist: astropy (>=6.0.1)
+Requires-Dist: gaiaoffline (>=1.0.3,<2.0.0)
+Requires-Dist: matplotlib (>=2.0.0)
+Requires-Dist: numpy (>=1.2)
+Requires-Dist: pandas (>=2.2.3,<3.0.0)
+Requires-Dist: pandoraref (>=0.3.0)
+Requires-Dist: rich (>=13.9.4,<14.0.0)
+Requires-Dist: sparse3d (>=1.2.10)
+Description-Content-Type: text/markdown
+
+<a href="https://github.com/pandoramission/pandora-aperture/actions/workflows/black.yml"><img src="https://github.com/pandoramission/pandora-aperture/workflows/black/badge.svg" alt="black status"/></a> <a href="https://github.com/pandoramission/pandora-aperture/actions/workflows/flake8.yml"><img src="https://github.com/pandoramission/pandora-aperture/workflows/flake8/badge.svg" alt="flake8 status"/></a> [![Generic badge](https://img.shields.io/badge/documentation-live-blue.svg)](https://pandoramission.github.io/pandora-aperture/)
+[![PyPI - Version](https://img.shields.io/pypi/v/pandoraaperture)](https://pypi.org/project/pandoraaperture/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pandoraaperture)](https://pypi.org/project/pandoraaperture/)
+
+# Pandora Aperture
+
+## Installation
+
+To install you can use
+
+```sh
+pip install pandoraaperture --upgrade
+```
+
+You should update your package often, as we frequently put out new versions with updated Current Best Estimates, and some limited new functionality. Check your version number using
+
+```python
+import pandoraaperture as pa
+pa.__version__
+```
+

pandoraaperture-0.1.0/docs/README.md

@@ -0,0 +1,20 @@
+<a href="https://github.com/pandoramission/pandora-aperture/actions/workflows/black.yml"><img src="https://github.com/pandoramission/pandora-aperture/workflows/black/badge.svg" alt="black status"/></a> <a href="https://github.com/pandoramission/pandora-aperture/actions/workflows/flake8.yml"><img src="https://github.com/pandoramission/pandora-aperture/workflows/flake8/badge.svg" alt="flake8 status"/></a> [![Generic badge](https://img.shields.io/badge/documentation-live-blue.svg)](https://pandoramission.github.io/pandora-aperture/)
+[![PyPI - Version](https://img.shields.io/pypi/v/pandoraaperture)](https://pypi.org/project/pandoraaperture/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pandoraaperture)](https://pypi.org/project/pandoraaperture/)
+
+# Pandora Aperture
+
+## Installation
+
+To install you can use
+
+```sh
+pip install pandoraaperture --upgrade
+```
+
+You should update your package often, as we frequently put out new versions with updated Current Best Estimates, and some limited new functionality. Check your version number using
+
+```python
+import pandoraaperture as pa
+pa.__version__
+```

pandoraaperture-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "pandoraaperture"
+version = "0.1.0"
+description = ""
+authors = [
+    {name = "Christina Hedges",email = "christina.l.hedges@nasa.gov"}
+]
+readme = "docs/README.md"
+requires-python =  ">=3.9,<3.13"
+dependencies = [
+    "rich (>=13.9.4,<14.0.0)",
+    "numpy (>=1.2)",
+    "pandas (>=2.2.3,<3.0.0)",
+    "appdirs (>=1.4.4,<2.0.0)",
+    "sparse3d (>=1.2.10)",
+    "matplotlib (>=2.0.0)",
+    "astropy (>=6.0.1)",
+    "gaiaoffline (>=1.0.3,<2.0.0)",
+    "pandoraref (>=0.3.0)"
+]
+
+[tool.poetry]
+packages = [{include = "pandoraaperture", from = "src"}]
+
+[tool.poetry.group.dev]
+optional = true
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.4"
+black = "^25.1.0"
+isort = "^6.0.0"
+flake8 = "^7.1.2"
+jupyterlab = "^4.3.5"
+mkdocs = "^1.6.1"
+mkdocs-jupyter = "^0.25.1"
+mkdocs-material = "^9.6.5"
+pytkdocs = {version = "^0.16.2", extras = ["numpy-style"]}
+mkdocs-include-markdown-plugin = "^7.1.4"
+mkdocstrings = {version = "^0.28.2", extras = ["python"]}
+jupyter-contrib-nbextensions = "^0.7.0"
+notebook = ">=6.0.0,<7.0.0"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+line-length = 79
+
+[tool.isort]
+import_heading_firstparty = 'First-party/Local'
+import_heading_future = 'Future'
+import_heading_stdlib = 'Standard library'
+import_heading_thirdparty = 'Third-party'
+line_length = 79
+multi_line_output = 3
+no_lines_before = 'LOCALFOLDER'
+profile = 'black'

pandoraaperture-0.1.0/src/pandoraaperture/__init__.py

@@ -0,0 +1,149 @@
+# Standard library
+import logging  # noqa: E402
+import os  # noqa
+from glob import glob
+
+# Third-party
+from rich.console import Console  # noqa: E402
+from rich.logging import RichHandler  # noqa: E402
+
+PACKAGEDIR = os.path.abspath(os.path.dirname(__file__))
+DOCSDIR = "/".join(PACKAGEDIR.split("/")[:-2]) + "/docs/"
+TESTDIR = "/".join(PACKAGEDIR.split("/")[:-2]) + "/tests/"
+PANDORASTYLE = glob(f"{PACKAGEDIR}/data/pandora.mplstyle")
+
+# Standard library
+import configparser  # noqa: E402
+from importlib.metadata import PackageNotFoundError, version  # noqa
+
+# Third-party
+import numpy as np  # noqa: E402
+import pandas as pd  # noqa: E402
+import pandoraref as pr  # noqa: E402
+from appdirs import user_config_dir, user_data_dir  # noqa: E402
+
+
+def get_version():
+    try:
+        return version("pandoraaperture")
+    except PackageNotFoundError:
+        return "unknown"
+
+
+__version__ = get_version()
+
+
+# Custom Logger with Rich
+class PandoraLogger(logging.Logger):
+    def __init__(self, name, level=logging.INFO):
+        super().__init__(name, level)
+        console = Console()
+        self.handler = RichHandler(
+            show_time=False, show_level=False, show_path=False, console=console
+        )
+        self.handler.setFormatter(
+            logging.Formatter(
+                "%(asctime)s %(levelname)s: %(message)s",
+                datefmt="%Y-%m-%d %H:%M:%S",
+            )
+        )
+        self.addHandler(self.handler)
+
+
+def get_logger(name="pandoraaperture"):
+    """Configure and return a logger with RichHandler."""
+    return PandoraLogger(name)
+
+
+CONFIGDIR = user_config_dir("pandoraaperture")
+os.makedirs(CONFIGDIR, exist_ok=True)
+CONFIGPATH = os.path.join(CONFIGDIR, "config.ini")
+
+logger = get_logger("pandoraaperture")
+
+
+def reset_config():
+    """Set the config to defaults."""
+    # use this function to set your default configuration parameters.
+    config = configparser.ConfigParser()
+    config["SETTINGS"] = {
+        "log_level": "WARNING",
+        "data_dir": user_data_dir("pandoraaperture"),
+        "pixel_buffer": 15,
+        "catalog_columns": "source_id, phot_g_mean_flux, phot_bp_mean_flux, phot_rp_mean_flux, j_flux, h_flux, k_flux, teff_gspphot",
+    }
+    with open(CONFIGPATH, "w") as configfile:
+        config.write(configfile)
+
+
+def load_config() -> configparser.ConfigParser:
+    """
+    Loads the configuration file, creating it with defaults if it doesn't exist.
+
+    Returns
+    -------
+    configparser.ConfigParser
+        The loaded configuration.
+    """
+
+    config = configparser.ConfigParser()
+
+    if not os.path.exists(CONFIGPATH):
+        # Create default configuration
+        reset_config()
+    config.read(CONFIGPATH)
+    return config
+
+
+def save_config(config: configparser.ConfigParser) -> None:
+    """
+    Saves the configuration to the file.
+
+    Parameters
+    ----------
+    config : configparser.ConfigParser
+        The configuration to save.
+    app_name : str
+        Name of the application.
+    """
+    with open(CONFIGPATH, "w") as configfile:
+        config.write(configfile)
+
+
+config = load_config()
+
+# Use this to check that keys you expect are in the config file.
+# If you update the config file and think users may be out of date
+# add the config parameters to this loop to check and reset the config.
+for key in ["data_dir", "log_level"]:
+    if key not in config["SETTINGS"]:
+        logger.error(
+            f"`{key}` missing from the `pandoraaperture` config file. Your configuration is being reset."
+        )
+        reset_config()
+        config = load_config()
+
+DATADIR = config["SETTINGS"]["data_dir"]
+logger.setLevel(config["SETTINGS"]["log_level"])
+
+
+def display_config() -> pd.DataFrame:
+    dfs = []
+    for section in config.sections():
+        df = pd.DataFrame(
+            np.asarray(
+                [(key, value) for key, value in dict(config[section]).items()]
+            )
+        )
+        df["section"] = section
+        df.columns = ["key", "value", "section"]
+        df = df.set_index(["section", "key"])
+        dfs.append(df)
+    return pd.concat(dfs)
+
+
+NIRDAReference = pr.NIRDAReference()
+VISDAReference = pr.VISDAReference()
+
+from .prf import PRF, DispersedPRF, SpatialPRF  # noqa: E402,F401
+from .scene import DispersedSkyScene, ROISkyScene, SkyScene  # noqa: E402,F401

pandoraaperture-0.1.0/src/pandoraaperture/data/pandora.mplstyle

@@ -0,0 +1,71 @@
+lines.color:     C0                # has no affect on plot(); see axes.prop_cycle
+lines.linewidth  : 0.8
+lines.markersize : 1.5
+figure.facecolor : white
+figure.edgecolor:   white     # figure edge color
+figure.dpi       : 150
+figure.titlesize:   x-large     # size of the figure title (``Figure.suptitle()``)
+figure.autolayout: True  # When True, automatically adjust subplot
+                           # parameters to make the plot fit the figure
+                           # using `tight_layout`
+image.origin:          lower        # {lower, upper}
+text.color : 000000
+axes.spines.top   : False
+axes.spines.right : False
+axes.titlepad   : 10
+axes.titlesize  : x-large
+axes.facecolor  : white
+axes.edgecolor  : 000000
+axes.labelcolor : 000000
+axes.labelsize  : large
+axes.linewidth  : 1.25
+axes.prop_cycle : cycler('color', ['000000', '0072B2', '009E73', 'D55E00', 'CC79A7', 'F0E442', '56B4E9'])
+axes.formatter.use_mathtext: True  # When True, use mathtext for scientific
+                                     # notation.
+axes.formatter.min_exponent: 1  # minimum exponent to format in scientific notation
+axes.formatter.useoffset: True  # If True, the tick label formatter
+                                 # will default to labeling ticks relative
+                                 # to an offset when the data range is
+                                 # small compared to the minimum absolute
+                                 # value of the data.
+axes.formatter.offset_threshold: 4  # When useoffset is True, the offset
+                                     # will be used when it can remove
+                                     # at least this number of significant
+                                     # digits from tick labels.
+
+axes.unicode_minus: True  # use Unicode for the minus symbol rather than hyphen.  See
+                           # https://en.wikipedia.org/wiki/Plus_and_minus_signs#Character_codes
+axes.labelpad:      7.0
+errorbar.capsize: 3
+legend.fontsize      : medium
+legend.frameon       : True
+legend.numpoints     : 3
+legend.scatterpoints : 3
+legend.facecolor     : inherit
+legend.edgecolor     : 000000
+legend.framealpha:    0.9
+legend.handlelength:  2.5  # the length of the legend lines
+
+
+savefig.dpi:       150      # figure dots per inch or 'figure'
+savefig.bbox:      tight    # {tight, standard}
+
+grid.linestyle: --
+
+xtick.top           : False
+xtick.color         : 666666
+xtick.labelcolor    : 000000
+xtick.direction     : in
+xtick.major.size    : 8
+xtick.minor.size    : 4
+xtick.minor.visible : True
+xtick.labelsize     : medium
+
+ytick.minor.visible : True
+ytick.right         : False
+ytick.color         : 666666
+ytick.labelcolor    : 000000
+ytick.direction     : in
+ytick.major.size    : 8
+ytick.minor.size    : 4
+ytick.labelsize     : medium

pandoraaperture-0.1.0/src/pandoraaperture/docstrings.py

@@ -0,0 +1,239 @@
+# Standard library
+import functools
+
+# Third-party
+import astropy.units as u
+import numpy.typing as npt
+import pandas as pd
+from astropy.coordinates import SkyCoord
+from astropy.time import Time
+from astropy.wcs import WCS
+from scipy.interpolate import RectBivariateSpline
+from sparse3d import Sparse3D
+
+DOCSTRINGS = {
+    "name": (str, "Name of detector, choose from VISDA or NIRDA."),
+    "delta_pos": (
+        tuple,
+        "Change in position in pixels. Use format (row, column).",
+    ),
+    "file": (
+        str,
+        "Input file to use. Choose either a string path to the file or an `astropy.fits.HDUList` object",
+    ),
+    "flux": (
+        npt.NDArray,
+        "Array of the flux of the PRF as a function of position. Usually normalized such that the total flux is 1.",
+    ),
+    "gradients": (
+        bool,
+        "Whether to return gradients. If True, will return an additional 2 arrays that contain the gradients in each axis.",
+    ),
+    "pixel_size": (
+        u.Quantity,
+        "True detector pixel size in dimensions of length/pixel",
+    ),
+    "sub_pixel_size": (
+        u.Quantity,
+        "PSF file pixel size in dimensions of length/pixel",
+    ),
+    "scale": (
+        float,
+        "How much to scale the PRF by. Scale of 2 makes the PSF 2x broader. Default is 1.",
+    ),
+    "imshape": (
+        tuple,
+        "Tuple of the shape of the true image. "
+        "If using ROIs, use the shape of the image that "
+        "each ROI is cut out from. Use format (row, column).",
+    ),
+    "imcorner": (
+        tuple,
+        "Tuple of the lower left corner of the image, i.e. it's origin. "
+        "Use this to move the image around on the grid. If using a window mode,"
+        " make sure to set this to the right corner. Use format (row, column).",
+    ),
+    "location": (
+        tuple,
+        "Location of the source on the detector. Use format (row, column). "
+        "If not set will default to `self._default_location` which is in the "
+        "middle of the image as set by `imshape` and `imcorner`.",
+    ),
+    "spline": (RectBivariateSpline, "A spline model describing the PRF."),
+    "normalize": (
+        bool,
+        "Whether to normalize the input data so that the total flux is 1.",
+    ),
+    "row_im": (
+        npt.NDArray,
+        "1D Array of integer row values at which the PRF is evaluated.",
+    ),
+    "column_im": (
+        npt.NDArray,
+        "1D Array of integer column values at which the PRF is evaluated.",
+    ),
+    "prf_im": (
+        npt.NDArray,
+        "2D Array of PRF values.",
+    ),
+    "dprf_im": (
+        npt.NDArray,
+        "2, 2D arrays of the gradient of the PRF values. Only returned if `gradients`=True.",
+    ),
+    "X": (Sparse3D, "Sparse3D object containing the PRF at a given location."),
+    "dX0": (
+        Sparse3D,
+        "Sparse3D object containing the gradient of the PRF in axis 0"
+        " at a given location. Only returned if `gradients`=True.",
+    ),
+    "dX1": (
+        Sparse3D,
+        "Sparse3D object containing the gradient of the PRF in axis 1"
+        " at a given location. Only returned if `gradients`=True.",
+    ),
+    "focal_row": (
+        u.Quantity,
+        "Row position on the focal plane that corresponds to each element in the flux array. Units of pixels.",
+    ),
+    "focal_column": (
+        u.Quantity,
+        "Column position on the focal plane that corresponds to each element in the flux array. Units of pixels.",
+    ),
+    "trace_row": (
+        u.Quantity,
+        "Row position within the spectral trace that corresponds to each element in the flux array. Units of pixels.",
+    ),
+    "trace_column": (
+        u.Quantity,
+        "Column position within the spectral trace that corresponds to each element in the flux array. Units of pixels.",
+    ),
+    "prf": ("PRF", "pandoraaperture PRF class."),
+    "wcs": (WCS, "astropy World Coordinate System"),
+    "time": (Time, "astropy Time"),
+    "user_cat": (
+        pd.DataFrame,
+        "Optional catalog from the user. Use this to pass a catalog of objects expected in this"
+        " data that are not part of the Gaia catalog. You must include all the columns "
+        "specified in your config file under `catalog_columns`.",
+    ),
+    "nROIs": (int, "The number of regions of interest in the larger image"),
+    "ROI_size": (
+        tuple,
+        "The size the regions of interest in (row, column) pixels. All ROIs must be the same size.",
+    ),
+    "ROI_corners": (
+        list,
+        "The origin (lower left) corner positon for each of the ROIs. Must have length nROIs. List of tuples.",
+    ),
+    "cat": (
+        pd.DataFrame,
+        "Catalog of sources that will land within the image.",
+    ),
+    "coord": (SkyCoord, "Coordinate in the sky."),
+    "radius": (u.Quantity, "A radius in degrees for a cone search."),
+    "A": (
+        Sparse3D,
+        "Matrix containing the PRFs of all targets in the scene. ",
+    ),
+    "target": (
+        int,
+        "Indicates a target in the catalog. Use either in integer to express "
+        "an index in the catalog, or a SkyCoord to find the closest target",
+    ),
+    "threshold": (
+        float,
+        "Threshold to cut aperture off at, in units of electrons/s.",
+    ),
+    "ra": (u.Quantity, "Right Ascention"),
+    "dec": (u.Quantity, "Declination"),
+    "theta": (u.Quantity, "Roll angle in degrees"),
+    "pixel_resolution": (
+        float,
+        "The separation between different elements in the PRF model in pixels. For example 0.25"
+        " means there will be approximately 0.25 pixels between each element.",
+    ),
+}
+
+
+def extract_docstring_type(dtype, desc):
+    if isinstance(dtype, tuple):
+        dtype_str = " or ".join(
+            [t._name if hasattr(t, "_name") else t.__name__][0]
+            for t in dtype
+            if t is not None
+        )
+        dtype_str += " or None" if None in dtype else ""
+    elif isinstance(dtype, str):
+        dtype_str = dtype
+    else:
+        dtype_str = dtype.__name__
+    return dtype_str, desc
+
+
+def clean_docstring(func, additional_docstring, indent_str, heading):
+    existing_docstring = func.__doc__ or ""
+    if heading in existing_docstring:
+        func.__doc__ = (
+            existing_docstring.split("---\n")[0]
+            + "---\n"
+            + additional_docstring
+            + "---\n".join(existing_docstring.split("---\n")[1:])
+        )
+    else:
+        func.__doc__ = (
+            existing_docstring
+            + f"\n\n{indent_str}{heading}\n{indent_str}----------\n"
+            + additional_docstring
+        )
+
+
+# Decorator to add common parameters to docstring
+def add_docstring(func=None, *, parameters=None, returns=None):
+    def decorator(func, parameters=parameters, returns=returns):
+        param_docstring, return_docstring = "", ""
+        if func.__doc__:
+            # Determine the current indentation level
+            lines = func.__doc__.splitlines()
+            if len(lines[0]) == 0:
+                indent = len(lines[1]) - len(lines[1].lstrip())
+            else:
+                indent = len(lines[0]) - len(lines[0].lstrip())
+        else:
+            indent = 0
+        indent_str = " " * indent
+        if isinstance(parameters, str):
+            parameters = [parameters]
+        if isinstance(returns, str):
+            returns = [returns]
+
+        if parameters is not None:
+            for name in parameters:
+                if name in DOCSTRINGS:
+                    dtype_str, desc = extract_docstring_type(*DOCSTRINGS[name])
+                    param_docstring += f"{indent_str}{name}: {dtype_str}\n{indent_str}    {desc}\n"
+            clean_docstring(func, param_docstring, indent_str, "Parameters")
+
+        if returns is not None:
+            for name in returns:
+                if name in DOCSTRINGS:
+                    dtype_str, desc = extract_docstring_type(*DOCSTRINGS[name])
+                    return_docstring += f"{indent_str}{name}: {dtype_str}\n{indent_str}    {desc}\n"
+            clean_docstring(func, return_docstring, indent_str, "Returns")
+        return func
+
+    return decorator
+
+
+# Decorator to inherit docstring from base class
+def inherit_docstring(func):
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        return func(*args, **kwargs)
+
+    if func.__doc__ is None:
+        for base in func.__qualname__.split(".")[0].__bases__:
+            base_func = getattr(base, func.__name__, None)
+            if base_func and base_func.__doc__:
+                func.__doc__ = base_func.__doc__
+                break
+    return wrapper