emccd-detect 2.2.5__py3-none-any.whl → 2.4.0__py3-none-any.whl

emccd_detect/__init__.py

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

emccd_detect/emccd_detect.py

@@ -9,9 +9,10 @@ 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
+    from arcticpy import add_cti, CCD, ROE, TrapInstantCapture
 except:
     pass
 
@@ -93,12 +94,15 @@ class EMCCDDetectBase:
         self.numel_gain_register = numel_gain_register
 
         # Placeholders for trap parameters
-        self.ccd = None
-        self.roe = None
-        self.traps = None
-        self.express = None
-        self.offset = None
-        self.window_range = None
+        self.parallel_ccd = None
+        self.parallel_roe = None
+        self.parallel_traps = None
+        self.parallel_express = None
+        self.serial_ccd = None
+        self.serial_roe = None
+        self.serial_traps = None
+        self.serial_express = None
+     
 
         # Placeholders for derived values
         self.mean_expected_rate = None
@@ -122,36 +126,72 @@ class EMCCDDetectBase:
     try:
         def update_cti(
             self,
-            ccd=None,
-            roe=None,
-            traps=None,
-            express=1,
-            offset=0,
-            window_range=None
+            parallel_ccd=None,
+            parallel_roe=None,
+            parallel_traps=None,
+            parallel_express=1,
+            serial_ccd=None,
+            serial_roe=None,
+            serial_traps=None,
+            serial_express=1,
+            parallel=True, 
+            serial=True,
+            **kwargs # any other arguments that arcticpy.add_cti() might accept
         ):
+            '''See arcticpy documentation for details on parameters. Any arguments 
+            not explicitly listed here can be handed to arcticpy.add_cti() via
+            kwargs.  
+            
+            Parallel and serial CTI can each be switched on or off via the 
+            "parallel" and "serial" arguments of this function.  True means that 
+            type of CTI is simulated.  Both are True by default.'''
             # Update parameters
-            self.ccd = ccd
-            self.roe = roe
-            self.traps = traps
-
-            self.express = express
-            self.offset = offset
-            self.window_range = window_range
+            self.parallel_ccd = parallel_ccd
+            self.parallel_roe = parallel_roe
+            self.parallel_traps = parallel_traps
+            self.parallel_express = parallel_express
+            self.serial_ccd = serial_ccd
+            self.serial_roe = serial_roe
+            self.serial_traps = serial_traps
+            self.serial_express = serial_express
+            self.kwargs = kwargs
+            self.parallel = parallel
+            self.serial = serial
 
             # Instantiate defaults for any class instances not provided
-            if self.ccd is None:
-                self.ccd = CCD()
-            if roe is None:
-                self.roe = ROE()
-            if traps is None:
+
+            if parallel_ccd is None:
+                self.parallel_ccd = CCD()
+            if parallel_roe is None:
+                self.parallel_roe = ROE()
+            if parallel_traps is None:
                 #self.traps = [Trap()]
-                self.traps = [TrapInstantCapture()]
+                self.parallel_traps = [TrapInstantCapture()]
+            if self.parallel is False: # overrides
+                self.parallel_ccd = None
+                self.parallel_roe = None
+                self.parallel_traps = None
+
+            if serial_ccd is None:
+                self.serial_ccd = CCD()
+            if serial_roe is None:
+                self.serial_roe = ROE()
+            if serial_traps is None:
+                self.serial_traps = [TrapInstantCapture()]
+            if self.serial is False: #overrides
+                self.serial_ccd = None
+                self.serial_roe = None
+                self.serial_traps = None
 
         def unset_cti(self):
+            '''This turns off all CTI implementation.'''
             # Remove CTI simulation
-            self.ccd = None
-            self.roe = None
-            self.traps = None
+            self.parallel_ccd = None
+            self.parallel_roe = None
+            self.parallel_traps = None
+            self.serial_ccd = None
+            self.serial_roe = None
+            self.serial_traps = None
     except:
         pass
 
