noise - adds noise to ultracam data

noise takes an Ultracam file or a list of Ultracam files, then adds noise to simulate a CCD, including now an L3 CCD option. It treats the input frames as if they are measured in electrons. It now has quite a bit of extra stuff to cope with the rather tricky statistics of L3 CCDs. The effect of the avalanche register in these devices is calculated by first computing cumulative distribution functions (CDFs) using FFTs for a series of input electron number from 0 to a user-defined maximum (see nimax below). The 0 electron input includes clock-induced charges (CICs) generated within the avalanche register while the non-zero values do not. These are then used to generate output numbers using searches through the ordered CDF lists.

Invocation

noise file bias ncosmic beta elow ehigh full adcmax type [nstage pmult pave ppar npar pser nimax nmax ngauss] seed n*[read gain]

Arguments

file --- Either a file name or a list of files. If noise cannot open it as a standard ultracam file, it will assume that it is a list of files. The values in the file or files are assumed to represent mean electron numbers and must be positive. Poisson stats will be used.

bias --- A bias frame to add to the result (without incurring extra noise)

ncosmic --- Mean number of cosmic rays/CCD (normalised to total area)

beta --- Power law exponent (flux ~ E^-beta where E is the number of electrons from elow to ehigh

elow --- Lower cut-off of cosmic rays, > 0.

ehigh --- Upper cut-off of cosmic rays, > elow

full --- Full well capacity in electrons. Any value above this will be truncated to it. In the case of L3 readouts, this is the full well of the avalanche part.

adcmax --- Maximum value set by the ADC, e.g. 65535 for a 16 bit ADC.

type --- Type of readout. Either 'normal' for standard CCDs or 'L3' for avalanche readout. In the latter case a further 9 parameters are needed as described next.

nstage --- If type=L3, then you need to specify the number of mulitplication stages in the avalanche register. This will be a fixed number that is a function of the chip only

pmult --- If type=L3, then you need to specify the probability of multiplication per stage of the avalanche register. This leads to a mean gain of (1+pmult)^nstage. If you specify this as a negative number < -1, it will be assumed to be the negative of the desired avalanche gain and the equivalent pmult will be computed.

pave --- If type=L3, then you need to specify the probability of clock-induced charges per stage of the avalanche register. Such charges do not go through the complete set of avalanche multiplication steps and thus lead to a distinctly different output distribution from any charges generated before the avalanche steps.

ppar --- If type=L3, then you need to specify the probability of clock-induced charges per shift in the parallel register of the CCD. These should show up as a gradient in the parallel direction, rising as one gets further away from the readout, which I assume to lie in the bottom-right corner of the chip. The parallel direction is taken to lie along the Y direction, so if you set this to a large value you should see the number at large Y values increase.

npar --- If type=L3, this is an extra number of parallel shifts to represent a frame transfer device. This should of the same order of magnitude as the Y dimension of the chip and simply increases the probability of CICs due to parallel shifts.

pser --- If type=L3, then you need to specify the probability of clock-induced charges per shift in the serial register of the CCD *prior* to the avalanche register. Again this adds a gradient but now in the serial (X) direction. The gradient should increase towards small X. I am not quite sure whether I should have this parameter, but it is here for generality and can always to set = 0 if not thought to be significant. These 'normal' CICs will be added as follows. The mean number expected just before the avalanche stage will be calculated as ppar*(npar + y) + pser*(NXTOT-x) and a number of electrons generated following a Poisson distribution with the same mean.

nimax --- If type=L3, the events at low electron input numbers will be computed by lookup in CDFs computed at the start of the computation. 'nimax' is the number of CDFs including 0 to compute. Thus if you chose nimax=10, you would get CDFs for n=0 to 9. For n=0 this is just avalanche register CICs only, while for n=1 to 9, they are without CICs. Then when generating an event representatitve of an input of 6 electrons say, lookups of the n=0 and n=6 cases will be added. This parameter is essentially a matter of storage capacity and 'page faults'. The maximum input of nimax-1 will lead to a mean gain of (nimax-1)*g where g = (1+pmult)^nstage, with an RMS spread of sqrt((nimax-1)*(1-pmult)/(1+pmult)*g(g-1)) which can be used to determine the value of the previous parameter nmax. e.g. if pmult=0.015 and nstage=591 so g=6630, then if nimax=20 one would expect a mean gain for the maximum number = 126,000 with an RMS of 28,500, and so one might want nmax ~ 200,000. However, if one knew that the full-well capacity or the 16-bit ADU would limit this to a lower number, then you might as well set the limit at this stage to save time. The events are generated such that any exceeding 'nmax' will actually saturate at this number. Total memory implied by nimax and nmax (see next) is between 8*(6+nimax)*nmax and 8*(12+nimax)*nmax bytes. You get near the lower limit if you use a value of nmax just below an exact power of 2 such as 65000.

nmax --- If type=L3, then you need to specify the maximum gain to compute up to. The absolute maximum is 2^nstage but this is normally a huge number and far higher than typical gains in practice. nmax is essentially a computational parameter. The larger it is, the slower things will run.

ngauss --- If type=L3, then the lookup table method is limited in its maximum number to nimax-1. Values above nimax-1 can be generated by multiple lookup. e.g. if nimax=10 and we have an input of 25 electrons, we can add events drawn from the n=0, 9, 9 & 7 CDFs. However, for very large inputs even this will become slow and one has to make do with a gaussian of the the expected mean and variance of the true distribution. 'ngauss' is the number at which to start doing this which must be >= nimax.

seed --- Random number seed integer.

read, gain --- RMS readout (electrons), gain on readout (electron/ADU). Can be repeated many times and then will be applied successively to different windows (continuing on to the next CCD etc). Must be set at last once. If there are more windows than pairs of values, then the last pair are used for the extra windows.

Related routines

To create the input files for this routine see also addfield, addsky, addspectrum etc.

Classes

This command is a member of the classes: Programs, Testing.

Author: T.R. Marsh
Created: 15 May 2001
Revised: 03 November 2005

Page generated Fri Jul 5 12:23:42 2013

file	---	Either a file name or a list of files. If noise cannot open it as a standard ultracam file, it will assume that it is a list of files. The values in the file or files are assumed to represent mean electron numbers and must be positive. Poisson stats will be used.
bias	---	A bias frame to add to the result (without incurring extra noise)
ncosmic	---	Mean number of cosmic rays/CCD (normalised to total area)
beta	---	Power law exponent (flux ~ E^-beta where E is the number of electrons from elow to ehigh
elow	---	Lower cut-off of cosmic rays, > 0.
ehigh	---	Upper cut-off of cosmic rays, > elow
full	---	Full well capacity in electrons. Any value above this will be truncated to it. In the case of L3 readouts, this is the full well of the avalanche part.
adcmax	---	Maximum value set by the ADC, e.g. 65535 for a 16 bit ADC.
type	---	Type of readout. Either 'normal' for standard CCDs or 'L3' for avalanche readout. In the latter case a further 9 parameters are needed as described next.
nstage	---	If type=L3, then you need to specify the number of mulitplication stages in the avalanche register. This will be a fixed number that is a function of the chip only
pmult	---	If type=L3, then you need to specify the probability of multiplication per stage of the avalanche register. This leads to a mean gain of (1+pmult)^nstage. If you specify this as a negative number < -1, it will be assumed to be the negative of the desired avalanche gain and the equivalent pmult will be computed.
pave	---	If type=L3, then you need to specify the probability of clock-induced charges per stage of the avalanche register. Such charges do not go through the complete set of avalanche multiplication steps and thus lead to a distinctly different output distribution from any charges generated before the avalanche steps.
ppar	---	If type=L3, then you need to specify the probability of clock-induced charges per shift in the parallel register of the CCD. These should show up as a gradient in the parallel direction, rising as one gets further away from the readout, which I assume to lie in the bottom-right corner of the chip. The parallel direction is taken to lie along the Y direction, so if you set this to a large value you should see the number at large Y values increase.
npar	---	If type=L3, this is an extra number of parallel shifts to represent a frame transfer device. This should of the same order of magnitude as the Y dimension of the chip and simply increases the probability of CICs due to parallel shifts.
pser	---	If type=L3, then you need to specify the probability of clock-induced charges per shift in the serial register of the CCD prior to the avalanche register. Again this adds a gradient but now in the serial (X) direction. The gradient should increase towards small X. I am not quite sure whether I should have this parameter, but it is here for generality and can always to set = 0 if not thought to be significant. These 'normal' CICs will be added as follows. The mean number expected just before the avalanche stage will be calculated as ppar(npar + y) + pser(NXTOT-x) and a number of electrons generated following a Poisson distribution with the same mean.
nimax	---	If type=L3, the events at low electron input numbers will be computed by lookup in CDFs computed at the start of the computation. 'nimax' is the number of CDFs including 0 to compute. Thus if you chose nimax=10, you would get CDFs for n=0 to 9. For n=0 this is just avalanche register CICs only, while for n=1 to 9, they are without CICs. Then when generating an event representatitve of an input of 6 electrons say, lookups of the n=0 and n=6 cases will be added. This parameter is essentially a matter of storage capacity and 'page faults'. The maximum input of nimax-1 will lead to a mean gain of (nimax-1)g where g = (1+pmult)^nstage, with an RMS spread of sqrt((nimax-1)(1-pmult)/(1+pmult)g(g-1)) which can be used to determine the value of the previous parameter nmax. e.g. if pmult=0.015 and nstage=591 so g=6630, then if nimax=20 one would expect a mean gain for the maximum number = 126,000 with an RMS of 28,500, and so one might want nmax ~ 200,000. However, if one knew that the full-well capacity or the 16-bit ADU would limit this to a lower number, then you might as well set the limit at this stage to save time. The events are generated such that any exceeding 'nmax' will actually saturate at this number. Total memory implied by nimax and nmax (see next) is between 8(6+nimax)nmax and 8(12+nimax)*nmax bytes. You get near the lower limit if you use a value of nmax just below an exact power of 2 such as 65000.
nmax	---	If type=L3, then you need to specify the maximum gain to compute up to. The absolute maximum is 2^nstage but this is normally a huge number and far higher than typical gains in practice. nmax is essentially a computational parameter. The larger it is, the slower things will run.
ngauss	---	If type=L3, then the lookup table method is limited in its maximum number to nimax-1. Values above nimax-1 can be generated by multiple lookup. e.g. if nimax=10 and we have an input of 25 electrons, we can add events drawn from the n=0, 9, 9 & 7 CDFs. However, for very large inputs even this will become slow and one has to make do with a gaussian of the the expected mean and variance of the true distribution. 'ngauss' is the number at which to start doing this which must be >= nimax.
seed	---	Random number seed integer.
read, gain	---	RMS readout (electrons), gain on readout (electron/ADU). Can be repeated many times and then will be applied successively to different windows (continuing on to the next CCD etc). Must be set at last once. If there are more windows than pairs of values, then the last pair are used for the extra windows.