PHOTONS: Add Artificial Stars and/or Noise to an Image

   

Form: PHOTONS source [NSTARS=] [AT=r,c] [COUNTS=c1,c2] [MEAN=]
[RN=] [GAIN=] [GAUSS] [FILE=] [FW=] [DAOPSF=]
[PHOT] [NEW] [PSFLIB=] [STR=] [NDIV] [TRUNC]
NSTARS=
gives the number of stars to make.
AT=R,C
Put a single star at row R and column C This cannot be used with NSTARS.
STR=file
specifies a file with the positions and counts of the stars to be added
COUNTS=a,b
gives ranges in total counts for the stars. If only one number is given, range will be from 0 to that number
MEAN=
gives the mean level (counts) added to the image to mimic sky. If mean>=0, photon noise will be added properly given counts in each pixel. Mean=-1 if unspecified. If mean<0 then no photon noise is added to image.
RN=
gives the readout noise (electrons) 0 if unspecified.
GAIN=
gives the conversion between photons and counts. This is in the units photons per count. Needed to do noise properly.
GAUSS
tell program to make images from a sampled Gaussian, with FWHM specified by FW= keyword If not include, PSF profile will be read a a disk file specified by FILE= keyword
FW=
star FWHM in pixels for Gaussian, or half width for arbitrary PSF (in disk file)
FILE=
specifies file with 250 numbers (arr(i),i=1,250) representing 1-D PSF: half-width (no. of pixels per 250 bins) must be specified with FW keyword. If FILE is specified, GAUSS is ignored
DAOPSF=file
creates stars with PSF from a DAOPHOT .PSF file
PSFLIB=file
Specifies PSFLIB library file to use to look up PSF at various pixel centerings. Must be created with PSFLIB command and special image
PHOT
store the positions and total counts of added stars in a photometry file.
NEW
creates a new photometry file. NEW implies PHOT
NDIV
allows user to change the pixel subdivisions used for the PSF integration over pixels
TRUNC
Makes PHOTONS integer truncate
PHOTONS creates artificial stars and/or noise on an already existing image. If no image exists, use CREATE to make one. It makes as many stars as you want with whatever brightnesses you want. You can specify where to put each star, or you can place them randomly on the image, or you can read in positions from an external file. You can use a coarse Gaussian to represent the PSF with whatever FWHM, or you can give a PSF to the program to read from a preexisting disk file. You can use a DAOPHOT style PSF to create images, or a PSFLIB file. You can store the information (position and counts) about the created stars in a VISTA photometry file.

Without preparing an external file, you can either create one star at a specified position or one or more stars at random positions. For a specified position,use AT=r,c; if this keyword isn't used, positions will be random on the frame, unless the STR= keyword is used. Specify the number of stars desired using NSTARS=n.The number of counts in each star is determined from the COUNTS=c1,c2 keyword. Each star will have a total number of counts randomly distributed in the range c1 to c2. If you want a star to have a particular number of counts c1, just set c2=c1+1.

To make stars from a list on disk, prepare a file with four columns: ID,COL(X), ROW(Y), COUNTS. Any format is OK, as long as there are spaces between the numbers. Specify the filename with STR=filename and your stars will be made.

The PSFs of the stars can be a Gaussian of whatever FWHM you desire, or it can be integrated external disk file with a 1-D PSF, or you can use a PSF created by the DAOPHOT PSF routine to create stars, or you can specify a PSF library file to use. For a Gaussian PSF, use the GAUSS keyword along with FW=FWHM to specify the FWHM. For an arbitrary symmetric PSF from a disk file, use FILE=file to specify the file name. This file can contain up to 1000 numbers with the profile of your desire tabulated. The program converts this profile to a pixel scale using the FW= keyword to tell it how many pixels corresponds to the NTABLE entries. The file should be a formatted disk file written with (Fortran):

  WRITE(*)  NTABLE
  WRITE(*) (PSF_TABLE(I), I = 1, NTABLE)
Note that the ``formatted'' write statement in Fortran makes a file that is machine-dependent, and such files are generally not exportable to other machine/operating-system architectures.

To use a DAOPHOT PSF, use the DAOPSF=file to specify the file name of the DAOPHOT .PSF file.

For all the file options, the V_DATADIR is the default directory.

Unless requested, noise will not be added to the image. To add noise, use MEAN=mean and/or RN=rn. MEAN adds a constant value to all pixels in the image, then computes noise for each pixel and adds it on. RN will add readout noise to the image. Note that mean and rn are to be given in counts. To get the correct noise, you also need to specify a gain (with GAIN=gain) in units of photons per count. Recall, if MEAN is greater than or equal to 0, noise will be added. Consequently if you want to add stars to an image more than once, you will add photon noise each time if MEAN is >= 0. The default values are -1 for mean (no noise added), 0 for RN (no noise added), and 1 for GAIN. The most useful technique is to add sets of stars with MEAN=-1, and when all stars are finally placed, run PHOTONS with MEAN=the desired sky level.

To store the information about the created stars (their positions and brightnesses) in a VISTA photometry file, use the PHOT keyword. For a new file, use the NEW keyword (NEW implies PHOT).