Initial commit

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