@@ -224,16 +264,26 @@ class EMCCDDetectBase:
 
     def clock_parallel(self, actualized_e):
         # Only add CTI if update_cti has been called
-        if self.ccd is not None and self.roe is not None and self.traps is not None:
-            parallel_counts = add_cti(
-                actualized_e.copy(),
-                parallel_roe=self.roe,
-                parallel_ccd=self.ccd,
-                parallel_traps=self.traps,
-                parallel_express=self.express,
-                parallel_offset=self.offset,
-                parallel_window_range=self.window_range
-            )
+        if self.parallel_ccd is not None and self.parallel_roe is not None and self.parallel_traps is not None:
+            try:
+                parallel_counts = add_cti(
+                    actualized_e.copy(),
+                    parallel_roe=self.parallel_roe,
+                    parallel_ccd=self.parallel_ccd,
+                    parallel_traps=self.parallel_traps,
+                    parallel_express=self.parallel_express,
+                    **self.kwargs
+                )
+            except:
+                parallel_counts = add_cti(
+                    actualized_e.copy(),
+                    parallel_roe=self.parallel_roe,
+                    parallel_ccd=self.parallel_ccd,
+                    parallel_traps=self.parallel_traps,
+                    parallel_express=self.parallel_express,
+                    parallel_window_range=0,
+                    **self.kwargs
+                )
         else:
             parallel_counts = actualized_e
 
@@ -241,12 +291,37 @@ class EMCCDDetectBase:
 
     def clock_serial(self, actualized_e_full, empty_element_m):
         # Actualize cic electrons in prescan and overscan pixels
-        # XXX Another place where we are fudging a little
+        # XXX Another place where we are fudging a little as far as the order of operations(?)
         actualized_e_full[empty_element_m] = np.random.poisson(actualized_e_full[empty_element_m]
                                                                + self.cic)
-        # XXX Call arcticpy here
+        
+        # add serial CTI; the addition of CIC (serial and parallel) is really 
+        # *during* the addition of CTI, but this corrective effect would not be very significant 
+        if self.serial_ccd is not None and self.serial_roe is not None and self.serial_traps is not None:
+            try:
+                cti_actualized_e_full = add_cti(
+                        actualized_e_full.copy(),
+                        serial_roe=self.serial_roe,
+                        serial_ccd=self.serial_ccd,
+                        serial_traps=self.serial_traps,
+                        serial_express=self.serial_express,
+                        **self.kwargs
+                    )
+            except:
+                cti_actualized_e_full = add_cti(
+                        actualized_e_full.copy(),
+                        serial_roe=self.serial_roe,
+                        serial_ccd=self.serial_ccd,
+                        serial_traps=self.serial_traps,
+                        serial_express=self.serial_express,
+                        serial_window_range=0,
+                        **self.kwargs
+                    )
+        else:
+            cti_actualized_e_full = actualized_e_full
+
         # Flatten row by row
-        actualized_e_full_flat = actualized_e_full.ravel()
+        actualized_e_full_flat = cti_actualized_e_full.ravel()
 
         # Clock electrons through serial register elements
         serial_counts = self._serial_register_elements(actualized_e_full_flat)
@@ -260,7 +335,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 +476,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 +527,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 +551,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 +569,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/nonlinearity.py

