Writing LUCI2 Scripts


Nov 2015 !! Note: The G210 grating in LUCI2 is currently having some trouble stabilizing for central wavelengths in the K band below 2.24 microns.  Above this, or in other bands, it seems to have little trouble.  It is not clear why it is having this trouble.  We recommend for now that any K-band observations be set up either with the G200+HKspec or use a CWL higher than 2.24 microns.  


 

Introduction

Notes on Binocular Observations

Getting Help

What you need before running Scriptor

Remaining Known Issues with Scriptor

What Scriptor does NOT do

Scriptor

Page 1: Tell Scriptor what you want to do

Page 2: Set up your Observation

Also on Page 2: Create your ObsItems

Add a Telluric and Calibrations

Page 3: Download your Script(s)

Dither Patterns

Additional notes on:

  • Imaging
  • Spectroscopic Acquisitions
  • Long-Slit Spectroscopy
  • MOS Spectroscopy
  • Telluric Stars
  • Calibrations
  • Finding Charts

  ! Only FIREFOX is supported !  

Other browsers may encounter significant and silent errors!


Introduction

Aside from the new-generation Hawaii-2RG detector and AO camera, the other major change from LUCI1 to LUCI2 is a completely new software control system and the scripting that will eventually drive both LUCIs.  This webpage is a guide to using Scriptor, a web-based tool for generating LUCI2 scripts.  Keep in mind, however, that the basic approach to infrared observing is the same as for LUCI1 or any other near-infrared instrument.

Scriptor generates an XML file that describes the operation of the instrument and interaction with the LBT.  While it is possible to figure out what the script is doing by reading the XML itself, the XML tags are not always clearly understandable (for example, both X and Y offsets are labeled coord) and the attributes are not always intuitive (filters and some other mechanisms are referred to by position and not by name). Thus:

We strongly discourage any manual editing of LUCI2 scripts!

If you had prepared LUCI1 observations before, you will know the old LUCI1-style scripts had separate sections for setting up the archive information and configuring the instrument, telescope, and readout of the detector, then an observing section that allowed for dithering and taking data.  In the LUCI2 paradigm, each observation is laid out as an “Observation Item” (hereafter referred to as an ObsItem) that allows complete control of the telescope position, instrument and readout configurations for both LUCIs.  This allows one to build more complex scripts, as well as combine the formerly separate spectroscopic acquisition and science scripts that LUCI1 needed into a single XML file.

The URL for scriptor is http://scriptor.lbto.org/, and it works in a FIREFOX browser.  Only firefox will be supported.  Scriptor is python code that dynamically (re)generates the HTML sent to the browser.  As you use Scriptor, it will reconfigure defaults and some other aspects of its presentation to you depending on the information you provide.

The LUCI2 Scriptor was built with the eventual move to binocular operations and also adaptive optics in mind, and we need these functions to remain active for commissioning tasks in 2015B.  For now please stick with seeing-limited imaging, long-slit or mos observations and the associated calibrations.

 

Notes on Binocular Observations

2016B Binocular observations with two LUCIs are tentatively being offered in shared risk mode in Semester 2016B.  Scriptor does not directly create binocular scripts.  We have an external bit of software that will “twin” a script built for either LUCI. We recommend you build a monocular LUCI2 script with Scriptor to do your observations, and include clear instructions to the observer to twin them on the fly.

 

Getting Help

If you run into any issues generating LUCI2 scripts or you want to do something really non-standard or cannot figure out how to do it with Scriptor, please contact the LBT Science Operations group.  If you think you found a bug, please verify the problem is repeatable and then send detailed notes and any scripts you generated to ScienceOps.

What you need before running Scriptor

  • Coordinates and PA for your science target (these are in the LMS file for MOS observations)
  • LMS file if this observations uses a custom MOS mask
  • From the ETC, understand your individual (DIT) and total exposure times

Remaining Known Issues with Scriptor

  • We are still working on making calibration script generation automatic, in particular for MOS masks
  • Hitting “Enter” while working with Scriptor is like clicking the “Submit” button
  • Not all possible errors are handled correctly.  If you run into the purple python error screen, your best option is to go back to page 1, click the  Reset Form  button, and try again from the beginning
  • If you run into any odd or unexpected behavior, try the  Reset Form  button

