emccd-detect 2.2.5__py3-none-any.whl

emccd_detect/rand_em_gain.py

@@ -0,0 +1,187 @@
+# -*- coding: utf-8 -*-
+"""Generate random numbers according to EM gain pdfs."""
+
+import numpy as np
+from scipy import special
+
+
+class RandEMGainException(Exception):
+    """Exception class for rand_em_gain module."""
+
+
+def rand_em_gain(n_in_array, em_gain):
+    """Generate random numbers according to EM gain pdfs.
+
+    Parameters
+    ----------
+    n_in_array : array_like
+        Array of electron values (e-).
+    em_gain : float
+        CCD em_gain (e-/photon).
+
+    Returns
+    -------
+    array_like
+        Electron values multiplied by random EM gain distribution (e-).
+
+    Notes
+    -----
+    This function returns an array of the same size as n_in_array. Every element
+    in n_in_array is multiplied by em_gain*rand_val, where rand_val is a random
+    number drawn from a specific pdf selected based on the value of the
+    n_in_array element.
+
+    References
+    ----------
+    [1] http://matlabtricks.com/post-44/generate-random-numbers-with-a-given-distribution
+    [2] https://arxiv.org/pdf/astro-ph/0307305.pdf
+
+    """
+    if em_gain < 1:
+        raise RandEMGainException('EM gain cannot be set to less than 1')
+    elif em_gain == 1:
+        return n_in_array
+    else:
+        # Apply gain to regular counts
+        n_out_array = np.random.gamma(n_in_array, em_gain)
+        n_out_array = np.round(n_out_array)
+        return n_out_array
+
+
+
+
+if __name__ == '__main__':
+    import time
+    import matplotlib.pyplot as plt
+
+    # Generally, the agreement b/w the old and new methods is good.  The new
+    # method just speeds up the code a lot, especially when cosmics are present.
+    # Old method functions below:
+
+    def _apply_gain(n_in_array, em_gain, max_out):
+        """Apply a specific em_gain to all nonzero n_in values."""
+        # Initialize output count array
+        n_out_array = np.zeros_like(n_in_array)
+
+        # Get unique nonzero n_in values
+        n_in_unique = np.unique(n_in_array)
+        n_in_unique = n_in_unique[n_in_unique > 0]
+
+        # Generate random numbers according to the gain distribution for each n_in
+        for n_in in n_in_unique:
+            inds = np.where(n_in_array == n_in)[0]
+            n_out_array[inds] = _rand_pdf(n_in, em_gain, max_out, len(inds))
+
+        # n_out_array = np.random.gamma(n_in_array, em_gain)
+        # n_out_array = np.round(n_out_array)
+
+        return n_out_array
+
+
+    def _rand_pdf(n_in, em_gain, x_max, size):
+        """Draw samples from the EM gain distribution."""
+        x = np.random.random(size)
+
+        # Use exact solutions for n_in == 1 and 2
+        if n_in == 1:
+            n_out = -em_gain * np.log(1 - x)
+        elif n_in == 2:
+            n_out = -em_gain * special.lambertw((x-1)/np.exp(1), -1).real - em_gain
+        else:
+            # For n > 2 use CDF approximation
+            # Use x values ranging from 0 to maximum allowable x output
+            x_axis = np.arange(0, x_max).astype(float)
+            x_axis[0] = np.finfo(float).eps  # Use epsilon to avoid divide by 0
+            cdf = _get_cdf(n_in, em_gain, x_axis)
+
+            if cdf is None:
+                # If cdf maxes out, return maximum value
+                n_out = np.ones_like(x) * x_max
+            else:
+                # Draw random samples from the CDF
+                cdf_lookups = (cdf.max() - cdf.min()) * x + cdf.min()
+                n_out = x_axis[np.searchsorted(cdf, cdf_lookups)]  # XXX This could be made more accurate
+
+        return np.round(n_out)
+
+
+    def _get_cdf(n_in, em_gain, x):
+        """Return an approximate CDF for the EM gain distribution.
+
+        Basden 2003 probability distribution function is as follows:
+
+            pdf = x^(n_in-1) * exp(-x/g) / (g^n_in * factorial(n_in-1))
+
+        """
+        # Because of the cancellation of very large numbers, first work in log space
+        logpdf = (n_in-1)*np.log(x) - x/em_gain - n_in*np.log(em_gain) - special.gammaln(n_in)
+        pdf = np.exp(logpdf)
+
+        # XXX This is a rough but safe solution
+        sum_pdf = np.sum(pdf)
+        if sum_pdf == 0:
+            cdf = None
+        else:
+            cdf = np.cumsum(pdf / sum_pdf)
+
+        return cdf
+
+    def compare_stats(g, n, n_samples, max_val, num_bins, plot=False):
+
+        n_in_array = np.array([n]*n_samples)
+        old_method = _apply_gain(n_in_array, g, max_val)
+
+        # gamma distribution:
+        x = rand_em_gain(n_in_array, g)
+
+        print("For n={}, g={}:".format(n,g))
+        print('Mean for old method:  ', np.mean(old_method))
+        print('Std dev for old method:  ', np.std(old_method))
+        print('Mean of gamma distribution:  ', np.mean(x))
+        print('Std dev for gamma distribution:  ', np.std(x))
+        print('theoretical mean:  ', g*n)
+        print('theortical std dev:  ', g*np.sqrt(n))
+        print()
+
+        if plot==True:
+            fig, ax = plt.subplots()
+            H = ax.hist(old_method, bins = num_bins)
+            ax.set_ylabel('number of occurrences')
+            ax.set_xlabel('gained counts (e-)')
+            ax.set_title('Histogram of Gained Counts (Old Method, n={})'.format(n))
+
+            fig, ax = plt.subplots()
+            H = ax.hist(x, bins = num_bins)
+            ax.set_ylabel('number of occurrences')
+            ax.set_xlabel('gained counts (e-)')
+            ax.set_title('Histogram of Gained Counts (Gamma Distribution, n={})'.format(n))
+
+            plt.show()
+
+    g = 2 #20 #200
+    n_samples = 10000
+    #max_val = 200000
+    num_bins = 40
+    # let max_out be the mean + 4*std dev from gamma dist for the max value
+    # from serial_counts (using ENF ~ sqrt(2), which is fine even for low
+    # gain since we just want an upper limit)
+    def max_val(g, n):
+        return g*n + 4*g*np.sqrt(2*n)
+
+    # in original code, max_val used max(n_in_array) where that array was for
+    # all serial cells; so artifically inflate by multiplying by 100
+    n = 1
+    compare_stats(g, n, n_samples, 100*max_val(g,n), num_bins)
+
+    n2 = 2
+    compare_stats(g, n2, n_samples, 100*max_val(g,n), num_bins)
+
+    # now a value of n for which these methods differed
+    n3 = 3
+    compare_stats(g, n3, n_samples, 100*max_val(g,n), num_bins)
+
+    n4 = 40
+    compare_stats(g, n4, n_samples, 100*max_val(g,n), num_bins)
+
+    n5 = 100
+    compare_stats(g, n5, n_samples, 100*max_val(g,n), num_bins)

