emccd-detect 2.2.5__tar.gz → 2.3.0__tar.gz

{emccd_detect-2.2.5 → emccd_detect-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: emccd_detect
-Version: 2.2.5
+Version: 2.3.0
 Summary: EMCCD detector image simulation
 Home-page: https://github.jpl.nasa.gov/WFIRST-CGI/emccd_detect
 Author: Bijan Nemati, Sam Miller, Kevin Ludwick
@@ -22,12 +22,12 @@ Requires-Dist: pyyaml
 
 # EMCCD Detect
 
-Given an input fluxmap, emccd_detect will return a simulated EMCCD detector image.
+Given an input fluxmap, emccd_detect will return a simulated EMCCD detector image.  Website:  (<https://github.com/roman-corgi/emccd_detect/tree/master/emccd_detect>)
 
 
 # Version
 
-The latest version of emccd\_detect is 2.2.5.
+The latest version of emccd\_detect is 2.3.0.
 
 
 ## Getting Started

{emccd_detect-2.2.5 → emccd_detect-2.3.0}/README.md

@@ -1,11 +1,11 @@
 # EMCCD Detect
 
-Given an input fluxmap, emccd_detect will return a simulated EMCCD detector image.
+Given an input fluxmap, emccd_detect will return a simulated EMCCD detector image.  Website:  (<https://github.com/roman-corgi/emccd_detect/tree/master/emccd_detect>)
 
 
 # Version
 
-The latest version of emccd\_detect is 2.2.5.
+The latest version of emccd\_detect is 2.3.0.
 
 
 ## Getting Started

{emccd_detect-2.2.5 → emccd_detect-2.3.0}/emccd_detect/__init__.py

@@ -1,2 +1,2 @@
 # -*- coding: utf-8 -*-
-__version__ = '2.2.5'
+__version__ = '2.3.0'

{emccd_detect-2.2.5 → emccd_detect-2.3.0}/emccd_detect/emccd_detect.py

@@ -9,6 +9,7 @@ import numpy as np
 
 from emccd_detect.cosmics import cosmic_hits, sat_tails
 from emccd_detect.rand_em_gain import rand_em_gain
+from emccd_detect.nonlinearity import apply_relgains
 from emccd_detect.util.read_metadata_wrapper import MetadataWrapper
 try:
     from arcticpy import add_cti, CCD, ROE, Trap, TrapInstantCapture
@@ -260,7 +261,8 @@ class EMCCDDetectBase:
         # Pass electrons through amplifier
         amp_ev = self._amp(gain_counts)
 
-        # Pass amp electron volt counts through analog to digital converter
+        # Pass amp electron volt counts through analog to digital converter,
+        # applying nonlinearity if applicable
         output_dn = self._adc(amp_ev)
 
         return output_dn
@@ -400,10 +402,16 @@ class EMCCDDetectBase:
             Analog to digital converter output (dn).
 
         """
-        # Convert from electron volts to dn
+        # Convert from electron volts to dn and apply nonlin if applicable
+        dn = amp_ev / self.eperdn
+        if hasattr(self, 'nonlin_path'):
+            if self.nonlin_path is not None:
+                nonlin_factors = apply_relgains(dn, self.em_gain, 
+                                                self.nonlin_path)
+                dn *= nonlin_factors
         dn_min = 0
         dn_max = 2**self.nbits - 1
-        output_dn = np.clip(amp_ev / self.eperdn, dn_min, dn_max).astype(np.uint64)
+        output_dn = np.clip(dn, dn_min, dn_max).astype(np.uint64)
 
         return output_dn
 
@@ -445,7 +453,13 @@ class EMCCDDetect(EMCCDDetectBase):
         Number of gain register elements. For eventually modeling partial CIC.
         Defaults to 604.
     meta_path : str
-        Full path of metadata.yaml.
+        Full path of metadata.yaml.  If None, defaults to metadata.yaml in util
+        folder.
+    nonlin_path : str
+        Path of nonlinearity correction file.  See doc string of 
+        nonlinearity.apply_relgains for details on the required 
+        format of the file.  If None, defaults to no application of 
+        nonlinearity.
 
     """
     def __init__(
@@ -463,7 +477,8 @@ class EMCCDDetect(EMCCDDetectBase):
         eperdn=None,
         nbits=14,
         numel_gain_register=604,
-        meta_path=None
+        meta_path=None,
+        nonlin_path=None
     ):
         # If no metadata file path specified, default to metadata.yaml in util
         if meta_path is None:
@@ -480,6 +495,8 @@ class EMCCDDetect(EMCCDDetectBase):
         if eperdn is None:
             eperdn = self.meta.eperdn
 
+        self.nonlin_path = nonlin_path
+
         super().__init__(
             em_gain=em_gain,
             full_well_image=full_well_image,

emccd_detect-2.3.0/emccd_detect/nonlinearity.py

@@ -0,0 +1,132 @@
+# -*- coding: utf-8 -*-
+"""Module for imposing nonlinearity (inverse of relative gains) for each 
+pixel of a frame.
+
+Relative gain is dependent on both the detector gain and the dn count
+value of a given pixel.
+"""
+
+import numpy as np
+from scipy import interpolate
+
+
+class NonlinException(Exception):
+    """Exception class for nonlin module."""
+
+
+def _parse_file(nonlin_path):
+    """Get data from nonlinearity correction file."""
+    # Read nonlin csv
+    nonlin_raw = np.genfromtxt(nonlin_path, delimiter=',')
+
+    # File format checks
+    if nonlin_raw.ndim < 2 or nonlin_raw.shape[0] < 2 or \
+       nonlin_raw.shape[1] < 2:
+        raise NonlinException('Nonlin array must be at least 2x2 (room for x '
+                              'and y axes and one data point)')
+    if not np.isnan(nonlin_raw[0, 0]):
+        raise NonlinException('First value of csv (upper left) must be set to '
+                              '"nan"')
+
+    # Column headers are gains, row headers are dn counts
+    gain_ax = nonlin_raw[0, 1:]
+    count_ax = nonlin_raw[1:, 0]
+    # Array is relative gain values at a given dn count and gain
+    relgains = nonlin_raw[1:, 1:]
+
+    # Check for increasing axes
+    if np.any(np.diff(gain_ax) <= 0):
+        raise NonlinException('Gain axis (column headers) must be increasing')
+    if np.any(np.diff(count_ax) <= 0):
+        raise NonlinException('Counts axis (row headers) must be increasing')
+    # Check that curves (data in columns) contain or straddle 1.0
+    if (np.min(relgains, axis=0) > 1).any() or \
+       (np.max(relgains, axis=0) < 1).any():
+        raise NonlinException('Gain curves (array columns) must contain or '
+                              'straddle a relative gain of 1.0')
+
+    return gain_ax, count_ax, relgains
+
+
+def apply_relgains(frame, em_gain, nonlin_path):
+    """For a given bias-subtracted flattened frame of dn counts, 
+    return a same-size array of inverse relative gain values.  
+    "Relative gain" here is the value 
+    to correct for nonlinearity, the values from the input at nonlin_path, but 
+    since this function applies nonlinearity, it returns the corresponding 
+    inverse values.
+
+    The required format for the file specified at nonlin_path is as follows:
+     - CSV
+     - Minimum 2x2
+     - First value (top left) must be assigned to nan
+     - Row headers (dn counts) must be monotonically increasing
+     - Column headers (EM gains) must be monotonically increasing
+     - Data columns (relative gain curves) must straddle 1
+
+    For example:
+
+    [
+        [nan,  1,     10,    100,   1000 ],
+        [1,    0.900, 0.950, 0.989, 1.000],
+        [1000, 0.910, 0.960, 0.990, 1.010],
+        [2000, 0.950, 1.000, 1.010, 1.050],
+        [3000, 1.000, 1.001, 1.011, 1.060],
+    ],
+
+    where the row headers [1, 1000, 2000, 3000] are dn counts, the column
+    headers [1, 10, 100, 1000] are EM gains, and the first data column
+    [0.900, 0.910, 0.950, 1.000] is the first of the four relative gain curves.
+
+    Parameters
+    ----------
+    frame : array_like
+        Flattened array of dn count values.
+    em_gain : float
+        Detector EM gain.
+    nonlin_path : str
+        Full path of nonlinearity calibration csv.
+
+    Returns
+    -------
+    array_like
+        Flattened array of inverse relative gain values.
+
+    Notes
+    -----
+    This algorithm contains two interpolations:
+
+     - A 2d interpolation to find the relative gain curve for a given EM gain
+     - A 1d interpolation to find a relative gain value for each given dn
+     count value.
+
+    Both of these interpolations are linear, and both use their edge values as
+    constant extrapolations for out of bounds values.
+
+    """
+
+    # Get file data
+    gain_ax, count_ax, relgains = _parse_file(nonlin_path)
+
+    # Create interpolation for em gain (x), counts (y), and relative gain (z).
+    # Note that this defaults to using the edge values as fill_value for
+    # out of bounds values (same as specified below in interp1d)
+    f = interpolate.RectBivariateSpline(gain_ax,
+                                    count_ax,
+                                    relgains.T,
+                                    kx=1,
+                                    ky=1,
+    )
+    # Get the relative gain curve for the given gain value
+    relgain_curve = f(em_gain, count_ax)[0]
+
+    # Create interpolation for dn counts (x) and relative gains (y). For
+    # out of bounds values use edge values
+    ff = interpolate.interp1d(count_ax, relgain_curve, kind='linear',
+                              bounds_error=False,
+                              fill_value=(relgain_curve[0], relgain_curve[-1]))
+    # For each dn count, find the inverse of the relative gain since
+    # we are applying nonlinearity instead of correcting for it
+    counts_flat = 1/ff(frame)
+
+    return counts_flat

{emccd_detect-2.2.5 → emccd_detect-2.3.0}/emccd_detect.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: emccd_detect
-Version: 2.2.5
+Version: 2.3.0
 Summary: EMCCD detector image simulation
 Home-page: https://github.jpl.nasa.gov/WFIRST-CGI/emccd_detect
 Author: Bijan Nemati, Sam Miller, Kevin Ludwick
@@ -22,12 +22,12 @@ Requires-Dist: pyyaml
 
 # EMCCD Detect
 
-Given an input fluxmap, emccd_detect will return a simulated EMCCD detector image.
+Given an input fluxmap, emccd_detect will return a simulated EMCCD detector image.  Website:  (<https://github.com/roman-corgi/emccd_detect/tree/master/emccd_detect>)
 
 
 # Version
 
-The latest version of emccd\_detect is 2.2.5.
+The latest version of emccd\_detect is 2.3.0.
 
 
 ## Getting Started

{emccd_detect-2.2.5 → emccd_detect-2.3.0}/emccd_detect.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ setup.py
 emccd_detect/__init__.py
 emccd_detect/cosmics.py
 emccd_detect/emccd_detect.py
+emccd_detect/nonlinearity.py
 emccd_detect/rand_em_gain.py
 emccd_detect.egg-info/PKG-INFO
 emccd_detect.egg-info/SOURCES.txt