What Scriptor does NOT do

  • Does NOT make acceptable finding charts (see this guide)
  • Cannot design a MOS observing script without an LMS file
  • Does not run reliably in other browsers, only FIREFOX is supported!

Scriptor

! Only FIREFOX is supported !

Open FIREFOX and go to the URL http://scriptor.lbto.org/ as you follow the rest of this help page.

 

Page 1: Tell Scriptor what you plan to do

The initial Scriptor page gathers some basic information about what you want to do so that the next page(s) can be configured appropriately.  At top right is a  Reset Form  button that will clear out all information you might have entered into Scriptor and revert back to the defaults.

  • Select one of: Create new script, Edit script, or Upload LMS file

If you select either edit or upload you will get browse button you can use to navigate to and select the local file you want, then click upload.

  • Choice of Instrument(s): LUCI1 or LUCI2

You can select either instrument, but for now LUCI2 is the default.  Future LUCI1 scripts will be generated in the LUCI2 XML format, not the old format.  This will be needed for re-commissioning LUCI1 after the detector upgrade and installation of the N30 camera.  Note that if you upload an LMS file made for LUCI1, the instrument choice selection will default to LUCI1.  Just re-select LUCI2 if you want to create a script for LUCI2 using a LUCI1 LMS file.

  • Observation Mode: Imaging, Longslit, or Calibration

Select the type of observation you want to do, the default is seeing-limited imaging (the diffraction-limited box is unchecked).  Also select whether this is an imaging, longslit, or calibration script you are setting up.  The LMS option will be auto-selected once you upload an LMS file.  This is because the information Scriptor needs to configure the appropriate MOS mask for some future date is included in the LMS file.

When done, click the  Continue  button at the bottom of the page.  The Scriptor Help Page link at the bottom brings you to this page.

Page 2: Set up the Archive and Target Information

The second page is where you will enter all of the information needed to take the observations of your source.  You will want to complete each section before moving on to the next.  As before, if you get really stuck you can always reset to clear out the form and start over.

  • Archive Information

Select the partner(s) to whom these observations belong [only one partner can be selected now].  This is the primary bit of information used by the archive to control distribution of the data.  If you select calibration, data taken by the script will be available to all partners.

Enter the name of the PI for this project, and a proposal ID.  Both of these are free-format strings for use by the PI to make the data eaiser to locate in the archive.  Also enter a root name for the output file(s).

  • Target and Guide Star Parameters

First, enter the target information (RA, Dec, and Position Angle).  The bright and faint guide star limits are set to reasonable defaults, but in particularly dense fields you may change the guide star search limits so you get a manageable number of choices (this can be changed later).  Next, click on the Find/Refresh Guide Stars button.  This will open up a diagram of the LUCI guide star patrol field with the acceptable guide stars labeled (a more detailed diagram can be found here).  Select a specific guide star by clicking the radio button by that star in the table at left.  If you need to adjust the position angle to select a better guide star or restrict the magnitude range, enter the new data in the fields and click the Find/Refresh Guide Stars button again to update the plot.  It may take multiple clicks for the plot to update.

Once you have selected a guide star, click the Submit Reference Stars button.  The plot and tables will go away, replced by a summary line for the selected guide star.  You need to complete the guide star selection before moving on to the next section on Scriptor.

Also on Page 2: Create your ObsItems

Consider the next three segments on page 2 (instrument and readout and observation setups) together.  Because of the format of the new LUCI2 scripts, all are changeable when creating each ObsItem.  Keep in mind that multiple offsets will be executed with identical instrument and readout setups.  You will build up the complete observation of your target by adding the appropriate ObsItems.

Specify the mask, mask position, camera, grating, central wavelength (CWL) and filters in this section.  Normally flexure compensation should be on for all scripts, so this is set by default.  Some of the settings will be automatically set based on what you said you were planning to do.  For example, the acquisition imaging for longslit spectroscopy requires the longslit mask to be in turnout, so the mask position is not changeble for spectroscopic acquisitions.

