path: root/noao/artdata/doc/mk1dspec.hlp

.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