The following is a standard readme file on how to use auto_aor.py
to automatically generate Spizter AORs.

Last updated: Sun Feb  1 19:36:36 EST 2009

Contents -
 1. Preparation
    - a. Needed modules
    - b. The tep file
    - c. The aai file
    - d. The vis file
 2. Running the program
    - a. Syntax
    - b. Output
 3. FAQ

Please read over this file before you use the software to make
an automatic AOR.
 

1. PREPARATION
   
 - a. NEEDED MODULES
   
   The package NUMPY must be installed if you are to run AutoAOR. If you
   are reading this in Dr. Joe Harrington's lab, then it's installed.  If not, 
   please find a download mirror off the web and download/install with the 
   standard installation.

   AutoAOR also uses custom developed modules for generating timing constraints,
   which are most likely in its default directory.  These are SPITZTIMINGREP,
   SPITZTIMING, JULDAY, CALDAT, and CIRCORBPHASE.  In order for AutoAOR to work,
   these modules must either be in the same directory as AutoAOR, or they are 
   in the directory that your PYTHONPATH points to.  PYTHONPATH refers to a 
   variable in your .bashrc file, which contains a directory (ie: ~/lib/python) 
   to search for all importable modules.  Regardless of what you have set, 
   Python also always searches for modules in the default PYTHONPATH, which is 
   usually set to the directory /usr/local/lib/python.

   If these modules are not installed, AutoAOR WILL NOT WORK.


 - b. THE TEP FILE

   AutoAOR uses two files as input correctly.  The main file which contains 
   most of the planetary parameters is known as the tep file 
   (filename: <object>.tep). A template for the most recent version 
   (AS OF HEADER LAST UPDATED DATE) is located in /home/esp01/runs/seclsn 
   as planettemplate-3.tep.  Before you run AutoAOR, you need to have one of 
   these files completed with AS MUCH INFORMATION AS POSSIBLE to ensure AutoAOR 
   runs correctly.  ANY MISSING VALUES MAY CAUSE THE SOFTWARE TO RUN 
   INCORRECTLY, OR NOT RUN AT ALL.  Also, be sure to follow the strict 
   formatting of the tep file (that is, no spaces, etc.) to ensure the program 
   runs.

 
 - c. THE AAI FILE
   
   On top of the tep file, AutoAOR also uses a special file known as the INPUT 
   file. This is a standard text file, which is very similar to the tep file, 
   except it contains parameters that are unique to AutoAOR and AOR creation in 
   general.  This file needs to be FULLY COMPLETED FOR AUTOAOR TO WORK PROPERLY.
   Parameters which can be left as defaults are listed in the file, so please 
   examine that for more details. The most recent template 
   (AS OF HEADER LAST UPDATED DATE) is located in:
   
   /home/esp01/runs/planetephem/auto_aor/ as aor_input_template.aai

   (aai stands for Auto Aor Input)

   Please make a copy of this file and fill it out accordingly.  Name the file 
   based on the current naming convention. SAVE YOUR BACKUPS.  If you need to
   make a correction, MAKE A NEW FILE and NAME IT ACCORDINGLY.  Dr. Harrington
   has a very specific naming convention for these types of files so see him
   for more information (currently, the naming convention is as follows:
   <object>-<event>-ch<channel(s)>-<yyyy>-<mm>-<dd>-<filenum>.<filetype> where
   filenum represents the number in order of creation of that file for THAT
   DATE.)

   When it is named correctly, its time to fill it out.  Although the .aai file
   has comments documenting the contents of the file, included below is a
   specific overview of the contents of the .aai file, and how to fill it out
   accordingly:

   The header contains some general information about the file, its version,
   and misc. formatting.  Please read it before you proceed.

   A little lower, still in the comment header, you will find some the text
   <name of this file>.  Feel free to change this to the name of the file
   you are editing for easier reference when it is open.  Although not
   necessary to the operation of the AOR machine, this particular field
   can be quite useful and keeps you that much more organized.
   
   Below this lies the body of the .aai.  Proper formatting is needed for
   the program to run correctly, so PLEASE PAY ATTENTION TO THE FOLLOWING:

   THE PROPER FORMAT FOR EACH PARAMETER:
   -------------------------------------
 
   mission
    - Enter warm if you are making an AOR for Warm Spitzer and vice
      versa.

   filename
    - Must be a string (no spaces). A value of -1 tells auto_aor to
      generate its own filename.  This will be a file based off of the
      current naming convention.
	
   shotnum
    - The number of the current shot for the specific object.  For example,
      if the object has been shot three times before, and you are working
      on a new AOR, the shotnum would be 4.  THESE NUMBERS MUST BE REAL,
      NUMERICAL VALUES!! (ie: 4 instead of four)

   chan
    - The channel(s).  Once again, numerical values are needed.  If there
      is more than one channel, specify it as a single decimal (ie: channels
      2 & 4 would be 24).  Keep in mind that only full array observations
      can shoot in more than one channel simultaneously, and these can
      either be channels 2 & 4 or 1 & 3.  Trying to generate a subarray
      observation with more than one channel will cause an error and 
      the program will not run. -1 defaults to 0.

   event
    - STRING LITERALS.  The event of the AOR.  Either 'eclipse' or 'transit'
      without the quotes will work.  Anything else will default event to
      eclipse.

   readmode
    - REQUIRED AS OF v1.x of auto_aor.  Read the source if you are not
      sure which version you are using.  Only TWO values are accepted
      for this parameter, and they are the LITERAL STRINGS 'full_array'
      and 'subarray', without the quotes.  If STELLAR MODE observations
      are desired, please note the following:
       - As of Wed Jan 14 14:42:15 EST 2009, Dr. Harrington specifically
         specifies that observations in stellar mode MUST have a (2x2)/12
	 exposure time.
       - Notice that the particular exposure time of (2x2)/12 is only 
         available in stellar mode, not any others.
       - Also, Spot still counts stellar mode observations as full array
         observations, except stellar mode is a toggle-able option.
       - Therefore, IF YOU WISH TO SHOOT IN STELLAR MODE, THE PARAMETER
       	 READMODE MUST BE FULL_ARRAY AND THE PARAMETER FRAMETIME MUST BE
	 (2x2)/12
    - If these particular rules are not followed for readmode, then you
      will not be able to make an AOR (it will not work)

   frametime
    - REQUIRED IF READMODE IS SPECIFIED.
    - Although exposure times are numbers, the input file requires them to be
      literal strings.  That is, auto_aor is very sensitive to the formatting 
      of this field.
    - THE FOLLOWING ARE THE ONLY ACCEPTED VALUES:
      - 12
      - 2
      - (2x2)/12
      - 0.4
      - 0.02
    - The last two values work in subarray mode ONLY.  Please input these in 
      the exact format they are listed here.  Any other formatting will not 
      work correctly.

   nframes
    - This is the number of frames that you wish to be shot for the science
      observation.  If this is omitted, they will be calculated.

   duration
    - In seconds, this is the duration of the science AOR.  This value will 
      also be calculated if omitted from the input.

   off_row
    - The row offsets.  Calculated if omitted.

   off_col
    - The column offsets.  Calculated if omitted.

   pre_ra
    - The right ascension of the preflash target.  If the observation requires 
      a preflash and this value is omitted, the preflash target is set to the 
      same coordinates as the science observation. See the .aai template for 
      the format.

   pre_dec
    - The declination of the preflash target.  Ditto.

   co_ra
    - Check-out observation right ascension. Ditto.

   co_dec
    - Check-out observation declination. Ditto.

   toff
    - Ephemeris time offset. Defaults to 0.  An example is if you list Ttrans 
      in the tepfile as 4578.9821.  You need to offset it by 2450000 to 
      represent a valid Julian date.

   ctrshift
    - Seconds, center shift later (start/stop earlier).  Changing this will 
      start the observation at a time offset from the start of the event.  
      Default is zero.  Most observations will leave this as its default 
      value.

   startwin
    - Defaults to 1800 seconds.  Used to generate the correct timing 
      constraints. Most observations will use the default value. DO NOT 
      CHANGE UNLESS YOU KNOW WHAT YOU ARE DOING.
          
   obswin
    - The dates of the open and close of a particular observation window.  
      These come directly from SPOT, and will change depending many factors 
      with Spitzer.  Each new window must be on its own line, with the 
      parameter obswin in front of each date.  Please follow the strict format 
      shown in the .aai template.
    - This is an optional parameter, provinding that your .vis file is not
      empty.  If these are specified while you have a full vis file, the 
      windows listed as this parameter will take precedence.

   You and also use the .aai file to override ANY of the values in the .tep 
   file. To do so, just list the parameter, its value, and its uncert. 
   respectively on a separate line.  There is a special section to do this in 
   the .aai file.  In order for overriding to work properly, the parameter 
   must identical to its tep equivalent.  That is, proper spelling, proper 
   case, and proper spacing.

   Once this file is complete, you are ready to make your AOR.


 - d. THE VIS FILE
   
   These files have the spitzer visibility windows of the object you are
   observing.  This file is made from SPOT, and should be named accordingly
   (naming convention.vis).  To make this file, create a new target in SPOT
   and calculate its visibility windows.  Then file->save visibility windows
   as->filename.vis.  Pass this into auto_aor as the FOURTH command line 
   parameter.   

