PRIMUS Mask Generation

From NYU CCPP Wiki

This is a page about the PRIMUS project.

We break the generation of masks into two steps: creating a "survey" with targets and priorities assigned; and designing masks for a particular observing "run." There may be multiple design runs for a particular survey.

Enlarge

Contents

[edit]

Correcting astrometry

The first task is to make sure that the astrometry you are using is appropriate. This in general is hard but we have some tools to help. It is a good idea to create a program that does this such as: 

[survey]_correct

which reads in the basic survey catalogs that will be read later by [survey]_all and writes out versions with corrected RA and DECs.

A useful tool in the PRIMUS repository is 

correct_astrom

which inputs two catalogs, and tweaks the astrometry of one to match the other. It returns a structure containing the nature of the tweak (so you can reuse it).

[edit]

Designing a "survey"

A "survey" is based on a particular set of target data. For example, "deep2_02hr" is based on the DEEP2 field at 2 hours in right ascension. To design a survey we run: 

survey_design, survey

which calls: 

[survey]_all.pro - gather all of the potential targets
[survey]_bsmask.pro - create the relevant bright masks
[survey]_targets.pro - assign target flags
[survey]_priority.pro - prioritize targets (may subsample!)

All of these need to be rewritten for each new survey, because they depend on the particulars of the data set. These steps do the following tasks:

  1. survey_all: Create the list of all possible targets. This is done as a separate step since then you can concentrate all the data dependencies into this one file. This creates the file:
    $PRIMUS_DATA/design/[survey]/targets/[survey]_all.fits
  2. survey_bsmask: Create the list of exclusion regions away from bright stars. Usually, this is just some exlusion regions surrounding Tycho and USNO-A stars brighter than 13 or so. You need to include both, since Tycho is not complete faint enough, and USNO is not complete bright enough. Note that this mask is not applied until later, when each mask is designed, so that the target flags in the following stars do not respect this bright star mask. This creates the file:
    $PRIMUS_DATA/design/[survey]/masks/[survey]_bsmask.ply
  3. survey_targets: Choose the targets from the full list. This code chooses targets and assigns target bits to the PRIMUS_TARGET field. The list of target bits is in the file $PRIMUS_DIR/data/primus_maskbits.par. This creates the file:
    $PRIMUS_DATA/design/[survey]/targets/[survey]_targets.fits
    The target flags include bits to flag reference stars (that is, alignment stars).
  4. survey_priority: Prioritize the targets. At this point, we assign priorities to each object based on its target flags and perhaps other things. The priority defined here is the one passed to mask generation for objects in the window of each mask. This procedure may decide to subsample the objects depending on the strategy for a particular survey. Creates the file:
    $PRIMUS_DATA/design/[survey]/targets/[survey]_priority.fits
[edit]

Designing a "run"

A "run" is a set of masks designed for observations of a particular survey. We usually name it by the first time it is to be observed (for example, 'jan05'). To design the run we call: 

run_design, survey, run

which calls: 

[survey]_[run]_masks.pro - choose mask positions
primus_maskgen_[method].pro - assign targets to masks
primus_survey_obsfiles.pro - create the .obs files for maskgen
primus_masks_stats.pro - create statistics files and QA plots

These routines depend upon a file which one has to update for each run: 

$PRIMUS_DIR/data/primus_masks.par

which tracks the surveys and runs, and which mask numbers are in which. It also contains which "method" of "primus_maskgen_[method]" we want to use.

The primus_masks.par file tells what mask numbers are to be assigned, what the priority name and numbers are for various targets, and other information including the PRIMUS slit type for conflict resolution.


These routines do the following:

[edit]

survey_run_masks

Chooses mask positions and PAs. For now (and usually, I think) this will be basically hard-coded. It also creates a spherical polygon file describing the geometry of the masks. Creates the files: 

$PRIMUS_DATA/design/[survey]/masks/[survey]_masks.fits
$PRIMUS_DATA/design/[survey]/masks/[survey]_masks_poly.ply
$PRIMUS_DATA/design/[survey]/masks/[survey]_masks_window.ply

