Charge Collection models

Charge Collection models#

Charge collection models are used to add to and manipulate data in Pixel array inside the Detector object. The data represents amount of charge stored in each of the pixels. A charge collection model, e.g. Simple collection, is necessary to first convert from charge data stored in Charge class to pixel stored in Pixel. Multiple models are available to add detector effects after.

Create and Store a detector#

The models Save detector and Load detector can be used respectively to create and to store a Detector to/from a file.

These models can be used when you want to store or to inject a Detector into the current Pipeline.

Save detector#

This model saves the current Detector into a file. Accepted file formats are .h5, .hdf5, .hdf and .asdf.

- name: save_detector
  func: pyxel.models.save_detector
  enabled: true
  arguments:
    filename: my_detector.h5
pyxel.models.save_detector(detector, filename)[source]

Save the current detector into a file.

Load detector#

This model loads a Detector from a file and injects it in the current pipeline. Accepted file formats are .h5, .hdf5, .hdf and .asdf.

- name: load_detector
  func: pyxel.models.load_detector
  enabled: true
  arguments:
    filename: my_detector.h5
pyxel.models.load_detector(detector, filename)[source]

Load a new detector from a file.

Raises:

TypeError – If the loaded detector has not the same type of the current detector.

Simple collection#

Charge → Pixel

Simple collection model is the simplest model of charge collection and necessary to fill up Pixel array when no other collection model is used. If charge inside Charge class is stored in an numpy array, arrays will be the same. If charge is in the form of Pandas dataframe and representing 3D point cloud of charges inside the detector, calling array property of Charge will assign charges to the closest pixel and sum the values.

Example of YAML configuration model:

- name: simple_collection
  func: pyxel.models.charge_collection.simple_collection
  enabled: true
pyxel.models.charge_collection.simple_collection(detector)[source]#

Associate charge with the closest pixel.

Parameters:

detector (Detector) – Pyxel Detector object.

Simple full well#

Pixel → Pixel

This model can be used to limit the amount of charge in Pixel array due to full well capacity. Values will be clipped to the value of the full well capacity. The model uses full well capacity value specified in Characteristics of the Detector, unless providing an argument fwc directly as the model argument.

Example of the configuration file:

- name: simple_full_well
  func: pyxel.models.charge_collection.simple_full_well
  enabled: true
  arguments:
      fwc: 1000  # optional
pyxel.models.charge_collection.simple_full_well(detector, fwc=None)[source]#

Limit the amount of charge in pixel due to full well capacity.

Uses full well capacity in the characteristics of the detector object if not overridden by the function argument.

Parameters:

  • detector (Detector)

  • fwc (int)

Fixed pattern noise#

Pixel → Pixel

With this model you can multiply Pixel array with fixed pattern noise caused by pixel non-uniformity during charge collection. User has to provide a filename or a fixed-pattern nise factor to model arguments. Accepted file formats for the noise are .npy, .fits, .txt, .data, .jpg, .jpeg, .bmp, .png and .tiff. Use argument position to set the offset from (0,0) pixel and set where the noise is placed onto detector. You can set preset positions with argument align. Values outside of detector shape will be cropped. Read more about placement in the documentation of function fit_into_array(). If the user provides a value for the fixed_pattern_noise_factor instead of a filename, the model will use a simple calculation of the PRNU. In the simple calculation the fixed_pattern_noise_factor will be multiplied with the quantum_efficiency, given by the detector characteristics, and applied to the pixel array through a lognormal distribution. The fixed_pattern_noise_factor is typically between 0.01 and 0.02 for a given sensor, but varies from one sensor to another [12].

Basic example of the configuration file:

- name: fixed_pattern_noise
  func: pyxel.models.charge_collection.fixed_pattern_noise
  enabled: true
  arguments:
      filename: "noise.fits"
      #fixed_pattern_noise_factor: 0.01
pyxel.models.charge_collection.fixed_pattern_noise(detector, filename=None, position=(0, 0), align=None, fixed_pattern_noise_factor=None, seed=None)[source]#

Add fixed pattern noise caused by pixel non-uniformity during charge collection.

Parameters:

  • detector (Detector) – Pyxel Detector object.

  • filename (str or Path or None) – Path to a file with an array or an image.

  • position (tuple) – Indices of starting row and column, used when fitting noise to detector.

  • align (Literal) – Keyword to align the noise to detector. Can be any from: (“center”, “top_left”, “top_right”, “bottom_left”, “bottom_right”)

  • fixed_pattern_noise_factor (float, optional) – Fixed pattern noise factor.

  • seed (int, optional) – Random seed.

Raises:

ValueError – If no filename and no fixed_pattern_noise_factor is giving or both are giving.

Inter-pixel capacitance#

Note

This model is specific for the CMOS detector.

Pixel → Pixel