emccd_detect/util/__init__.py

@@ -0,0 +1 @@
+# -*- coding: utf-8 -*-

emccd_detect/util/metadata.yaml

@@ -0,0 +1,60 @@
+# Any regions not specified are assumed to be shielded or unused pixels.
+#
+# Geometry regions are defined as:
+#   rows: number of region rows
+#   cols: number of region columns
+#   r0c0: coordinates (row, col) of the corner closest to (0, 0) of the array
+#
+# For example, in a 5x5 array, the following geometry would look as follows:
+#   rows: 2
+#   cols: 3
+#   r0c0:
+#     - 2
+#     - 1
+#
+# [
+#     [0, 0, 0, 0, 0],
+#     [0, 0, 0, 0, 0],
+#     [0, 1, 1, 1, 0],
+#     [0, 1, 1, 1, 0],
+#     [0, 0, 0, 0, 0]
+# ]
+#
+# where (0, 0) is defined as the top left of this array.
+frame_rows: 1200
+frame_cols: 2200
+geom:
+  image:
+    rows: 1024
+    cols: 1024
+    r0c0:
+      - 13
+      - 1088
+  prescan:
+    rows: 1200
+    cols: 1088
+    # good, reliable cols used for getting row-by-row bias, relative to r0c0
+    col_start: 800
+    col_end: 1000
+    r0c0:
+      - 0
+      - 0
+  parallel_overscan:
+    rows: 163
+    cols: 1056
+    r0c0:
+      - 1037
+      - 1088
+  serial_overscan:
+    rows: 1200
+    cols: 56
+    r0c0:
+      - 0
+      - 2144
+eperdn: 8.2
+fwc: 105000 #serial
+sat_thresh: 0.99
+plat_thresh: 0.85
+cosm_filter: 2
+tail_filter: #5
+cic_thresh: #100

emccd_detect/util/read_metadata.py

