diff options
Diffstat (limited to 'noao/artdata/doc/mknoise.hlp')
| -rw-r--r-- | noao/artdata/doc/mknoise.hlp | 245 |
1 files changed, 245 insertions, 0 deletions
diff --git a/noao/artdata/doc/mknoise.hlp b/noao/artdata/doc/mknoise.hlp new file mode 100644 index 00000000..cab14d42 --- /dev/null +++ b/noao/artdata/doc/mknoise.hlp @@ -0,0 +1,245 @@ +.help mknoise Aug90 noao.artdata +.ih +NAME +mknoise - Make/add noise and cosmic rays to 1D/2D images +.ih +PARAMETERS +.ls input +Images to create or modify. +.le +.ls output = "" +Output images when modifying input images. If no output images are +given then existing images in the input list are modified directly. +If an output image list is given then it must match in number the +input list. +.le + +WHEN CREATING NEW IMAGES +.ls title = "" +Image title to be given to the images. Maximum of 79 characters. +.le +.ls ncols = 512, nlines = 512 +Number of columns and lines. +.le +.ls header = "artdata$stdheader.dat" +Image or header keyword data file. If an image is given then the image header +is copied. If a file is given then the FITS format cards are copied. +This only applies to new images. The data file consists of lines +in FITS format with leading whitespace ignored. A FITS card must begin +with an uppercase/numeric keyword. Lines not beginning with a FITS +keyword such as comments or lower case are ignored. The user keyword +output of \fBimheader\fR is an acceptable data file. See \fBmkheader\fR +for further information. +.le + +NOISE PARAMETERS +.ls background = 0. +Background to add to images before computing Poisson noise. +.le +.ls gain = 1. +Gain in electrons per data number. The gain is used for scaling the +read noise parameter and in computing poisson noise. +.le +.ls rdnoise = 0. +Gaussian read noise in electrons. +.le +.ls poisson = no +Add poisson noise? Note that any specified background is added to new +or existing images before computing the Poisson noise. +.le +.ls seed = 1 +Random number seed. If a value of "INDEF" is given then the clock +time (integer seconds since 1980) is used as the seed yielding +different random numbers for each execution. +.le + +COSMIC RAYS +.ls cosrays = "" +List of cosmic ray files. Cosmic ray files contain lines of cosmic ray +coordinates and energy (see DESCRIPTION section). If no +file or a new (nonexistent) file is specified then a number of random +cosmic rays given by the parameter \fIncosrays\fR is generated. If a +new file name is specified then the events generated are recorded in the +file. If the list of cosmic ray files is shorter than the list of +input images then the last cosmic ray file is reused. +.le +.ls ncosrays = 0 +If no cosmic ray file or a new file is specified then the task will +generate this number of random cosmic rays. The positions are +uniformly random within the limits of the image and the energy is +uniformly random between zero and a maximum. +.le +.ls energy = 30000. +When generating random events the cosmic rays will have a uniform energy +distribution (in electrons) between zero and this maximum. +.le +.ls radius = 0.5 +The half-intensity radius of gaussian profile cosmic rays in pixels +along the major axis. +.le +.ls ar = 1. +Minor to major axial ratio for cosmic rays. +.le +.ls pa = 0. +Position angle in degrees measured counterclockwise from the X axis for +cosmic rays. +.le + +.ls comments = yes +Include comments recording task parameters in the image header? +.le + +PACKAGE PARAMETERS + +These parameters define certain computational shortcuts which greatly +affect the computational speed. They should be adjusted with care. +.ls nxc = 5, nyc = 5 +Number of cosmic ray centers per pixel in X and Y. Rather than evaluate +cosmic rays precisely at each subpixel coordinate, a set of templates +with a grid of subpixel centers is computed and then the nearest template to +the desired position is chosen. The larger the number the more memory +and startup time required. +.le +.ls nxsub = 10, nysub = 10 +Number of pixel subsamples in X and Y used in computing the cosmic +ray profiles. This is the subsampling in the central +pixel and the number of subsamples decreases linearly from the center. +This affects the time required to compute the cosmic ray templates. +.le +.ls dynrange = 100000. +The intensity profile of the gaussian cosmic rays extends to infinity so +a dynamic range, the ratio of the peak intensity to the cutoff +intensity, is imposed. Because the cosmic rays are small this parameter +is not critical. +.le +.ls ranbuf = 0 +Random number buffer size. When generating readout and poisson noise, +evaluation of new random values has an affect on the execution time. +If truly (or computationally truly) random numbers are not needed +then this number of random values is stored and a simple +uniform random number is used to select from the stored values. +To force evaluation of new random values for every pixel set the +value of this parameter to zero. +.le +.ih +DESCRIPTION +This task creates or modifies images with readout noise, poisson noise, +and cosmic ray events. New images are created with the specified +dimensions and real datatype. Existing images may be modified in place +or new images may be created. + +If a new image is created it is has the mean level given by the parameter +\fIbackground\fR. With no noise and no cosmic rays this task can be used to +create images of constant background value. For existing images the +background is added before computing any noise. To add noise to an +existing image without modifying the mean counts set the background +to zero. + +For new images a set of header keywords may be added by specifying an +image or data file with the \fIheader\fR parameter (see also \fBmkheader\fR). +If a data file is specified lines beginning with FITS keywords are +entered in the image header. Leading whitespace is ignored and any +lines beginning with words having lowercase and nonvalid FITS keyword +characters are ignored. In addition to this optional header, +keywords, parameters for the gain and read noise are defined. +Finally, comments may be added to the image header recording the task +parameters and any information from the cosmic ray file which are not +cosmic ray definitions. + +Poisson photon noise is generated by setting the \fIpoisson\fR parameter. +For new images the input data value is the background while for +existing images the input data value is added to the background value. +The data value is then multiplied by the gain, a poisson deviate is +generated, and divided by the gain. Expressed as a formula: + +.nf + New images: out = P(background * gain) / gain + Existing images: out = P((in+background)*gain) / gain +.fi + +where P(x) is a poisson deviate with mean x, in and out are the input +and final pixel values, and background and gain are the parameter +values of the same name. + +Readout or gaussian noise is generated by specifying a gaussian sigma with +the parameter \fIrdnoise\fR. The sigma is divided by the specified gain +to convert to image data units. Gaussian random numbers of mean zero are +then generated for each pixel and added to the image, or background +value for new images, after the photon noise is computed. + +Generating gaussian and poisson random numbers computationally is +the main determinant of the execution time in this task. +Two things are done to speed up the task. +First, the gaussian approximation is used for data values greater +than 20 (after applying the background and gain). The square root +of the data value is used as the gaussian sigma about the data +value. For values less than 20 a true poisson deviate is generated. +The second speed up is to allow storing a number of normalized gaussian +values given by the package parameter \fIranbuf\fR as they are generated. If +more values than this are desired then a uniform random number is used +to select one of these stored values. This applies to both the read noise +and poisson noise gaussian approximation though not the true poisson +evaluation. For most purposes this approximation is good and one would +need to look very hard to detect the nonrandomness in the noise. +However, if one wants to take the extra computational time then +by setting the \fIranbuf\fR parameter to zero each gaussian +random number will be generated independently. + +The cosmic ray model is an elliptical gaussian of specified +half-intensity radius, axial ratio, and position angle. Normally the +radius will be small (smaller than the point spread function) and the +axial ratio will be 1. The cosmic rays are subsampled and can have the +number of centers given by the \fInxc/nyc\fR package parameters. The method +of generating the cosmic rays is that described for the task +\fBmkobjects\fR. Specifically it is the same as adding gaussian +profile stars. + +The total flux (not the peak) of the cosmic ray is given by the energy +in electrons so that the value is divided by the gain to produce the +total flux in the image. Note that this task can be used to add cosmic +ray spikes to one dimensional images such as spectra but the strengths +will appear low because of the part of the event which falls outside +the single line. + +The positions and energies of the cosmic rays can be specified in a +file or the task can generate random events. Specific cosmic rays are +specified by a file containing lines of x and y positions and energy. +Positions outside the limits of the image are ignored. If no cosmic +ray file is given or if a new, nonexistent file is named then the +number of cosmic rays given by the \fIncosrays\fR parameter is +generated with uniform spatial distribution within the image and +uniform energy distribution between zero and that given by the +\fIenergy\fR parameter. By giving a new file name the randomly +generated cosmic rays will be recorded for reuse or to allow +identifying the events while testing tasks and algorithms. +.ih +EXAMPLES +1. Create a new image with a background of 1000, a read noise +of 10 electrons, a gain of 2, and 50 random cosmic rays. Don't keep a +record of the cosmic rays. + +.nf + cl> mknoise testim back=1000 rd=10 gain=2 poisson+ ncos=50 +.fi + +2. Add cosmic rays to an image and create a new output image. + +.nf + cl> head cosfile + 20.3 50.1 1000 + 325.6 99.6 250 + cl> mknoise dev$pix out=newpix cos=cosfile +.fi +.ih +REVISIONS +.ls MKNOISE V2.11+ +The random number seed can be set from the clock time by using the value +"INDEF" to yield different random numbers for each execution. +.le +.ls MKNOISE V2.11 +The default value of "ranbuf" was changed to zero. +.le +.ih +SEE ALSO +mkobjects, mkheader +.endhelp |