This model can be used to apply inter-pixel capacitance to Pixel array. When there is IPC, the signal read out on any pixel is affected by the signal in neighboring pixels. The IPC affects the point spread function (PSF) of the optical system, modiying the shape of the objects. More about the IPC and the math describing it can be found in [3]. The amount of coupling between the pixels is described in the article by a \(3\times3\) matrix \(K_{\alpha, \alpha_+, \alpha'}\):

\[\begin{split}K_{\alpha, \alpha_+, \alpha'} = \begin{bmatrix} \alpha' & \alpha-\alpha_+ & \alpha'\\ \alpha+\alpha_+ & 1-4(\alpha+\alpha') & \alpha+\alpha_+\\ \alpha' & \alpha-\alpha_+ & \alpha' \end{bmatrix},\end{split}\]

where \(\alpha\) is the coupling parameter for the neighbouring pixels, \(\alpha'\) the coupling parameter for the pixels located on the diagonals and \(\alpha_+\) parameter for introducing an anisotropical coupling. In the model, the last two are optional. The sum of the matrix elements is always 1. The result image that is seen on the detector is a convolution of the image with the kernel matrix, which is done using astropy convolution tools.

Example of the configuration file:

- name: simple_ipc
  func: pyxel.models.charge_collection.simple_ipc
  enabled: true
  arguments:
      coupling: 0.1
      diagonal_coupling: 0.05
      anisotropic_coupling: 0.03

Note

You can find examples of this model in these Jupyter Notebooks from Pyxel Data:

pyxel.models.charge_collection.simple_ipc(detector, coupling, diagonal_coupling=0.0, anisotropic_coupling=0.0)[source]#

Convolve pixel array with the IPC kernel.

Parameters:

Notes

For more information, you can find examples here:

Simple Persistence#

Note

This model is specific for the CMOS detector.

Pixel → Pixel

With this model you can simulate the effect of persistence changing Pixel array. The simple model takes as input a list of trap time constants together with a list of trap densities and assuming the trap densities are uniform over the whole detector area. Additionally user can also specify trap full well capacities using the trap_capacities parameter. At each iteration of the pipeline, the model will compute the amount of trapped charges in this iteration, add it to the memory of the detector and then remove this amount from the pixel array. More on the persistence model can be found in [18].

Example of the configuration file:

- name: simple_persistence
  func: pyxel.models.charge_collection.simple_persistence
  enabled: true
  arguments:
    trap_time_constants: [1., 10.]  # Two different traps
    trap_densities: [0.307, 0.175]
    trap_capacities: [100., 100.]  # optional

Note

You can find an example of this model used in this Jupyter Notebook H2RG pipeline from Pyxel Data.

pyxel.models.charge_collection.simple_persistence(detector, trap_time_constants, trap_densities, trap_capacities=None)[source]#

Apply simple persistence model.

Parameters:

  • detector (CMOS) – Pyxel CMOS object.

  • trap_time_constants (sequence of floats) – List of trap time constants.

  • trap_densities (sequence of floats) – List of trap densities.

  • trap_capacities (sequence of floats, optional) – List of trap capacities.

Notes

For more information, you can find an example here: H2RG pipeline.

Persistence#

Note

This model is specific for the CMOS detector.

Pixel → Pixel

With this model you can simulate the effect of persistence changing Pixel array. The more advanced model takes as input a list of trap time constants together with a list of trap proportions. For trap densities user has to provide a 2D map of densities. This model assumes trap density distribution over the detector area is the same for all traps and the trap densities are computed using the map and trap proportions. Additionally user can also specify trap full well capacity map. At each iteration of the pipeline, the model will compute the amount of trapped charges in this iteration, add it to the memory of the detector and then remove this amount from the pixel array. More on the persistence model can be found in [18].

Use arguments trap_densities_position and trap_capacities_position to set the maps offset from (0,0) pixel and set where the input map is placed onto detector. You can set preset positions with arguments trap_densities_align and trap_capacities_align. Values outside of detector shape will be cropped. Read more about placement in the documentation of function fit_into_array().

Example of the configuration file:

- name: persistence
  func: pyxel.models.charge_collection.persistence
  enabled: true
  arguments:
    trap_time_constants: [1, 10, 100, 1000, 10000]
    trap_proportions: [0.307, 0.175, 0.188, 0.136, 0.194]
    trap_densities_filename: trap_densities.fits
    trap_capacities_filename: trap_capacities.fits  # optional

Note

You can find examples of this model in these Jupyter Notebooks from Pyxel Data:

pyxel.models.charge_collection.persistence(detector, trap_time_constants, trap_proportions, trap_densities_filename, trap_capacities_filename=None, trap_densities_position=(0, 0), trap_densities_align=None, trap_capacities_position=(0, 0), trap_capacities_align=None)[source]#

Apply persistence model.

Parameters:

  • detector (CMOS) – Pyxel CMOS object.

  • trap_time_constants (sequence of floats) – A list of trap time constants.

  • trap_proportions (sequence of floats) – A list of trap proportions.

  • trap_densities_filename (path or str) – Path to densities file.

  • trap_capacities_filename (path or str) – Path to capacities file.

  • trap_densities_position (tuple of int) – Indices of starting row and column, used when fitting densities to detector.

  • trap_densities_align (literal) – Keyword to align the densities to detector. Can be any from: (“center”, “top_left”, “top_right”, “bottom_left”, “bottom_right”)

  • trap_capacities_position (tuple of int) – Indices of starting row and column, used when fitting capacities to detector.

  • trap_capacities_align (literal) – Keyword to align the capacities to detector. Can be any from: (“center”, “top_left”, “top_right”, “bottom_left”, “bottom_right”)

Notes

For more information, you can find examples here:

Contents