@@ -0,0 +1,90 @@
+# -*- coding: utf-8 -*-
+"""Detector geometry metadata."""
+
+import yaml
+
+
+class ReadMetadataException(Exception):
+    """Exception class for read_metadata module."""
+
+
+class Metadata(object):
+    """Create masks for different regions of the WFIRST CGI EMCCD detector.
+
+    Parameters
+    ----------
+    meta_path : str
+        Full path of metadta yaml.
+
+    Attributes
+    ----------
+    data : dict
+        Data from metadata file.
+    geom : SimpleNamespace
+        Geometry specific data.
+    eperdn : float
+        Electrons per dn conversion factor (detector k gain).
+    fwc : float
+        Full well capacity of detector.
+    sat_thresh : float
+        Multiplication factor for fwc that determines saturated cosmic pixels.
+    plat_thresh : float
+        Multiplication factor for fwc that determines edges of cosmic plateu.
+    cosm_filter : int
+        Minimum length in pixels of cosmic plateus to be identified.
+    tail_filter : int
+        Moving median filter window size for cosmic tail subtraction.
+    cic_thresh : float
+        Multiplication factor for readnoise that determines beginning of cic.
+
+    B Nemati and S Miller - UAH - 03-Aug-2018
+
+    """
+
+    def __init__(self, meta_path):
+        self.meta_path = meta_path
+
+        self.data = self.get_data()
+        self.frame_rows = self.data['frame_rows']
+        self.frame_cols = self.data['frame_cols']
+        self.geom = self.data['geom']
+        self.eperdn = self.data['eperdn']
+        self.fwc = self.data['fwc']
+        self.sat_thresh = self.data['sat_thresh']
+        self.plat_thresh = self.data['plat_thresh']
+        self.cosm_filter = self.data['cosm_filter']
+        self.tail_filter = self.data['tail_filter']
+        self.cic_thresh = self.data['cic_thresh']
+
+    def get_data(self):
+        """Read yaml data into dictionary."""
+        with open(self.meta_path, 'r') as stream:
+            data = yaml.safe_load(stream)
+        return data
+
+    def slice_section(self, frame, key):
+        """Slice 2d section out of frame.
+
+        Parameters
+        ----------
+        frame : array_like
+            Full frame consistent with size given in frame_rows, frame_cols.
+        key : str
+            Keyword referencing section to be sliced; must exist in geom.
+
+        """
+        rows, cols, r0c0 = self._unpack_geom(key)
+
+        section = frame[r0c0[0]:r0c0[0]+rows, r0c0[1]:r0c0[1]+cols]
+        if section.size == 0:
+            raise ReadMetadataException('Corners invalid')
+        return section
+
+    def _unpack_geom(self, key):
+        """Safely check format of geom sub-dictionary and return values."""
+        coords = self.geom[key]
+        rows = coords['rows']
+        cols = coords['cols']
+        r0c0 = coords['r0c0']
+
+        return rows, cols, r0c0

emccd_detect/util/read_metadata_wrapper.py