@@ -0,0 +1,134 @@
+# -*- 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.
+
+Adapted from https://github.com/roman-corgi/cgi_iit_drp/blob/main/proc_cgi_frame_NTR/proc_cgi_frame/gsw_nonlin.py.
+"""
+
+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.4.0.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.1
+Name: emccd_detect
+Version: 2.4.0
+Summary: EMCCD detector image simulation
+Author: Bijan Nemati, Sam Miller, Kevin Ludwick
+Author-email: bijan.nemati@tellus1.com, sam.miller@uah.edu, kevin.ludwick@uah.edu
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Requires-Dist: astropy
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: pynufft ==2020.0.0
+Requires-Dist: pyyaml
+
+# EMCCD Detect
+
+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.4.0.  Main differences from previous version: the ability to implement readout nonlinearity and the latest version of arcticpy for charge transfer inefficiency implementation.
+
+
+## Getting Started
+### Installing
+
+This package requires Python version 3.6 or higher.  If the user wants the ability to apply charge transfer inefficiency (CTI) to detector frames using the optional tool (older version of arcticpy which is pure Python) provided in emccd\_detect, then the Python version should be >=3.6 and <=3.9.  If the newer version of arcticpy (wrapper around C++ code) is installed, there is no upper limit restriction for Python version. For installation instructions and documentation for the newer arcticpy, see <https://github.com/jkeger/arctic>. emccd\_detect works apart from arcticpy and does not require it.
+
+emccd\_detect is available on PyPI.org, so the following command will install the module (without CTI capabilities):
+
+	pip install emccd-detect
+
+To install emccd\_detect instead from this package download, after downloading, navigate to the emccd\_detect directory where setup.py is located and use
+
+	pip install .
+
+This will install emccd\_detect and its dependencies, which are as follows:
+
+* astropy
+* matplotlib
+* numpy
+* scipy
+* pynufft==2020.0.0
+* pyyaml
+
+To optionally implement CTI capabilities with the pure-Python arcticpy, navigate to the arcticpy directory (<https://github.com/roman-corgi/emccd_detect/tree/master/arcticpy_folder>), and there will be a file called setup.py in that directory.  Use
+
+	pip install .
+
+This will install arcticpy version 1.0.  See (<https://github.com/jkeger/arcticpy/tree/row_wise/arcticpy>) for documentation.  If
+you have Python>3.9, the CTI functionality will not work if you are using the arcticpy installation that was included with this emccd_detect package, but everything else will work fine.
+
+
+### Usage
+
+For an example of how to use emccd\_detect, see example_script.py.
+
+
+## Authors
+
+* Bijan Nemati (<bijan.nemati@tellus1.com>)
+* Sam Miller (<sam.miller@uah.edu>)
+* Kevin Ludwick (<kevin.ludwick@uah.edu>)
+

{emccd_detect-2.2.5.dist-info → emccd_detect-2.4.0.dist-info}/RECORD

@@ -1,12 +1,13 @@
-emccd_detect/__init__.py,sha256=rQ0MYUU5kTHWjOTy7kyoV4spMKntp-VbXP69qDLTRwI,45
+emccd_detect/__init__.py,sha256=FwzLqOGO--eOgOxuK6wCfzsc5yCUneMzLELAeD7Rc7Q,45
 emccd_detect/cosmics.py,sha256=wRE47QOB3fwxkH5PHTeoyLjJ0fgJki6Z8hLDPx2h3SQ,3991
-emccd_detect/emccd_detect.py,sha256=x8At7uER_ccsdjO6DHq9mLdrKdO71CcdcBdnl1YdBgE,22363
+emccd_detect/emccd_detect.py,sha256=iOLp-I6NibxJeZwmb7V5cqo5xZI3BxV5XB-1AcQLnac,26678
+emccd_detect/nonlinearity.py,sha256=DWBGjoShInMXBX0BLj6lT9dlY_lx6pdn8VU84jk_djU,4938
 emccd_detect/rand_em_gain.py,sha256=3eF9T7PNYFZT0coGZwBmNTYz6B9pj2lXxTR8ROG6_7Q,6297
 emccd_detect/util/__init__.py,sha256=iwhKnzeBJLKxpRVjvzwiRE63_zNpIBfaKLITauVph-0,24
 emccd_detect/util/metadata.yaml,sha256=hcKTg4kMy12dfbCmmvZeKEqjeUA3BYiAcZc5vZpc3bE,1149
 emccd_detect/util/read_metadata.py,sha256=r511ENJ6zbIvLDWiVic7KsVXYrBphSdTKUQbuwocjLs,2764
 emccd_detect/util/read_metadata_wrapper.py,sha256=oBh2KpJ-uLTSIY_hPzw8sNIcJ6MENBSf38ks8OaFOSQ,5473
-emccd_detect-2.2.5.dist-info/METADATA,sha256=AtPSg_JzaaRAvEuvGgOSubLj21JNEF0NdReNez9V4kA,2307
-emccd_detect-2.2.5.dist-info/WHEEL,sha256=UvcQYKBHoFqaQd6LKyqHw9fxEolWLQnlzP0h_LgJAfI,91
-emccd_detect-2.2.5.dist-info/top_level.txt,sha256=V0qxOcGf8TowSJXnTxWEMuK9BBsySwhtKNitfdokD0A,13
-emccd_detect-2.2.5.dist-info/RECORD,,
+emccd_detect-2.4.0.dist-info/METADATA,sha256=sX4JDwVH__aNVtFOAliynk1oLCiMwLSokSACT6noa9g,3039
+emccd_detect-2.4.0.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
+emccd_detect-2.4.0.dist-info/top_level.txt,sha256=V0qxOcGf8TowSJXnTxWEMuK9BBsySwhtKNitfdokD0A,13
+emccd_detect-2.4.0.dist-info/RECORD,,

{emccd_detect-2.2.5.dist-info → emccd_detect-2.4.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (74.0.0)
+Generator: setuptools (75.1.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

emccd_detect-2.2.5.dist-info/METADATA

@@ -1,69 +0,0 @@
-Metadata-Version: 2.1
-Name: emccd_detect
-Version: 2.2.5
-Summary: EMCCD detector image simulation
-Home-page: https://github.jpl.nasa.gov/WFIRST-CGI/emccd_detect
-Author: Bijan Nemati, Sam Miller, Kevin Ludwick
-Author-email: bijan.nemati@tellus1.com, sam.miller@uah.edu, kevin.ludwick@uah.edu
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.6
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
-Requires-Python: >=3.6
-Description-Content-Type: text/markdown
-Requires-Dist: astropy
-Requires-Dist: matplotlib
-Requires-Dist: numpy
-Requires-Dist: scipy
-Requires-Dist: pynufft ==2020.0.0
-Requires-Dist: pyyaml
-
-# EMCCD Detect
-
-Given an input fluxmap, emccd_detect will return a simulated EMCCD detector image.
-
-
-# Version
-
-The latest version of emccd\_detect is 2.2.5.
-
-
-## Getting Started
-### Installing
-
-This package requires Python version 3.6 or higher.  If the user wants the ability to apply charge transfer inefficiency (CTI) to detector frames using the optional tool provided in emccd\_detect, then the Python version should be >=3.6 and <=3.9.
-
-To install emccd\_detect, navigate to the emccd\_detect directory where setup.py is located and use
-
-	pip install .
-
-This will install emccd\_detect and its dependencies, which are as follows:
-
-* astropy
-* matplotlib
-* numpy
-* scipy
-* pynufft==2020.0.0
-* pyyaml
-
-To optionally implement CTI capabilities, navigate to the arcticpy directory (<https://github.com/roman-corgi/emccd_detect/tree/master/arcticpy_folder>), and there will be a file called setup.py in that directory.  Use
-
-	pip install .
-
-This will install arcticpy version 1.0, which is an older version of arcticpy which runs purely on Python (<https://github.com/jkeger/arcticpy/tree/row_wise/arcticpy>).  If
-you have Python>=3.10, the CTI functionality will not work if you are using the arcticpy installation that was included with this emccd_detect package, but everything else will work fine.
-
-
-### Usage
-
-For an example of how to use emccd\_detect, see example_script.py.
-
-
-## Authors
-
-* Bijan Nemati (<bijan.nemati@tellus1.com>)
-* Sam Miller (<sam.miller@uah.edu>)
-* Kevin Ludwick (<kevin.ludwick@uah.edu>)
-