For the readout setup, specify the detector integration time (DIT) based on your work with the ETC (see this page for additional details about the differences between the old LUCI1 and LUCI2).  You want to integrate (set the DIT) at least long enough to be background-limited, and not so long that you are too close to saturation for anything of interest.  Set the number of DITs (NDIT) to give you a dwell time at each dither position of about a minute to give the wavefront sensor time to cycle and keep the telescope collimated.  Note for spectroscopy NDIT is normally 1 and the DIT is often well over 1 minute.  If your source is bright, we still recommend NDITxDIT ~ 15 sec, long enough to integrate over several guider cycles.  Select line-interlaced read (LIR) mode for observations that are easily background limited, and multiple endpoint read (MER) mode when you need the noise reduction (~1/sqrt[5]) it offers in order to reach the background limit in a reasonable time for particularly low background observations (e.g. at shorter wavelengths, or with higher resolution spectroscopy).  A savemode of integrated will save the sum of all NDITs in that exposure to a single FITS file and is typically used whenever NDIT>1, while a savemode of normal will save each NDIT to a separate FITS file.  It is unusual to use anything other than Nexp=1 for normal observations.

In the observation setup section you specify the offsets (dithers) needed to observe your target.  For spectroscopic programs, you must first complete and add the acquisition imaging ObsItems before you can set up the spectroscopy.  This section also allows you to set how the dithers are to be applied (relative or absolute) and in which coordinate system (RADEC or DETXY).  All offsets are in arcseconds in the tangent plane centered on the coordinates you supplied.  If you specify a blind offset, note that they will always be applied as relative RADEC offsets, independent of what you request in Scriptor.

It is possible to prepare an ASCII text file containing your offsets and upload it into scriptor, and some example dither patterns are provided below.  This allows you to put together a longer or more complex dithering pattern.  Click the radio button and you will get a navigation popup where you can select your offsets file.  Once read in, it will populate the dXdY fields.  You can manually add more offset fields if you need more than the initial 10, as well as repeat a particular pattern multiple times, although repeating a pattern is not recommended for near-infrared observing.  If you do not select keep offsets then the dXdY offset fields will be cleared out when you submit the each ObsItem.

Once you are done with each of your ObsItem setups, click the  Add Obs_item  button.  Repeat as needed to build up your complete observation.  You should see a new line added at the top of the Scriptor page for each ObsItem you add.  They look like this (this example includes both the acquisition imaging [top line] and spectroscopy [bottom line]).  The blue regions on the left correspond to the LUCI1 instrument and readout setups (these should be blank for monocular LUCI2 observations).  The center yellow rectangle represents the target and guide star information.  The two pink recangles on the right correspond to LUCI2 instrument and readout setups.  While similar entries appear in the Observer GUI’s queue panel, Scriptor will summarize all observations taken with the same instrument and readout configuration on one ObsItem entry. This is denoted by the multiplier in the LUCI2 readout setup rectangle for this example spectroscopic acquisition ObsItem (but see Additional Notes on Spectroscopic Acquisitions below about hidden acquisition exposures).

Add a Telluric and Calibrations

Once you have completed the spectroscopic observations of your target, Scriptor will offer you the option to set up a telluric standard [ and also create standard calibration scripts (not yet working) ].  Click on the  Add Telluric & Calibration Scripts  button.  In the telluric observation section that opens you may select a telluric star by spectral type following the Gemini format.  Be careful about the source magnitudes, LUCI2 will saturate on stars brighter than ~8th magnitude in the low-resolution (G200) modes, and brighter than ~7th magnitude in the higher resolution (G210) modes (estimated).

For the acquisition, Scriptor will automatically include a single offset exposure of your source.  You do need to check the filters and exposure info (NDIT x DIT), but the defaults should all be OK.  For the spectroscopy you need to check the exposure information and include appropriate dithers.  An exposure will be taken at each dither position.  For telluric observations through custom MOS slit masks you can choose the different slitlets in which you want to move the telluric and Scriptor will include the appropriate offsets calculated from the information in the LMS file.  You only need to provide offsets if you want more than one exposure through each slitlet you select.