Most of the time PRIMUS observations are taken at PA=0. Sometimes, we need to choose PAs which align the slits with the direction towards the zenith (so that the position angle of the slits is aligned with the "parallactic angle"). A procedure "parangle.pro" exists that yields the PA necessary for a given time. (Note that the PRIMUS software always talks about the PA of the slits, whereas the POSITION entry in maskgen .obs files is POSITION=PA-90).

Once we choose the PA, we need to check that (a) there are no "rotator" issues with that PA and (b) that there are guide stars available in the IMACS guide windows. Both of these tasks require running the "intgui" routines on the .obs files. For (a), look for the "OK" (instead of "!ROTATOR!") next to the "Slit Pos. Ang." entry in the intgui GUI. Rotate the PAs by 180 deg to fix the problem if it is there. For (b), the Principle Guider (on top) requires a star with 9 < V < 18 (we try to guarantee V < 16), whereas the Secondary Guider (on bottom) requires a star with 9 < V < 16 (we try to guarantee V < 14.5).

You can check these things using the routine "dummy_obsfiles", which creates dummy .obs files based on the results of survey_run_masks (before going on to the next steps).

[edit]

primus_maskgen_method

Choose which objects go on each mask. Currently, I'm doing this using a very simple algorithm (primus_maskgen_simple.pro) which proceeds as follows:

  1. First, it assigns up to 8 reference stars to each mask, limiting one to each chip.
  2. Second, for each priority class, it goes to each mask one at a time and assigns objects in that class that haven't been assigned to a previous class and that do not overlap another object already assigned (ie. of more favored priority).

For the assignment of targets in a particular class, the code tries to assign ALL targets, and then tosses out targets starting with the most crowded until none overlap. Ie. it DOESN'T just randomly subsample, and it also doesn't do anything as prinicipled as Daniel's scheme.

The nice thing about the implementation is that the "overlap" definition is done in a very general way to deal with funny slit geometries, though I think we aren't trying this at first at least.

It makes the following files: 

$PRIMUS_DATA/design/[survey]/masks/deep2_02hr_slits_####.fits
 - list of slits for each mask
$PRIMUS_DATA/design/[survey]/masks/deep2_02hr_mask_conflicts_####.fits 
 - "conflict image" for each mask (i.e. image of where each spectrum will lie)
$PRIMUS_DATA/design/[survey]/masks/deep2_02hr_assign.fits 
 - mask assignment for each target
[edit]

primus_survey_obsfiles

This code just takes the slits files and creates a version of them suitable for input into "maskgen". This produces files with funny names because of maskgen's 8-letter filename convention "issues". These names are of the form: 

aaaa####.obs
aaaa####.dat

Where "####" indicates the mask number and "aaaa" is a four letter prefix unique to a survey and run (and assigned in the "survey_run_masks" routine).

When the .obs files are made, we often want to adjust the slit positions just a little bit. This is because, although the ADC takes out the differential refraction term, it does not take out the refraction term as a whole, so the field is squashed when you are looking at highish airmass. This matters little if you have long enough slits aligned with the parallactic angle, but for our short slits, which are not necessarily align, we pay a little bit in misalignment due to this effect.

To account for this we drill the holes slightly squashed given what we think the local siderial time will be for an observation (with the understanding that if we are slightly off that time it is okay). The file: 

$PRIMUS_DIR/data/primus_masks_refrac_[survey]_[run].par

contains the estimated LST for each mask.

[edit]

primus_masks_stats

This code creates a statistics file and QA plots. The statistics file is called: 

$PRIMUS_DATA/design/[survey]/masks/[survey]_masks_stats.fits

It contains the columns (among possibly others): 

MASK - mask number
NTARGETS - number of slits on mask
RACEN - "center" in J2000 deg
DECCEN - "center" in J2000 deg
PA - position angle of slits (deg E of N)
PRIORITY - list of priority numbers
PNAMES - names of each priority class
NPRIORITY - number of slits in each class
NPOSSIBLE - number of possible slits in each class 
SURVEY - name of survey
RUN - name of run

Note that NPOSSIBLE counts all possible targets, even ones which are slits on other masks.

The code also creates for each mask a QA file: 

 $PRIMUS_DATA/design/[survey]/masks/[survey].mask-####.ps

which shows the mask design.

In the upper left it shows the survey and run names, along with the names of the .obs file, position angle, and center. On the upper right it shows a list of all the priorities, the symbols used to show them, and the NPRIORITY and NPOSSIBLE numbers for each.

