aiapy 0.8.0__py3-none-any.whl

aiapy/CITATION.rst

@@ -0,0 +1,31 @@
+Acknowledging or Citing aiapy
+=============================
+
+If you use aiapy in your scientific work, we would appreciate you citing it in your publications.
+
+Please add the following line within your methods, conclusion or acknowledgements sections:
+
+*This research used version X.Y.Z (software citation) of the aiapy open source
+software package (project citation).*
+
+The project citation should be to the `aiapy paper`_ and the software citation should be the specific `Zenodo DOI`_ for the version used within your work.
+
+.. code:: bibtex
+
+   @article{Barnes2020,
+      doi = {10.21105/joss.02801},
+      url = {https://doi.org/10.21105/joss.02801},
+      year = {2020},
+      publisher = {The Open Journal},
+      volume = {5},
+      number = {55},
+      pages = {2801},
+      author = {Will T. Barnes and Mark C. M. Cheung and Monica G. Bobra and Paul F. Boerner and Georgios Chintzoglou and Drew Leonard and Stuart J. Mumford and Nicholas Padmanabhan and Albert Y. Shih and Nina Shirman and David Stansby and Paul J. Wright},
+      title = {aiapy: A Python Package for Analyzing Solar EUV Image Data from AIA},
+      journal = {Journal of Open Source Software}
+   }
+
+You can also obtain this information with ``aiapy.__citation__``.
+
+.. _Zenodo DOI: https://zenodo.org/record/4274931
+.. _aiapy paper: https://joss.theoj.org/papers/10.21105/joss.02801

aiapy/__init__.py

@@ -0,0 +1,29 @@
+from itertools import compress
+from pathlib import Path
+
+from .version import version as __version__
+
+_SSW_MIRRORS = [
+    "https://soho.nascom.nasa.gov/solarsoft/",
+    "https://hesperia.gsfc.nasa.gov/ssw/",
+]
+
+
+def _get_bibtex():
+    import textwrap
+
+    # Set the bibtex entry to the article referenced in CITATION.rst
+    citation_file = Path(__file__).parent / "CITATION.rst"
+
+    # Explicitly specify UTF-8 encoding in case the system's default encoding is problematic
+    with Path.open(citation_file, "r", encoding="utf-8") as citation:
+        # Extract the first bibtex block:
+        ref = citation.read().partition(".. code:: bibtex\n\n")[2]
+        lines = ref.split("\n")
+        # Only read the lines which are indented
+        lines = list(compress(lines, [line.startswith("   ") for line in lines]))
+        return textwrap.dedent("\n".join(lines))
+
+
+__citation__ = __bibtex__ = _get_bibtex()
+__all__ = ["__version__", "__citation__", "_SSW_MIRRORS"]

aiapy/_version.py

@@ -0,0 +1,16 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.8.0'
+__version_tuple__ = version_tuple = (0, 8, 0)

aiapy/calibrate/__init__.py

@@ -0,0 +1,9 @@
+"""
+Subpackage for calibrating AIA imaging data.
+"""
+
+from .meta import *  # NOQA: F403
+from .prep import *  # NOQA: F403
+from .spikes import *  # NOQA: F403
+from .transform import *  # NOQA: F403
+from .uncertainty import *  # NOQA: F403

aiapy/calibrate/meta.py

@@ -0,0 +1,191 @@
+"""
+Functions for updating/fixing header keywords.
+"""
+
+import copy
+import warnings
+
+import astropy.time
+import astropy.units as u
+import numpy as np
+from astropy.coordinates import CartesianRepresentation, HeliocentricMeanEcliptic, SkyCoord
+from sunpy.map import contains_full_disk
+
+from aiapy.calibrate.util import get_pointing_table
+from aiapy.util.exceptions import AiapyUserWarning
+
+__all__ = ["fix_observer_location", "update_pointing"]
+
+
+def fix_observer_location(smap):
+    """
+    Fix inaccurate ``HGS_LON`` and ``HGS_LAT`` FITS keywords.
+
+    The heliographic Stonyhurst latitude and longitude locations in the
+    AIA FITS headers are incorrect. This function fixes the values of these
+    keywords using the heliocentric aries ecliptic keywords, ``HAEX_OBS,
+    HAEY_OBS, HAEZ_OBS``.
+
+    .. note::
+
+        `~sunpy.map.sources.AIAMap` already accounts for the inaccurate
+        HGS keywords by using the HAE keywords to construct the
+        derived observer location.
+
+    Parameters
+    ----------
+    smap : `~sunpy.map.sources.AIAMap`
+        Input map.
+
+    Returns
+    -------
+    `~sunpy.map.sources.AIAMap`
+    """
+    # Create observer coordinate from HAE coordinates
+    coord = SkyCoord(
+        x=smap.meta["haex_obs"] * u.m,
+        y=smap.meta["haey_obs"] * u.m,
+        z=smap.meta["haez_obs"] * u.m,
+        representation_type=CartesianRepresentation,
+        frame=HeliocentricMeanEcliptic,
+        obstime=smap.date,
+    ).heliographic_stonyhurst
+    # Update header
+    new_meta = copy.deepcopy(smap.meta)
+    new_meta["hgln_obs"] = coord.lon.to(u.degree).value
+    new_meta["hglt_obs"] = coord.lat.to(u.degree).value
+    new_meta["dsun_obs"] = coord.radius.to(u.m).value
+
+    return smap._new_instance(smap.data, new_meta, plot_settings=smap.plot_settings, mask=smap.mask)  # NOQA: SLF001
+
+
+def update_pointing(smap, *, pointing_table=None):
+    """
+    Update the pointing information in the input map header.
+
+    This function updates the pointing information in ``smap`` by
+    updating the ``CRPIX1, CRPIX2, CDELT1, CDELT2, CROTA2`` keywords
+    in the header using the information provided in ``pointing_table``.
+    If ``pointing_table`` is not specified, the 3-hour pointing
+    information is queried from the `JSOC <http://jsoc.stanford.edu/>`_.
+
+    .. note::
+
+        The method removes any ``PCi_j`` matrix keys in the header and
+        updates the ``CROTA2`` keyword.
+
+    .. note::
+
+        If correcting pointing information for a large number of images,
+        it is strongly recommended to query the table once for the
+        appropriate interval and then pass this table in rather than
+        executing repeated queries.
+
+    .. warning::
+
+        This function is only intended to be used for full-disk images
+        at the full resolution of 4096x4096 pixels. It will raise a
+        ``ValueError`` if the input map does not meet these criteria.
+
+    Parameters
+    ----------
+    smap : `~sunpy.map.sources.AIAMap`
+        Input map.
+    pointing_table : `~astropy.table.QTable`, optional
+        Table of pointing information. If not specified, the table
+        will be retrieved from JSOC.
+
+    Returns
+    -------
+    `~sunpy.map.sources.AIAMap`
+
+    See Also
+    --------
+    `aiapy.calibrate.util.get_pointing_table`
+    """
+    if not contains_full_disk(smap):
+        msg = "Input must be a full disk image."
+        raise ValueError(msg)
+    shape_full_frame = (4096, 4096)
+    if not all(d == (s * u.pixel) for d, s in zip(smap.dimensions, shape_full_frame, strict=True)):
+        msg = f"Input must be at the full resolution of {shape_full_frame}"
+        raise ValueError(msg)
+    if pointing_table is None:
+        # Make range wide enough to get closest 3-hour pointing
+        pointing_table = get_pointing_table(smap.date - 12 * u.h, smap.date + 12 * u.h)
+    # Find row in which T_START <= T_OBS < T_STOP
+    # The following notes are from a private communication with J. Serafin (LMSAL)
+    # and are preserved here to explain the reasoning for selecting the particular
+    # entry from the master pointing table (MPT).
+    # NOTE: The 3 hour MPT entries are computed from limb fits of images with T_OBS
+    # between T_START and T_START + 3hr, so any image with T_OBS equal to
+    # T_START + 3hr - epsilon should still use the 3hr MPT entry for that T_START.
+    # NOTE: For SDO data, T_OBS is preferred to DATE-OBS in the case of the
+    # MPT, using DATE-OBS from near the slot boundary might result in selecting
+    # an incorrect MPT record.
+    t_obs = smap.meta.get("T_OBS")
+    if t_obs is None:
+        warnings.warn(
+            "T_OBS key is missing from metadata. Falling back to Map.date. "
+            "This may result in selecting in incorrect record from the "
+            "master pointing table.",
+            AiapyUserWarning,
+            stacklevel=3,
+        )
+        t_obs = smap.date
+    t_obs = astropy.time.Time(t_obs)
+    t_obs_in_interval = np.logical_and(t_obs >= pointing_table["T_START"], t_obs < pointing_table["T_STOP"])
+    if not t_obs_in_interval.any():
+        msg = (
+            f"No valid entries for {t_obs} in pointing table "
+            f'with first T_START date of {pointing_table[0]["T_START"]} '
+            f'and a last T_STOP date of {pointing_table[-1]["T_STOP"]}.'
+        )
+        raise IndexError(msg)
+    i_nearest = np.where(t_obs_in_interval)[0][0]
+    w_str = f"{smap.wavelength.to(u.angstrom).value:03.0f}"
+    new_meta = copy.deepcopy(smap.meta)
+    # Extract new pointing parameters
+    # The x0 and y0 keywords denote the location of the center
+    # of the Sun in CCD pixel coordinates (0-based), but FITS WCS indexing is
+    # 1-based. See Section 2.2 of
+    # http://jsoc.stanford.edu/~jsoc/keywords/AIA/AIA02840_K_AIA-SDO_FITS_Keyword_Document.pdf
+    x0_mp = pointing_table[f"A_{w_str}_X0"][i_nearest].to("pix").value
+    y0_mp = pointing_table[f"A_{w_str}_Y0"][i_nearest].to("pix").value
+    crpix1 = x0_mp + 1
+    crpix2 = y0_mp + 1
+    cdelt = pointing_table[f"A_{w_str}_IMSCALE"][i_nearest].to("arcsecond / pixel").value
+    # CROTA2 is the sum of INSTROT and SAT_ROT.
+    # See http://jsoc.stanford.edu/~jsoc/keywords/AIA/AIA02840_H_AIA-SDO_FITS_Keyword_Document.pdf
+    # NOTE: Is the value of SAT_ROT in the header accurate?
+    crota2 = pointing_table[f"A_{w_str}_INSTROT"][i_nearest] + smap.meta["SAT_ROT"] * u.degree
+    crota2 = crota2.to("deg").value
+    # Update headers
+    for key, value in [
+        ("crpix1", crpix1),
+        ("crpix2", crpix2),
+        ("x0_mp", x0_mp),  # x0_mp and y0_mp are not standard FITS keywords but they are
+        ("y0_mp", y0_mp),  # used when respiking submaps so we update them here.
+        ("cdelt1", cdelt),
+        ("cdelt2", cdelt),
+        ("crota2", crota2),
+    ]:
+        if np.isnan(value):
+            # There are some entries in the pointing table returned from the JSOC that are marked as
+            # MISSING. These get converted to NaNs when we cast it to an astropy quantity table. In
+            # these cases, we just want to skip updating the pointing information.
+            warnings.warn(
+                f"Missing value in pointing table for {key}. This key will not be updated.",
+                AiapyUserWarning,
+                stacklevel=3,
+            )
+        else:
+            new_meta[key] = value
+
+    # sunpy map converts crota to a PCi_j matrix, so we remove it to force the
+    # re-conversion.
+    new_meta.pop("PC1_1")
+    new_meta.pop("PC1_2")
+    new_meta.pop("PC2_1")
+    new_meta.pop("PC2_2")
+    return smap._new_instance(smap.data, new_meta, plot_settings=smap.plot_settings, mask=smap.mask)  # NOQA: SLF001

aiapy/calibrate/prep.py

@@ -0,0 +1,231 @@
+"""
+Functions for calibrating AIA images.
+"""
+
+import warnings
+
+import astropy.units as u
+import numpy as np
+from sunpy.map import contains_full_disk
+from sunpy.map.sources.sdo import AIAMap, HMIMap
+from sunpy.util.decorators import add_common_docstring
+
+from aiapy.calibrate.transform import _rotation_function_names
+from aiapy.calibrate.util import _select_epoch_from_correction_table, get_correction_table
+from aiapy.util import AiapyUserWarning
+from aiapy.util.decorators import validate_channel
+
+__all__ = ["register", "correct_degradation", "degradation"]
+
+
+@add_common_docstring(rotation_function_names=_rotation_function_names)
+def register(smap, *, missing=None, order=3, method="scipy"):
+    """
+    Processes a full-disk level 1 `~sunpy.map.sources.AIAMap` into a level
+    1.5 `~sunpy.map.sources.AIAMap`.
+
+    Rotates, scales and translates the image so that solar North is aligned
+    with the y axis, each pixel is 0.6 arcsec across, and the center of the
+    Sun is at the center of the image. The actual transformation is done by
+    the `~sunpy.map.GenericMap.rotate` method.
+
+    .. warning::
+
+        This function might not return a 4096 by 4096 data array
+        due to the nature of rotating and scaling the image.
+        If you need a 4096 by 4096 image, you will need to pad the array manually,
+        update header: crpix1 and crpix2 by the difference divided by 2 in size along that axis.
+        Then create a new map.
+
+        Please open an issue on the `aiapy GitHub page <https://github.com/LM-SAL/aiapy/issues>`__
+        if you would like to see this changed.
+
+    .. note::
+
+        This routine modifies the header information to the standard
+        ``PCi_j`` WCS formalism. The FITS header resulting in saving a file
+        after this procedure will therefore differ from the original
+        file.
+
+    Parameters
+    ----------
+    smap : `~sunpy.map.sources.AIAMap` or `~sunpy.map.sources.sdo.HMIMap`
+        A `~sunpy.map.Map` containing a full-disk AIA image or HMI magnetogram
+    missing : `float`, optional
+        If there are missing values after the interpolation, they will be
+        filled in with ``missing``. If `None`, the default value will be the
+        minimum value of ``smap``
+    order : `int`, optional
+        Order of the spline interpolation.
+    method : {{{rotation_function_names}}}, optional
+        Rotation function to use. Defaults to ``'scipy'``.
+
+    Returns
+    -------
+    `~sunpy.map.sources.AIAMap` or `~sunpy.map.sources.sdo.HMIMap`:
+        A level 1.5 copy of `~sunpy.map.sources.AIAMap` or
+        `~sunpy.map.sources.sdo.HMIMap`.
+    """
+    # This implementation is taken directly from the `aiaprep` method in
+    # sunpy.instr.aia.aiaprep under the terms of the BSD 2 Clause license.
+    # See licenses/SUNPY.rst.
+    if not isinstance(smap, AIAMap | HMIMap):
+        msg = "Input must be an AIAMap or HMIMap."
+        raise TypeError(msg)
+    if not contains_full_disk(smap):
+        msg = "Input must be a full disk image."
+        raise ValueError(msg)
+    if smap.processing_level is None or smap.processing_level > 1:
+        warnings.warn(
+            "Image registration should only be applied to level 1 data",
+            AiapyUserWarning,
+            stacklevel=3,
+        )
+    # Target scale is 0.6 arcsec/pixel, but this needs to be adjusted if the
+    # map has already been rescaled.
+    if (smap.scale[0] / 0.6).round() != 1.0 * u.arcsec / u.pix and smap.data.shape != (
+        4096,
+        4096,
+    ):
+        scale = (smap.scale[0] / 0.6).round() * 0.6 * u.arcsec
+    else:
+        scale = 0.6 * u.arcsec  # pragma: no cover # needs a full res image
+    scale_factor = smap.scale[0] / scale
+    missing = smap.min() if missing is None else missing
+    tempmap = smap.rotate(
+        recenter=True,
+        scale=scale_factor.value,
+        order=order,
+        missing=missing,
+        method=method,
+    )
+    # extract center from padded smap.rotate output
+    # crpix1 and crpix2 will be equal (recenter=True), as prep does not work with submaps
+    center = np.floor(tempmap.meta["crpix1"])
+    range_side = (center + np.array([-1, 1]) * smap.data.shape[0] / 2) * u.pix
+    newmap = tempmap.submap(
+        u.Quantity([range_side[0], range_side[0]]),
+        top_right=u.Quantity([range_side[1], range_side[1]]) - 1 * u.pix,
+    )
+    newmap.meta["r_sun"] = newmap.meta["rsun_obs"] / newmap.meta["cdelt1"]
+    newmap.meta["lvl_num"] = 1.5
+    newmap.meta["bitpix"] = -64
+    return newmap
+
+
+def correct_degradation(smap, *, correction_table=None, calibration_version=None):
+    """
+    Apply time-dependent degradation correction to an AIA map.
+
+    This function applies a time-dependent correction to an AIA observation by
+    dividing the observed intensity by the correction factor calculated by
+    `degradation`. Any keyword arguments that can be passed to `degradation`
+    can also be passed in here.
+
+    Parameters
+    ----------
+    smap : `~sunpy.map.sources.AIAMap`
+        Map to be corrected.
+    correction_table : `~astropy.table.Table` or `str`, optional
+        Table of correction parameters or path to correction table file.
+        If not specified, it will be queried from JSOC. See
+        `aiapy.calibrate.util.get_correction_table` for more information.
+        If you are processing many images, it is recommended to
+        read the correction table once and pass it with this argument to avoid
+        multiple redundant network calls.
+    calibration_version : `int`, optional
+        The version of the calibration to use when calculating the degradation.
+        By default, this is the most recent version available from JSOC. If you
+        are using a specific calibration response file, you may need to specify
+        this according to the version in that file.
+
+    Returns
+    -------
+    `~sunpy.map.sources.AIAMap`
+
+    See Also
+    --------
+    degradation
+    """
+    d = degradation(
+        smap.wavelength,
+        smap.date,
+        correction_table=correction_table,
+        calibration_version=calibration_version,
+    )
+    return smap / d
+
+
+@u.quantity_input
+@validate_channel("channel")
+def degradation(
+    channel: u.angstrom,
+    obstime,
+    *,
+    correction_table=None,
+    calibration_version=None,
+) -> u.dimensionless_unscaled:
+    r"""
+    Correction to account for time-dependent degradation of the instrument.
+
+    The correction factor to account for the time-varying degradation of
+    the telescopes is given by a normalization to the calibration epoch
+    closest to ``obstime`` and an interpolation within that epoch to
+    ``obstime``,
+
+    .. math::
+
+        \frac{A_{eff}(t_{e})}{A_{eff}(t_0)}(1 + p_1\delta t + p_2\delta t^2 + p_3\delta t^3)
+
+    where :math:`A_{eff}(t_e)` is the effective area calculated at the
+    calibration epoch for ``obstime``, :math:`A_{eff}(t_0)` is the effective
+    area at the first calibration epoch (i.e. at launch),
+    :math:`p_1,p_2,p_3` are the interpolation coefficients for the
+    ``obstime`` epoch, and :math:`\delta t` is the difference between the
+    start time of the epoch and ``obstime``.
+    All calibration terms are taken from the ``aia.response`` series in JSOC
+    or read from the table input by the user.
+
+    .. note:: This function is adapted directly from the
+              `aia_bp_corrections.pro <https://sohoftp.nascom.nasa.gov/solarsoft/sdo/aia/idl/response/aia_bp_corrections.pro>`__
+              routine in SolarSoft.
+
+    Parameters
+    ----------
+    channel : `~astropy.units.Quantity`
+    obstime : `~astropy.time.Time`
+    correction_table : `~astropy.table.Table` or `str`, optional
+        Table of correction parameters or path to correction table file.
+        If not specified, it will be queried from JSOC. See
+        `aiapy.calibrate.util.get_correction_table` for more information.
+        If you are processing many images, it is recommended to
+        read the correction table once and pass it with this argument to avoid
+        multiple redundant network calls.
+    calibration_version : `int`, optional
+        The version of the calibration to use when calculating the degradation.
+        By default, this is the most recent version available from JSOC. If you
+        are using a specific calibration response file, you may need to specify
+        this according to the version in that file.
+
+    See Also
+    --------
+    aiapy.calibrate.util.get_correction_table
+    aiapy.response.Channel.wavelength_response
+    aiapy.response.Channel.eve_correction
+    """
+    if obstime.shape == ():
+        obstime = obstime.reshape((1,))
+    ratio = np.zeros(obstime.shape)
+    poly = np.zeros(obstime.shape)
+    # Do this outside of the loop to avoid repeated queries
+    correction_table = get_correction_table(correction_table=correction_table)
+    for i, t in enumerate(obstime):
+        table = _select_epoch_from_correction_table(channel, t, correction_table, version=calibration_version)
+
+        # Time difference between obstime and start of epoch
+        dt = (t - table["T_START"][-1]).to(u.day).value
+        # Correction to most recent epoch
+        ratio[i] = table["EFF_AREA"][-1] / table["EFF_AREA"][0]
+        # Polynomial correction to interpolate within epoch
+        poly[i] = table["EFFA_P1"][-1] * dt + table["EFFA_P2"][-1] * dt**2 + table["EFFA_P3"][-1] * dt**3 + 1.0
+    return u.Quantity(poly * ratio)