[Not yet working:] For the calibration scripts, you simply need to indicate whether you want them or not.  If requested, scripts will be produced to take lamp-on and lamp-off sets of data for the three arc lamps and appropriate flatfield lamps.  A script to take dark exposures is not produced at this time.

Page 3: Download your script(s)

When you complete the setup of your observation, and any telluric or calibrations that go with it, just click the  Submit  button at the bottom of the page.  This will take you to the file output page.  Click the here link and Scriptor will download your script(s) to your local disk.  If more than one script is made, Scriptor will pack them into a zipped file.

The output script(s) generated by Scriptor will be given default names constructed from the output root filename entered earlier.  These will be an appropriate combination of (with “default” replaced by the output filename root you provided earlier):

  • default_img.xml – imaging script
  • default.xml – spectroscopic acquisition and science
  • default_tell.xml – telluric calibration
  • default_cal.xml – arc and flat lamps

Dither Patterns

The goal of a well-designed dither pattern is to aid in the removal of instrumental signatures from the RAW data, including bad pixels or clusters of bad pixels.  It must also allow a robust measurement of the sky background under every pixel.  Bad pixels are usually a very small fraction of the total, so randomizing your dithering is sufficient.  For a good sky measurement you must move completely off the largest structure on you are trying to measure.  For very extended sources, this often means moving completely off source to obtain a separate measurement of the sky.  In spectroscopic observations you are further constrained in one dimension by the need to keep your science target somewhere along the spatial direction of the slit, but the same considerations apply.

When the total observation on a source consists of just a few exposures, a standard pattern like a dice5 (for imaging) or ABAB (for spectroscopy) will suffice.  But note that for longer total exposures it is better to randomize things a bit more.  Repeating the same base pattern many times to build up a total exposure will bias the measurement of the sky wherever there is an object.  This is easy to understand…consider the typical 2-position ABAB dither pattern commonly used for spectroscopy, where only half of the data (the “B” positions) are available to sky-subtract the “A” data, and vice-versa.  Now consider a 4-position ACBD pattern where 75% of the data can be used as sky for each position in the pattern.  The logical extreme of this is to never repeat positions in any dither pattern.  While difficult to achieve in practice, especially for spectroscopic observations, you can see that potentially all but one exposure in a dataset can be used as sky for each science frame.  This reduces the noise added into the data by the sky-subtraction.

We provide some example dither patterns as ASCII text files in the format that Scriptor expects in this gzipped tar file (this will unpack to a directory called LUCI_DitherPatterns).  These can be uploaded into Scriptor and/or modified as needed.

  • dice5 – an imaging 5-point dither pattern, +/-20″ from the center position, absolute offsets
  • star9 – an imaging 3×3 pattern sequenced to maximize offsets, +/-20″ from the center position, absolute offsets
  • Offsrc_sky – an imaging dither pattern that moves completely off source to take sky data, absolute offsets
  • Random20x – an imaging dither pattern that does 20 randomized points in a 60 arcsec box, absolute offsets
  • ABAB – a standard spectroscopic 2-position dither pattern using relative (must be DETXY) offsets
  • ACBD – a standard spectroscopic 4-position dither pattern using relative (must be DETXY) offsets

Additional notes on:

  • Imaging

Imaging scripts should use absolute offsets as this makes resuming an interrupted sequence of observations much easier to recover.  There is typically no “acquisition” for imaging…you just point and shoot.  If so desired, verify the initial pointing on the first couple of exposures taken.

  • Spectroscopic Acquisitions

A complete spectroscopic acquisition sequence consists of up to five steps:

  1. sky image, optional for bright sources visible above the sky background
  2. source frame to measure the current position of the source
  3. slit image to measure the position of the slit on the detector
  4. source+slit image taken after executing the alignment offset
  5. A blind offset from a nearby star for exceptionally faint targets