The plot on the bottom shows the coverage of the mask (with the bright star mask cut out) as a grey region. Little black dots show all the targets in the mask. The larger symbols are objects with slits (sizes and colors are set by their priorities --- larger is higher priority). The black squares are alignment (REFERENCE) star holes. The numbered rectangles are the IMACS CCD coverages.

[edit]

Checking that a run is "good"

After the mask design is done, you have to go through some sanity checks to make sure everything worked all right. These are:

  1. On the .obs file, run "intgui" and check:
    1. that there is no !ROTATOR! issue (change PA by 180 deg to fix)
    2. that in Skywin there is a star with 9 < V < 16 in the Principal Guider (on top); make sure it is not too near the edge, because of the nod. (The faint limit is teachnically 18, but we are being careful).
    3. that in Skywin there is a star with 9 < V < 14.5 in the Secondary Guider (on bottom); make sure it is not too near the edge, because of the nod. (The faint limit is teachnically 16, but we are being careful).
  2. For each mask, open the conflicts image and verify that it doesn't have any pixels above unity
  3. From the QA plot make sure there are one or two REFERENCE stars in each CCD.
  4. From the QA plot make sure there are at least 8 REFERENCE stars.
  5. Check the numbers of the targets of each priority to make sure they make sense.
  6. Make sure there are not a ridiculous number of sky slits
  7. Make sure there are some calibration stars
  8. Make sure that the nod is in the proper direction, and that the slits are separated by the right amount
  9. Have you remembered to set the refraction angle file?
[edit]

Submitting a Mask to LCO

You'll need the latest lsi distribution from ftp.ociw.edu/pub/clardy/lsi.tgz, which writes the machine readable mask cutting instructions. You'll also need the full GMAP catalogs if you want to run the Skyview option in "lsi/intgui"

For each mask you want to submit, you need two files for a given design, let's take cosb0127 as an example. You need cosb0127.obs and cosb0127.dat

1) Check carefully the .obs files to insure that the SLITSIZE line is correct, currently we want the line to look like this in all files: 

 SLITSIZE   1.0000 0.8 0.8 0.00

Save and overwrite the .obs file if needed.

2) This step is optional and is only necessary to double check that guide stars are available and adds the guide star info into the .obs file for later use (But nobody actually uses this information anyway). 

 a)  From the directory with the mask files:  intgui cosb0127    (no need to append .obs)
 b)  Pull down the option "Skywin" under the "Options" menu
 c)  Check center, orientation and availibility of V~15 guide stars in the blue bananas where the guide probes can access.  The lower star should be brighter if possible, V < 14.
 b)  Choose SaveExit in the File Menu back on the Main Screen.

3) maskgen -w -r -s cosb0127 

 a) This generates an SMF file, which we need to run the reduction code as well.
 b) The -r flag specifies reordering for optimal cutting time.
 c) This usually takes about 10 minutes to run

4) maskcut +e -r cosb0127 

 a) Makes a laser machine readable Icosb0127.nc file

5) Start up IDL and use the command, "reorder". 

 IDL> reorder, 'cosb0127'

 a) This picks out one slit near an optimal place in the focal plane to put at the start of the list.
 b) We think this helps with the quality of the laser cutting run, but now I'm not so sure
 c) It makes a backup file of the .SMF file, leaves the .nc file alone, and makes a new .SMF file


Once you've made all the .SMF files you need to submit, you have two options. The first is two submit the .SMF files to the lco mask database at: http://percey.lco.cl/masks/ Beware, you can only submit 1 MB of uncompressed .SMF files at at time. That's 2 or 3 .SMF files for us. The second option is to make a huge compressed tar file of BOTH the .SMF and .nc files and send to one of the support crew at LCO. I've been sending the ones for 2006 to David Osip.

Next, copy all of the new .SMF files to primus/design/SMF/ and check into CVS

And if you're really gung ho, you can invoke the command: 

  obscat -f primus_observing.cat "List of .SMF Files you just made"

This will output a Magellan readable catalog file that you should also check into CVS if you bothered to create it. This step can also be run on the mountain if the observers have the .SMF files available.

Retrieved from "http://howdy.physics.nyu.edu/index.php/PRIMUS_Mask_Generation"