Initial commit

1 files changed, 355 insertions, 0 deletions

diff --git a/noao/artdata/doc/mk1dspec.hlp b/noao/artdata/doc/mk1dspec.hlp
new file mode 100644
index 00000000..b96684a8
--- /dev/null
+++ b/noao/artdata/doc/mk1dspec.hlp
@@ -0,0 +1,355 @@
+.help mk1dspec Jul95 noao.artdata
+.ih
+NAME
+mk1dspec -- Make/add artificial 1D spectra
+.ih
+USAGE
+mk1dspec input
+.ih
+PARAMETERS
+.ls input
+Spectra to create or modify.
+.le
+.ls output = ""
+Output spectra when modifying input spectra.  If no output spectra are
+given then existing spectra in the input list are modified directly.
+If an output list is given then it must match in number the input list.
+.le
+.ls ap = 1
+Image line to be created or modified in images of dimension greater than 1.
+.le
+.ls rv = 0.
+Radial velocity (km/s) or redshift, as selected by the parameter \fIz\fR,
+applied to line positions and continuum.  Velocities are converted to
+redshift using the relativistic relation 1+z = sqrt ((1+rv/c)/(1-rv/c)).
+Note the shift is not a shift in the dispersion parameters but in the
+underlying artificial spectrum.
+.le
+.ls z = no
+Is the velocity parameter a radial velocity or a redshift?
+.le
+
+WHEN CREATING NEW SPECTRA
+.ls title = ""
+Image title to be given to the spectra.  Maximum of 79 characters.
+.le
+.ls ncols = 512
+Number of columns.
+.le
+.ls naps = 1
+Number of lines or apertures.
+.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
+.ls wstart = 4000., wend = 8000.
+Starting and ending wavelengths in Angstroms.  The dispersion is
+determined by these values and the number of columns.
+.le
+
+CONTINUUM PARAMETERS
+.ls continuum = 1000., slope = 0.
+Continuum of the starting wavelength at rest and the slope of the continuum.
+.le
+.ls temperature = 5700.
+Blackbody continuum temperature in Kelvin.  A value of 0 is used if
+no blackbody continuum is desired.  The intensity level is set by
+scaling to the continuum level of the starting wavelength at rest.
+.le
+.ls fnu = no
+Compute the continuum as flux per unit frequency (F-nu) if yes or flux per
+unit wavelength (F-lambda) if no.
+.le
+
+
+LINE PARAMETERS
+.ls lines = ""
+List of spectral line files.  Spectral line files contain lines of rest
+wavelength, peak, profile type, and widths (see the DESCRIPTION
+section).  The latter parameters may be missing or INDEF in which case they
+default to the task \fIpeak\fR, \fIprofile\fR, \fIgfwhm\fR, and \fIlfwhm\fR
+parameters (note that the \fIpeak\fR parameter is not a constant but the
+random number scaling).  If no file or a new (nonexistent) file is
+specified then a number of random lines given by the parameter \fInlines\fR
+is generated.  If a new file name is specified then the lines generated are
+recorded in the file.  If the list of spectral line files is shorter than
+the list of input spectra, the last spectral line list file is reused.
+.le
+.ls nlines = 0
+If no spectral line file or a new file is specified then the task will
+generate this number of random spectral lines.  The rest wavelengths are
+uniformly random within the limits of the spectrum, the peaks are uniformly
+random between zero and the value of the \fIpeak\fR parameter, the profile
+type is given by \fIprofile\fR, and the widths are fixed at the values of
+the \fIgfhwm\fR ad \fIlfwhm\fR parameters.  If a redshift is applied the
+rest wavelengths are shifted and repeated periodically.
+.le
+.ls profile = "gaussian" (gaussian|lorentzian|voigt)
+The default profile type for random lines or when not specified in the
+spectral line file.  The profile types are:
+
+.nf
+      gaussian - Gaussian profile
+    lorentzian - Lorentzian profile
+         voigt - Voigt profile
+.fi
+.le
+.ls peak = -0.5
+The maximum spectral line peak value when generating random lines or
+when the peak is missing from the spectral line file.
+This value is relative to the continuum unless the continuum is zero.
+Negative values are absorption lines and positive values are emission lines.
+.le
+.ls gfwhm = 20., lfwhm = 20.
+The default gaussian and lorentzian full widths at half maximum (FWHM), in
+Angstroms, used when generating random lines or when the widths are missing
+from the spectral line file.
+.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
+
+.ls comments = yes
+Include comments recording task parameters in the image header?
+.le
+
+PACKAGE PARAMETERS
+.ls nxsub = 10
+Number of pixel subsamples used in computing the gaussian spectral line
+profiles.
+.le
+.ls dynrange = 100000.
+The gaussian line profiles extend to infinity so a dynamic range, the ratio
+of the peak intensity to the cutoff intensity, is imposed to cutoff
+the profiles.
+.le
+.ih
+DESCRIPTION
+This task creates or modifies one dimensional spectra.  with a combination
+of blackbody and linear sloped continuum and emission and absorption
+spectral lines.  The spectral lines may be gaussian, lorentzian, or voigt
+profiles.  A velocity shift may be applied to the underlying artificial
+spectrum which is shifted into the specified observed wavelength region.
+No noise is included but may be added with the task \fBmknoise\fR.  New
+spectra are created with the specified number of pixels, wavelength range,
+and real datatype.  When \fInlines\fR is greater than 1 then an image with
+the specified number of lines is created though only the line given by the
+\fIap\fR is will have a spectrum.  Existing spectra may be modified in
+place or new spectra output.  Spectra are modified by adding the continuum
+and lines defined by the parameters.
+
+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, parameters for the
+wavelength coordinates are defined.  Finally, comments may be added to the
+image header recording the task parameters and any information from the
+line file which are not line definitions.
+
+Initially all spectra are created without a dispersion function; i.e.
+pixel coordinates.  For multiple spectra in an image this task must be
+executed for each image line to set the dispersion function and add data.
+When an image line is selected if it has a defined dispersion function that
+is used otherwise the task wavelength parameters are used.
+
+A continuum is defined by the value at the starting wavelength at rest, a
+slope, and a blackbody function of a given temperature.  The blackbody
+function is scaled to have the specified continuum value at the starting
+wavelength at rest.  The blackbody flux units are per unit wavelength
+(F-lambda).  A zero continuum value or a zero temperature will not produce a
+blackbody continuum.
+
+Spectral lines are modeled by gaussian, lorentzian, or voigt profiles of
+specified wavelength, peak, and widths.  The lines are defined in a
+spectral line file or generated randomly.  A spectral line file consists of
+text lines giving rest wavelength, peak, profile type, gaussian full width
+at half maximum and/or lorentzian full width at half maximum.  Only the
+wavelength is required and subsequent fields may be missing or given as
+INDEF.  The following table shows the possible formats where wavelength,
+peak,  gfwhm, and lfwhm are values of wavelength, peak, gaussian FWHM, and
+lorentzian FWHM.  The profile types are as shown though they may be
+abbreviated to one character.
+
+.nf
+	wavelength
+	wavelength peak
+	wavelength peak gaussian
+	wavelength peak gaussian gfwhm
+	wavelength peak gaussian gfwhm
+	wavelength peak lorentzian
+	wavelength peak lorentzian lfwhm
+	wavelength peak lorentzian lfwhm
+	wavelength peak voigt
+	wavelength peak voigt gfwhm
+	wavelength peak voigt gfwhm lfwhm
+	wavelength peak voigt gfwhm lfwhm
+.fi
+
+When a field is missing or INDEF the values given by the parameters
+\fIpeak\fR, \fIprofile\fR, \fIgfwhm\fR, and \fIlfwhm\fR are used.  If a
+peak value is missing, random values between zero and the \fIpeak\fR value
+are generated.  Note that to get random line intensities with some
+specified profile type and widths the value INDEF would be used for
+the peak field.
+
+If no spectral line file is specified or a new (nonexistent) file is named
+then the number of random lines given by the parameter \fInlines\fR is
+generated.  The rest wavelengths are uniformly random within the wavelength
+range of the spectrum and extend periodically outside this range in the
+case of an applied velocity shift, the peaks are uniformly random between
+zero and the \fIpeak\fR parameter, and the profile type and widths are
+given by the \fIprofile\fR, \fIgfwhm\fR, and \fIlfwhm\fR parameters.  If a
+new file is named then the parameters of the generated lines will be
+output.
+
+The peak values are taken relative to a positive continuum.  In other
+words the generated line profile is multiplied by the continuum (with a
+minimum of zero for fully saturated absorption lines).  If the
+continuum is less than or equal to zero, as in the case of an
+artificial arc spectrum or pure emission line spectrum, then the peak
+values are absolute intensities.  Positive peak values produce emission
+lines and negative values produce absorption lines.  Odd results will
+occur if the continuum has both positive and zero or negative values.
+
+The underlying rest spectrum may be shifted.  This is used primarily for
+testing radial velocity measuring algorithms and is not intended as a
+complete model of redshift effects.  The starting and ending wavelengths
+are not changed by redshifting; these are the instrumental observed
+wavelengths.  Input line wavelengths are specified at rest and then
+shifted into or out of the final spectrum.  To be realistic the line
+list should include wavelengths over a great enough range to cover
+all desired redshifts.  The peaks and widths are also appropriately
+modified by a redshift.  As an example, if the redshift is 1 the
+lines will appear broader by a factor of 2 and the peaks will be down
+by a factor of 2 in order to maintain the same flux.
+
+The random line generation is difficult in that one wants to have the
+same set of lines (for a given seed) observed at different redshifts.
+What is done is that the specified number of random lines is generated
+within the observed wavelength interval taken at rest.  This set is
+then repeated periodical over all wavelengths.  A redshift will then
+shift these rest lines in to or out of the observed spectrum.  If the
+lines are output, they are given at rest.  \fBNote that this
+periodicity may be important in interpreting cross correlation redshift
+tests for large shifts between template and object spectra.\fR
+
+The definitions of the continuum are also affected by a redshift.
+The reference point for the continuum level, slope, and blackbody
+continuum is the starting wavelength taken at rest.  Shifts will then
+modify the continuum level at the first pixel appropriately.  In
+particular a large redshift will shift the blackbody in such a way that
+the flux is still given by the \fIcontinuum\fR parameter at the starting
+wavelength at rest.
+.ih
+EXAMPLES
+1. Create a simple blackbody continuum between the default wavelengths.
+
+.nf
+	cl> mk1dspec bb title=Blackbody
+.fi
+
+2. Create a random absorption spectrum on a blackbody continuum without
+saving the line list.
+
+.nf
+	cl> mk1dspec bbab title=Absorption nlines=100
+.fi
+
+3. Create a random absorption spectrum with noise and cosmic rays.
+
+.nf
+	cl> mk1dspec bbab title=Absorption nlines=100
+	cl> mknoise bbab rdnoise=10 poisson+ ncos=5 energy=1000
+.fi
+
+4. Create a random emission spectrum on a blackbody continuum and save
+the line list.
+
+.nf
+	cl> mk1dspec bbem title=Emission nl=30 peak=0.6 lines=bbem.dat
+.fi
+
+5. Create an artificial random arc line spectrum.
+
+.nf
+	cl> mk1dspec arc title="Arc lines" cont=0 peak=500 nl=30
+.fi
+
+6. Create a test spectrum with a line list.
+
+.nf
+	cl> type linelist
+	4100 -.1 g 20
+	4200 -2. g 20
+	4300 -.3 g 20
+	5100 -.9 g 2
+	5200 -.9 g 4
+	5300 -.9 g 8
+	6700 .9 g 8
+	6800 .9 g 2
+	6900 .9 g 4
+	7700 .3 g 20
+	7800 .2 g 20
+	7900 .1 g 20
+	cl> mk1dspec testspec title=Test cont=500 temp=0 lines=linelist
+.fi
+
+7. Add absorption lines to a spectrum.
+
+.nf
+	cl> mk1dspec bb out=artspec cont=0 lines=STDIN
+	4300 -60
+	5000 -200
+	[EOF]
+.fi
+
+Normally the input spectrum would be a real spectrum.
+
+8. Make two spectra taken from the same set of random lines but differing
+in redshift.
+
+.nf
+	cl> mk1dspec restspec nl=30
+	cl> mk1dspec redspec rv=3000 nl=30
+	cl> mk1dspec bluespec rv=-.01 z+ nl=30
+.fi
+
+9. Make a multispec image with 5 apertures and a range of redshifts.
+
+.nf
+	cl> mk1dspec spec.ms ap=1 nl=30 rv=0 naps=5
+	cl> mk1dspec spec.ms ap=2 nl=30 rv=1000
+	cl> mk1dspec spec.ms ap=3 nl=30 rv=2000
+	cl> mk1dspec spec.ms ap=4 nl=30 rv=3000
+	cl> mk1dspec spec.ms ap=5 nl=30 rv=4000
+.fi
+.ih
+REVISIONS
+.ls MK1DSPEC 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 MK1DSPEC V2.11
+Lorentzian and Voigt profiles were added and the parameters and input
+line list format were changed.  The widths are now FWHM instead of
+gaussian sigmas.
+.le
+.ls MK1DSPEC V2.10.3
+The format parameter was eliminated and the task updated to produce the
+current coordinate system format.
+.le
+.ih
+SEE ALSO
+mknoise, mk2dspec, mkheader, onedspec.sinterp
+.endhelp