Scriptor will automatically include in the XML file the ObsItems to move the mask to the FPU and take the slit image with a pause after to allow calculation of the alignment offset, as well as the subsequent source+slit image with a pause after to allow inspection of the image to verify that the alignment of the mask on the sky is acceptable.  If requested, a blind offset is included as well, but no exposure is taken there.  These steps are not displayed in Scriptor!  However, they will be visible if you read the script back into Scriptor to edit it.  For the acquisition you just need to set up the one or two imaging exposures (filters, DIT, NDIT) needed to see the sources with sufficient SNR for the alignment.  Spectroscopic acquisition imaging should use relative DETXY offsets.  Blind offsets are always applied as relative RADEC offsets.  The slit and source+slit images will be taken with the same settings as the acquisition imaging.  If you are not sure about whether your source is bright enough to skip the sky image, take the sky image!

One key to efficient spectroscopic acquisitions is to know beforehand that your alignment sources are bright enough to centroid on.  How can you tell?  Consult 2MASS!  As a general guide, anything that is visible in 2MASS and not too bright is likely usable for spectroscopic alignment.  Note that sources of K<17 or J<18 (Vega mags) are bright enough to centroid on in all but the worst conditions with a 60-second (20×3.0s) exposure.  Sources brighter than 10th magnitude are getting too bright to use in good conditions.

  • Long-Slit Spectroscopy

There are several scenarios you might encounter where you should pay close attention to the dither pattern you use for longslit spectroscopy, including segmented slits, observing in crowded fields, or orienting the longslit to place two (or more) objects on the slit at the same time.  In all cases, be careful that the dither pattern you set up does not move an important source behind a segmented slit bridge or on top of another object on the slit in a different dither position.

  • MOS Spectroscopy

Because MOS spectroscopy is usually done with relatively short slits (~10 arcsec) the dithering offsets are usually quite small, typically +/-2 arcsec from the initial “aligned” position.

  • Telluric Stars

Telluric stars are usually very bright to minimize the amount of time you spend taking data on the calibrators.  As such, we recommend taking exposures where the source is visible in the acquisition sequence through crossed filters (usually OH1060+z or HeI+z) so the source does not saturate on the detector.  The filters need to be uncrossed for the slit exposure, however, to get enough sky flux on the detector to see where the slit is located.  This is why you do not need to put in any offsets for the telluric observations, Scriptor does this part automatically.

While perfect collimation is not really needed for spectroscopic observations of the telluric stars and they are bright enough to get high SNR in a minimum exposure time, we still recommend integrating for 5×3.0s in order to average over some atmospheric and guiding residuals.  These should be set as the defaults.

  • Calibrations

We are working on getting the calibration scripts to be automatically generated, but this does not work yet.  For longslit or imaging programs, you can create appropriate calibration scripts by clicking the calibration button on the first Scriptor page.

  • Finding Charts

The goal of a finding chart it to allow the observer to immeditately identify the field and the science target, blind offset reference source, or MOS mask alignment stars rapidly.  If it takes longer than 5-10 seconds to identify the field, usually the finding chart is to blame.  A good finding chart should have the following features:

  • Similar depth (and preferably wavelength band) as the acquisition image on LUCI
  • Background image rotated to the requested position angle
  • Scale and orientation clearly marked; if larger than the acquisition FoV then that should be marked as well
  • Science target, blind offset reference source, or MOS mask acquisition stars clearly marked

2MASS makes a decent background image for LUCI acquisitions.  They are available in the JHK bands, and anything you can see on a 2MASS image you can centroid on in a 60s (NDITxDIT) sky-subtracted exposure with LUCI.  Finding charts based on SDSS or DSS images can also work well, but keep in mind that sources can look very different when comparing images taken in the optical and near-IR bands.  The fainter blue sources are often not visible, and red sources can be significantly brighter if you acquire in the K band.  The Hubble Deep Field data from HST makes a terrible finding chart as only one or two of the brightest stars are visible on LUCI in a 60s image.  Here is an example of a decent finding chart, made with an SDSS background image.  Here is the same field using 2MASS for the background.

For MOS spectroscopy it is a good idea to also provide the observers with a printout of the mask pattern with the science slits numbered as in the LMS file and the two (or more) slits in which the telluric will land identified.  This will make the telluric acquisition go faster.