lezargus 0.0.4.dev51__tar.gz → 0.0.5__tar.gz

{lezargus-0.0.4.dev51 → lezargus-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: lezargus
-Version: 0.0.4.dev51
+Version: 0.0.5
 Summary: The accompanying data software package to the IRTF SPECTRE Spectrograph.
 Project-URL: Homepage, http://irtfweb.ifa.hawaii.edu/~spectre/
 Project-URL: Documentation, https://psmd-iberutaru.github.io/Lezargus/

{lezargus-0.0.4.dev51 → lezargus-0.0.5}/docs/source/technical/contributing.rst

@@ -144,7 +144,7 @@ adding to Lezargus. However, please keep the following in mind.
 
     - Python source files are better as one word.
     - Please have proper docstrings for all your files, functions, and classes. 
-      We require this but sometimes the automatic tools don't catch very case. 
+      We require this but sometimes the automatic tools don't catch every case. 
       We (generally) follow the 
       `Google/numpydoc <https://numpydoc.readthedocs.io/en/latest/format.html>`_ 
       style guide. (Note if you find a violation of the guide in our 

{lezargus-0.0.4.dev51 → lezargus-0.0.5}/docs/source/technical/convention.rst

@@ -31,8 +31,14 @@ look weird.
 - Solid angle: ``sr``
 - Information: ``bit``
 
-This is beneficial in that we do not need to deal with unit clashes. We 
-also allow Astropy to handle quite a few unit conversions behind the scene.
+We however have the following exceptions. This is a complete list, any 
+deviation from SI units not in the exception list is considered a bug.
+
+- Atmospheric precipitable water vapor: ``mm``.
+
+
+Using SI-only is beneficial in that we do not need to deal with unit clashes. 
+We also allow Astropy to handle quite a few unit conversions behind the scene.
 However, as developing Lezargus, care must still be taken into account. The 
 ultimate idea being that units within Lezargus are all self-consistent, with 
 conversions happening at input and output. Unit conversions are easily done 

{lezargus-0.0.4.dev51 → lezargus-0.0.5}/pyproject.toml

@@ -165,8 +165,8 @@ ban-relative-imports = "all"
 # provide hints.
 "src/lezargus/library/hint.py" = ["F401", "F403"]
 # The __init__ files often provide the imports to other files. 
-# So they are used, just not in that file.
-"src/lezargus/**/__init__.py" = ["F401"]
+# So they are used, just not in that file. 
+"src/lezargus/**/__init__.py" = ["F401",]
 
 [tool.ruff.lint.mccabe]
 # Flag errors (`C901`) whenever the complexity level exceeds some value.

{lezargus-0.0.4.dev51 → lezargus-0.0.5}/src/lezargus/__init__.py

@@ -19,7 +19,7 @@ from lezargus import initialize
 
 # isort:split
 # User-based functionality, the actual classes which call the above functions.
-from lezargus import simulation
+from lezargus import simulator
 
 # Lastly, the main file. We only do this so that Sphinx correctly builds the
 # documentation. (Though this too could be a misunderstanding.) Functionality

{lezargus-0.0.4.dev51 → lezargus-0.0.5}/src/lezargus/__version__.py

@@ -4,4 +4,4 @@ Please do not manually edit this value.
 """
 
 # DO NOT EDIT MANUALLY.
-__version__ = "0.0.4.dev51"
+__version__ = "0.0.5"

{lezargus-0.0.4.dev51 → lezargus-0.0.5}/src/lezargus/container/__init__.py

@@ -24,9 +24,10 @@ from lezargus.container.spectrum import LezargusSpectrum
 
 # The minor classes for dimensional data, with a very specific implementation
 # details.
+from lezargus.container.atmosphere import AtmosphereSpectrumGenerator
 
+# isort: split
 
-# Other inner packages. Although easily accessible by the user, the depth of
-# these packages and functions, compared to the main containers, implies that
-# we should still abstract it away from the end-user.
-from lezargus.container import broadcast
+# Extra and utility functions which operate on containers. Though user facing,
+# it is more likely the user would not directly use these functions.
+from lezargus.container import function

lezargus-0.0.5/src/lezargus/container/atmosphere.py

@@ -0,0 +1,219 @@
+"""Container classes to hold both atmospheric transmission and radiance.
+
+We define small wrappers to hold atmospheric transmission and radiance data
+so that it can be used more easily. The data itself usually has been derived
+from PSG. These container classes are just intuitive wrappers around
+interpolation.
+"""
+
+# isort: split
+# Import required to remove circular dependencies from type checking.
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from lezargus.library import hint
+# isort: split
+
+import numpy as np
+
+import lezargus
+
+
+class AtmosphereSpectrumGenerator:
+    """Atmospheric spectrum generator/interpolator.
+
+    This class generates, via interpolation of a pre-computed grid. Typically
+    this is used for atmospheric transmission and radiance spectrum, but,
+    others may be used as well.
+
+    Attributes
+    ----------
+    wavelength : ndarray
+        The wavelength axis of the grid data we are interpolating over.
+    zenith_angle : ndarray
+        The zenith angle axis of the grid data we are interpolating over.
+        The actual interpolation uses airmass instead of zenith angle.
+    airmass : ndarray
+        The calculated airmass axis of the grid data we are interpolating over.
+    pwv : ndarray
+        The precipitable water vapor axis of the grid data we are interpolating
+        over.
+    data : ndarray
+        The data grid, usually transmission or radiance. The axes are defined
+        by the other attributes.
+    wavelength_unit : Unit
+        The wavelength unit of the wavelength array provided, if provided.
+    data_unit : Unit
+        The data unit of the data provided, if provided.
+    spectral_scale : float
+        The spectral resolution (scale) of the computed grid, if provided.
+    _data_interpolator : RegularNDInterpolator
+        The interpolator class for the data which we use as the backbone of
+        this generator. This should not be called directly.
+
+    """
+
+    def __init__(
+        self: AtmosphereSpectrumGenerator,
+        wavelength: hint.ndarray,
+        zenith_angle: hint.ndarray,
+        pwv: hint.ndarray,
+        data: hint.ndarray,
+        wavelength_unit: hint.Unit | str = "m",
+        data_unit: hint.Unit | str = "",
+        spectral_scale: float | None = None,
+    ) -> None:
+        """Initialize the atmospheric transmission and radiance container.
+
+        Parameters
+        ----------
+        wavelength : ndarray
+            The wavelength axis of the grid data that defines the transmission
+            and radiance data.
+        zenith_angle : ndarray
+            The zenith angle axis of the grid data that defines the
+            transmission and radiance data, in radians.
+        pwv : ndarray
+            The precipitable water vapor axis of the grid data that defines
+            the transmission and radiance data, in millimeters.
+        data : ndarray
+            The atmospheric data for the generator to "generate" via
+            interpolation. The shape of the data should match that created
+            by the domain of the previous attributes.
+        wavelength_unit : Unit or str, default = "m"
+            The wavelength unit of the wavelength provided. By default and by
+            convention, this should be in meters.
+        data_unit : Unit or str
+            The data unit of the data provided. By default, we assume a
+            dimensionless spectrum.
+        spectral_scale : float, default = 0
+            The spectral (scale) resolution of the simulation.
+
+        """
+        # Interpolation using airmass over zenith angle makes more sense as
+        # airmass has a linear response.
+        airmass = lezargus.library.atmosphere.airmass(zenith_angle=zenith_angle)
+
+        # We can properly build our class.
+        self.wavelength = wavelength
+        self.zenith_angle = zenith_angle
+        self.airmass = airmass
+        self.pwv = pwv
+        self.data = data
+
+        # Meta data information.
+        self.wavelength_unit = lezargus.library.conversion.parse_astropy_unit(
+            unit_string=wavelength_unit,
+        )
+        self.data_unit = lezargus.library.conversion.parse_astropy_unit(
+            unit_string=data_unit,
+        )
+        self.spectral_scale = spectral_scale
+
+        # Building the interpolators.
+        domain = (wavelength, airmass, pwv)
+        self._data_interpolator = (
+            lezargus.library.interpolate.RegularNDInterpolate(
+                domain=domain,
+                v=self.data,
+            )
+        )
+
+    def interpolate(
+        self: hint.Self,
+        wavelength: hint.ndarray | None = None,
+        zenith_angle: float = 0,
+        pwv: float = 0.5,
+    ) -> hint.ndarray:
+        """Generate atmospheric spectrum, through interpolation.
+
+        Parameters
+        ----------
+        wavelength : ndarray, default = None
+            The wavelengths to compute the spectrum at. If None,
+            we default to the wavelength basis used to generate this class.
+        zenith_angle : float, default = 0
+            The zenith angle for the transmission spectrum generation,
+            in radians.
+        pwv : float, default = 0
+            The precipitable water vapor for the transmission spectrum
+            generation, in millimeters.
+
+        Returns
+        -------
+        generated_data : ndarray
+            The generated/interpolated data sampled at the provided
+            wavelengths.
+
+        """
+        # The default wavelength if not provided.
+        wavelength = self.wavelength if wavelength is None else wavelength
+
+        # Airmass is the defining axis, not zenith angle, because of its
+        # more linear nature.
+        airmass = lezargus.library.atmosphere.airmass(zenith_angle=zenith_angle)
+
+        # Finally, we interpolate the values. Note, we need parallel arrays
+        # to define the points, so we just extend the airmass and PWV values.
+        airmass_extension = np.full_like(wavelength, airmass)
+        pwv_extension = np.full_like(wavelength, pwv)
+        generated_data = self._data_interpolator.interpolate(
+            wavelength,
+            airmass_extension,
+            pwv_extension,
+        )
+
+        # All done.
+        return generated_data
+
+    def interpolate_spectrum(
+        self: hint.Self,
+        wavelength: hint.ndarray | None = None,
+        zenith_angle: float = 0,
+        pwv: float = 0.5,
+    ) -> hint.LezargusSpectrum:
+        """Generate a atmospheric LezargusSpectrum, through interpolation.
+
+        This function really is a wrapper around the usual interpolator,
+        repackaging the results as a LezargusSpectrum. Note, most of the
+        meta data parameters are wrong and need to be fixed manually.
+
+        Parameters
+        ----------
+        wavelength : ndarray, default = None
+            The wavelengths to compute the spectrum at. If None,
+            we default to the wavelength basis used to generate this class.
+        zenith_angle : float, default = 0
+            The zenith angle for the transmission spectrum generation,
+            in radians.
+        pwv : float, default = 0
+            The precipitable water vapor for the transmission spectrum
+            generation, in millimeters.
+
+        Returns
+        -------
+        generated_spectrum : LezargusSpectrum
+            The generated/interpolated data sampled at the provided
+            wavelengths. This is packaged as a LezargusSpectrum.
+
+        """
+        # We find the generated data.
+        generated_data = self.interpolate(
+            wavelength=wavelength,
+            zenith_angle=zenith_angle,
+            pwv=pwv,
+        )
+
+        # We repackage it.
+        generated_spectrum = lezargus.container.LezargusSpectrum(
+            wavelength=wavelength,
+            data=generated_data,
+            uncertainty=None,
+            spectral_scale=self.spectral_scale,
+            wavelength_unit=self.wavelength_unit,
+            data_unit=self.data_unit,
+            header=None,
+        )
+        return generated_spectrum

{lezargus-0.0.4.dev51 → lezargus-0.0.5}/src/lezargus/container/cube.py

@@ -28,6 +28,7 @@ class LezargusCube(LezargusContainerArithmetic):
         uncertainty: hint.ndarray = None,
         wavelength_unit: str | hint.Unit | None = None,
         data_unit: str | hint.Unit | None = None,
+        spectral_scale: float | None = None,
         pixel_scale: float | None = None,
         slice_scale: float | None = None,
         mask: hint.ndarray | None = None,
@@ -53,6 +54,10 @@ class LezargusCube(LezargusContainerArithmetic):
             The unit of the wavelength array. If None, we assume unit-less.
         data_unit : Astropy Unit
             The unit of the data array. If None, we assume unit-less.
+        spectral_scale : float, default = None
+            The spectral scale, or spectral resolution, of the spectral
+            component, if any. Must be in meters per pixel. Scale is None if
+            none is provided.
         pixel_scale : float, default = None
             The E-W, "x" dimension, pixel plate scale of the spatial component,
             if any. Must be in radians per pixel. Scale is None if none
@@ -111,6 +116,7 @@ class LezargusCube(LezargusContainerArithmetic):
             uncertainty=uncertainty,
             wavelength_unit=wavelength_unit,
             data_unit=data_unit,
+            spectral_scale=spectral_scale,
             pixel_scale=pixel_scale,
             slice_scale=slice_scale,
             mask=mask,
@@ -173,17 +179,24 @@ class LezargusCube(LezargusContainerArithmetic):
         # Any post-processing is done here.
         # All done.
 
-    def convolve_spectra(self: hint.Self, kernel: hint.ndarray) -> hint.Self:
+    def convolve_spectra(
+        self: hint.Self,
+        kernel: hint.ndarray | None = None,
+        kernel_stack: hint.ndarray | None = None,
+        kernel_function: hint.Callable | None = None,
+    ) -> hint.Self:
         """Convolve the cube by a spectral kernel convolving spectra slices.
 
-        Convolving a spectral cube can either be done one of two ways;
-        convolving by image slices or convolving by spectral slices. We here
-        convolve by spectral slices.
+        See py:func:`convolve_cube_by_spectral_kernel` for full documentation.
 
         Parameters
         ----------
-        kernel : ndarray
-            The spectral kernel which we are using to convolve.
+        kernel : ndarray, default = None
+            The static 1D kernel.
+        kernel_stack : ndarray, default = None
+            The variable 1D kernel stack.
+        kernel_function : Callable, default = None
+            The dynamic 1D kernel function.
 
         Returns
         -------
@@ -191,59 +204,31 @@ class LezargusCube(LezargusContainerArithmetic):
             A near copy of the data cube after convolution.
 
         """
-        # Using this kernel, we convolve the cube. We assume that the
-        # uncertainties add in quadrature.
-        convolved_data = (
-            lezargus.library.convolution.convolve_3d_array_by_1d_kernel(
-                array=self.data,
-                kernel=kernel,
-            )
-        )
-        convolved_uncertainty = np.sqrt(
-            lezargus.library.convolution.convolve_3d_array_by_1d_kernel(
-                self.uncertainty**2,
-                kernel=kernel,
-            ),
-        )
-
-        # We also propagate the convolution of the mask and the flags where
-        # needed.
-        logging.error(
-            error_type=logging.ToDoError,
-            message=(
-                "Propagation of mask and flags via convolution is not done."
-            ),
-        )
-        convolved_mask = self.mask
-        convolved_flags = self.flags
-
-        # From the above information, we construct the new spectra.
-        cube_class = type(self)
-        convolved_cube = cube_class(
-            wavelength=self.wavelength,
-            data=convolved_data,
-            uncertainty=convolved_uncertainty,
-            wavelength_unit=self.wavelength_unit,
-            data_unit=self.data_unit,
-            mask=convolved_mask,
-            flags=convolved_flags,
-            header=self.header,
+        return lezargus.container.function.convolve_cube_by_spectral_kernel(
+            cube=self,
+            kernel=kernel,
+            kernel_stack=kernel_stack,
+            kernel_function=kernel_function,
         )
 
-        # All done.
-        return convolved_cube
-
-    def convolve_image(self: hint.Self, kernel: hint.ndarray) -> hint.Self:
+    def convolve_image(
+        self: hint.Self,
+        kernel: hint.ndarray | None = None,
+        kernel_stack: hint.ndarray | None = None,
+        kernel_function: hint.Callable | None = None,
+    ) -> hint.Self:
         """Convolve the cube by an image kernel convolving image slices.
 
-        Convolving a spectral cube can either be done one of two ways;
-        convolving by image slices or convolving by spectral slices. We here
-        convolve by image slices.
+        See py:func:`convolve_cube_by_image_kernel` for full documentation.
 
         Parameters
         ----------
-        kernel : ndarray
-            The image kernel which we are using to convolve.
+        kernel : ndarray, default = None
+            The static 2D kernel.
+        kernel_stack : ndarray, default = None
+            The variable 2D kernel stack.
+        kernel_function : Callable, default = None
+            The dynamic 2D kernel function.
 
         Returns
         -------
@@ -251,44 +236,9 @@ class LezargusCube(LezargusContainerArithmetic):
             A near copy of the data cube after convolution.
 
         """
-        # Using this kernel, we convolve the cube. We assume that the
-        # uncertainties add in quadrature.
-        convolved_data = (
-            lezargus.library.convolution.convolve_3d_array_by_2d_kernel(
-                array=self.data,
-                kernel=kernel,
-            )
-        )
-        convolved_uncertainty = np.sqrt(
-            lezargus.library.convolution.convolve_3d_array_by_2d_kernel(
-                self.uncertainty**2,
-                kernel=kernel,
-            ),
-        )
-
-        # We also propagate the convolution of the mask and the flags where
-        # needed.
-        logging.error(
-            error_type=logging.ToDoError,
-            message=(
-                "Propagation of mask and flags via convolution is not done."
-            ),
-        )
-        convolved_mask = self.mask
-        convolved_flags = self.flags
-
-        # From the above information, we construct the new spectra.
-        cube_class = type(self)
-        convolved_cube = cube_class(
-            wavelength=self.wavelength,
-            data=convolved_data,
-            uncertainty=convolved_uncertainty,
-            wavelength_unit=self.wavelength_unit,
-            data_unit=self.data_unit,
-            mask=convolved_mask,
-            flags=convolved_flags,
-            header=self.header,
+        return lezargus.container.function.convolve_cube_by_image_kernel(
+            cube=self,
+            kernel=kernel,
+            kernel_stack=kernel_stack,
+            kernel_function=kernel_function,
         )
-
-        # All done.
-        return convolved_cube

lezargus-0.0.5/src/lezargus/container/function/__init__.py

@@ -0,0 +1,19 @@
+"""Functionality relating to the container classes are put in this module.
+
+We put extra functionality that is not entirely related to the container
+classes here. Although it is very common to have the containers have their
+own interfaces to the functionality provided by this module. Moreover,
+by offloading a lot of the logic into this module, the container class files
+can be shorter and cleaner.
+
+It is fine to have all of the functions in the same namespace. We separate
+the files so it is easier to navigate however.
+"""
+
+# All of the container functions exist in all the same namespace, but we
+# break it into different files for organization.
+# ruff: noqa: F403
+
+from lezargus.container.function.broadcast import *
+from lezargus.container.function.convolution import *
+from lezargus.container.function.transform import *