2. RUNNING THE PROGRAM

 - a. SYNTAX

   The syntax for running AutoAOR is as follows:
   
   <script> <tep file> <input file> <vis file>

   ORDER IS IMPORTANT!

   The syntax for running the script should be ./auto_aor.py or auto_aor.py.  
   If the file does not execute, check the permissions of the script.  It 
   should read -rwxrwxr-x.  If it does not, execute the following command:
   
   chmod +x <script>

   Now it should be an executable, and show up as BOLD GREEN when any list 
   directory commands are passed in the shell.

   All exceptions from AutoAOR are handled by the program, so when something 
   goes wrong, you will only be notified that it did, rather than seeing its 
   precise runtime error.  A few general exceptions are caught (for example, 
   wrong filename parameters result in an IOError, in which AutoAOR will tell 
   you that you need to fix the filenames), yet many are just passed as 
   standard errors.  For more information on runtime errors, see FAQ
   (section 3.).

   If you need to debug the script for any reason, use the following syntax 
   when you go to run the application:

   <script> <tep file> <input file> <vis file> debug

   Passing the word 'debug' as the fourth parameter evokes PDB 
   (Python Debugger) and allows you to track down where your errors are 
   coming from.  Some knowledge of Python is assumed if you are in debug mode.

 
 - b. OUTPUT
 
   If you did everything correctly (input formatting, etc.), when you run 
   AutoAOR you should see some output on the screen.  This is the generated AOR.
    Also, in your current working directory, you should see a newly generated 
   AOR.  If you did not specify a filename to use in the input file, then it 
   will be named based off of the current naming convention.  On top of this, 
   if you scroll up to the start of the output generation on the screen, you 
   will see the uncertainties for the timing constraints generated.

   Besides the AOR, another important file is also produced in output.  In 
   the working directory, you will see another file with a name very similar
   to the aor, except with the prefix -diag-auto.out.  This file contains all
   the diagnostic information of the event and the timing constraints.  All
   of the information for each event is present (uncertainties and timing
   constraints for transit + eclipse).  Take a look at this file.  It is very
   important when it comes to deciding if your times are correct.

   Open Spot and import the AOR.  If it works, check it for correctness 
   (targeting, names, etc.)  If it does not, look at Spot's error messages 
   closely.  Usually they will tell you the issues and the line they are  
   located on.

   Thats it!  You made an AOR!


3. FAQ

 - Q. I keep getting an error saying to check my input files..

 - A. That means that AutoAOR does not like something in your input, either in 
      the tep file or the txt file.  Make sure you followed all the formatting 
      rules, and your values are correct.  On top of ill-formatted data, 
      incorrect data will also yield errors. For example, having an eclphase of 
      1827551, which is obviously incorrect, may yield to calculation errors 
      in the software, thus causing it to crash. DOUBLE CHECK YOUR INPUT.

 - Q. Spot does not read the AOR correctly...

 - A. Once again, this is most likely caused by incorrect input formatting.  
      AutoAOR assumes some general knowledge of AOR construction.  Perfectly 
      formatted files will not cause errors and Spot will read them without 
      a fuss.  Once again, double check your input for wrong values, formatting 
      errors, and even incompatibilities/contradictions of values 
      (ie: (2x2)/12 frametime in subarray mode).

 - Q. The duration estimates are missing...

 - A. Recompute all estimates in Spot.  All auto-generated AORs will come 
      without the estimates.

Please email any questions, comments, or bugs to ccampo@gmail.com