@@ -0,0 +1,157 @@
+"""Wrapper for read_metadata to allow use in emccd_detect simulator."""
+
+import numpy as np
+
+from emccd_detect.util.read_metadata import Metadata
+
+
+class ReadMetadataWrapperException(Exception):
+    """Exception class for read_metadata_wrapper module."""
+
+
+class MetadataWrapper(Metadata):
+    """Wrapper for Metadata class to add functionality for emccd_detect.
+
+    Parameters
+    ----------
+    meta_path : str
+        Full path of metadta yaml.
+
+    Attributes
+    ----------
+    data : dict
+        Data from metadata file.
+    geom : SimpleNamespace
+        Geometry specific data.
+    eperdn : float
+        Electrons per dn conversion factor (detector k gain).
+    fwc : float
+        Full well capacity of detector.
+    sat_thresh : float
+        Multiplication factor for fwc that determines saturated cosmic pixels.
+    plat_thresh : float
+        Multiplication factor for fwc that determines edges of cosmic plateu.
+    cosm_filter : int
+        Minimum length in pixels of cosmic plateus to be identified.
+    tail_filter : int
+        Moving median filter window size for cosmic tail subtraction.
+    cic_thresh : float
+        Multiplication factor for readnoise that determines beginning of cic.
+
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+        # Get imaging area geometry
+        self.rows_im, self.cols_im, self.r0c0_im = self._imaging_area_geom()
+
+        # Make some zeros frames for initial creation of arrays
+        self.imaging_area_zeros = np.zeros((self.rows_im, self.cols_im))
+        self.full_frame_zeros = np.zeros((self.frame_rows, self.frame_cols))
+
+    def mask(self, key):
+        full_frame_m = self.full_frame_zeros.copy()
+
+        rows, cols, r0c0 = self._unpack_geom(key)
+        full_frame_m[r0c0[0]:r0c0[0]+rows, r0c0[1]:r0c0[1]+cols] = 1
+        return full_frame_m.astype(bool)
+
+    def embed(self, frame, key, data):
+        rows, cols, r0c0 = self._unpack_geom(key)
+        try:
+            frame[r0c0[0]:r0c0[0]+rows, r0c0[1]:r0c0[1]+cols] = data
+        except Exception:
+            raise ReadMetadataWrapperException('Data does not fit in selected '
+                                               'section')
+        return frame
+
+    def embed_im(self, im_area, key, data):
+        rows, cols, r0c0 = self._unpack_geom_im(key)
+        try:
+            im_area[r0c0[0]:r0c0[0]+rows, r0c0[1]:r0c0[1]+cols] = data
+        except Exception:
+            raise ReadMetadataWrapperException('Data does not fit in selected '
+                                               'section')
+        return im_area
+
+    def imaging_slice(self, frame):
+        """Select only the real counts from full frame and exclude virtual.
+
+        Use this to transform mask and embed from acting on the full frame to
+        acting on only the image frame.
+
+        """
+        rows, cols, r0c0 = self._imaging_area_geom()
+
+        return frame[r0c0[0]:r0c0[0]+rows, r0c0[1]:r0c0[1]+cols]
+
+    def imaging_embed(self, frame, im_area):
+        """Add the imaging area back to the full frame."""
+        rows, cols, r0c0 = self._imaging_area_geom()
+
+        frame[r0c0[0]:r0c0[0]+rows, r0c0[1]:r0c0[1]+cols] = im_area
+        return frame
+
+    def _unpack_geom_corners(self, key):
+        """Returns corners corresponding to geometry."""
+        rows, cols, r0c0 = self._unpack_geom(key)
+        r1c1 = (r0c0[0]+rows-1, r0c0[1]+cols-1)
+
+        return r0c0, r1c1
+
+    def _unpack_geom_im(self, key):
+        """Wrapper for _unpack_geom, transforms r0c0 locations from full frame
+        coords to imaging area coords.
+
+        """
+        # Unpack geomotry of requested section
+        rows, cols, r0c0_original = self._unpack_geom(key)
+        # Unpack geometry of imaging area
+        _, _, r0c0_im = self._imaging_area_geom()
+
+        # Shift r0c0 locations by the r0c0 of the imaging area
+        r0c0 = r0c0_original.copy()
+        r0c0[0] -= r0c0_im[0]
+        r0c0[1] -= r0c0_im[1]
+
+        # Make sure new geom is valid
+        pass
+
+        return rows, cols, r0c0
+
+    def _imaging_area_geom(self):
+        """Return geometry of imaging area in reference to full frame."""
+        _, cols_pre, _ = self._unpack_geom('prescan')
+        _, cols_serial_ovr, _ = self._unpack_geom('serial_overscan')
+        rows_parallel_ovr, _, _ = self._unpack_geom('parallel_overscan')
+        #_, _, r0c0_image = self._unpack_geom('image')
+        fluxmap_rows, _, r0c0_image = self._unpack_geom('image')
+
+        rows_im = self.frame_rows - rows_parallel_ovr
+        cols_im = self.frame_cols - cols_pre - cols_serial_ovr
+        r0c0_im = r0c0_image.copy()
+        r0c0_im[0] = r0c0_im[0] - (rows_im - fluxmap_rows)
+
+        return rows_im, cols_im, r0c0_im
+
+    def slice_section_im(self, im_area, key):
+        """Slice 2d section out of imaging area of frame.
+
+        Parameters
+        ----------
+        im_area : array_like
+            Imaging area of frame, i.e. the full frame with the prescan and
+            overscan removed:
+                full_frame[:overscan[r0c0[0]], overscan[r0c0[1]]:]
+        key : str
+            Keyword referencing section to be sliced; must exist in geom and
+            must not be 'prescan' or 'overscan'.
+
+        """
+        rows, cols, r0c0 = self._unpack_geom_im(key)
+
+        section = im_area[r0c0[0]:r0c0[0]+rows, r0c0[1]:r0c0[1]+cols]
+        if section.size == 0:
+            raise ReadMetadataWrapperException('Corners invalid')
+        return section

emccd_detect-2.2.5.dist-info/METADATA

@@ -0,0 +1,69 @@
+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>)
+

emccd_detect-2.2.5.dist-info/RECORD

@@ -0,0 +1,12 @@
+emccd_detect/__init__.py,sha256=rQ0MYUU5kTHWjOTy7kyoV4spMKntp-VbXP69qDLTRwI,45
+emccd_detect/cosmics.py,sha256=wRE47QOB3fwxkH5PHTeoyLjJ0fgJki6Z8hLDPx2h3SQ,3991
+emccd_detect/emccd_detect.py,sha256=x8At7uER_ccsdjO6DHq9mLdrKdO71CcdcBdnl1YdBgE,22363
+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.2.5.dist-info/WHEEL

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

emccd_detect-2.2.5.dist-info/top_level.txt

@@ -0,0 +1 @@
+emccd_detect