WaveformModifier

class ctapipe.image.WaveformModifier(*args: t.Any, **kwargs: t.Any)

Bases: TelescopeComponent

Component to add NSB noise to R1 waveforms.

This component in principle to be applied on MC shower simulations, to make them closer to real data in terms of noise level.

There are two possibilities:

1. The “showers MC” file has dark-NSB settings and electronic noise ( waveform baseline fluctuations), and the input NSB file is a dedicated sim_telarray file, which must be produced with the same telescope array configuration (and other simulation settings) as the showers MC to which the noise is to be added, but containing only NSB noise (electronic fluctuations of the baseline should be switched off)

2. The showers MC file is produced with no noise (baseline fluctuations) of any kind (electronic or NSB), just the Cherenkov signal (with the appropriate single-p.e.-response fluctuations), whereas the nsb file is a real data DL0 file from which only the interleaved pedestals are used (all gain channels must be present for all pixels). In that case, nsb_level must be =1 (to match the MC to the data) and sample_pixels_independently=False (we do not want e.g. to duplicate stars in the FoV).

In case (1), the number of available noise events per telescope in the NSB file must be at least twice the number of waveforms (“nsb_level”) from that file that we want to add up. If the NSB file is produced with a level of 25% of dark NSB, and we want to simulate 10x dark NSB, then nsb_level=40 (=10/0.25) and the file must contain at least 80 events. This is to guarantee that the different noise waveforms are not too correlated

Attributes Summary

n_noise_realizations	Number of different realizations of the total NSB waveform to be created per pixel
nsb_file	Path to a dedicated NSB-only file (e.g. from sim_telarray).
nsb_level	Number of random instances of the NSB waveforms from the NSB file to be added up to the waveform
rng_seed	Seed for the random number generator
sample_pixels_independently	If True, each pixel uses a different random combination of the input noise eventsIf False, all pixels use the same random combination of noise events.

Methods Summary

__call__(event)
check_noise_statistics(nsb_database)	Check that we have enough NSB-only events for all telescopes.
read_nsb_database()	Reads in R1 noise waveforms from an input file self.nsb_file
zero_baseline(nsb_database)	For each telescope and gain we average the waveform values for all pixels, and subtract those averages from the waveforms.

Attributes Documentation

n_noise_realizations

Number of different realizations of the total NSB waveform to be created per pixel

nsb_file

Path to a dedicated NSB-only file (e.g. from sim_telarray)

nsb_level

Number of random instances of the NSB waveforms from the NSB file to be added up to the waveform

rng_seed

Seed for the random number generator

sample_pixels_independently

If True, each pixel uses a different random combination of the input noise eventsIf False, all pixels use the same random combination of noise events. That is, noise events will be combined as full cameras

Methods Documentation

__call__(event)

Parameters:

event: container

A ArrayEventContainer event container

check_noise_statistics(nsb_database)

Check that we have enough NSB-only events for all telescopes. We require that the number of NSB events for any telescope is at least two times the number of waveforms (=nsb_level) that we will add up. This is to avoid excessive correlation among the waveforms.

Parameters:

nsb_database: dict

Dictionary with one key per telescope, containing an array [n_events,

n_gains, n_pixels, n_samples] (noise waveforms)

Returns:

stats_okbool

True if statistics of noise events is considered sufficient

read_nsb_database()

Reads in R1 noise waveforms from an input file self.nsb_file

Returns:

nsb_databasedict

Dictionary with one key per telescope, containing an array [n_events,

n_gains, n_pixels, n_samples] (noise waveforms)

zero_baseline(nsb_database)

For each telescope and gain we average the waveform values for all pixels, and subtract those averages from the waveforms. In this way we make sure we do not introduce any net average charge, but only increase the fluctuations.

Parameters:

nsb_database: dict

Dictionary with one key per telescope, containing an array [n_events,

n_gains, n_pixels, n_samples] (noise waveforms)

Returns:

nsb_database: dict

Dictionary, same as above but after baseline zeroing