Facilities

Base Facility Class

class tom_observations.facility.GenericObservationFacility

The facility class contains all the logic specific to the facility it is written for. Some methods are used only internally (starting with an underscore) but some need to be implemented by all facility classes. All facilities should inherit from this class which provides some base functionality. In order to make use of a facility class, add the path to TOM_FACILITY_CLASSES in your settings.py.

For an implementation example, please see https://github.com/TOMToolkit/tom_base/blob/master/tom_observations/facilities/lco.py

abstract get_form(observation_type)

This method takes in an observation type and returns the form type that matches it.

abstract submit_observation(observation_payload)

This method takes in the serialized data from the form and actually submits the observation to the remote api

abstract validate_observation(observation_payload)

Same thing as submit_observation, but a dry run. You can skip this in different modules by just using “pass”

abstract get_observation_url(observation_id)

Takes an observation id and return the url for which a user can view the observation at an external location. In this case, we return a URL to the LCO observation portal’s observation record page.

get_flux_constant()

Returns the astropy quantity that a facility uses for its spectral flux conversion.

get_wavelength_units()

Returns the astropy units that a facility uses for its spectral wavelengths

is_fits_facility(header)

Returns True if the FITS header is from this facility based on valid keywords and associated values, False otherwise.

get_start_end_keywords()

Returns the keywords representing the start and end of an observation window for a facility. Defaults to start and end.

abstract get_terminal_observing_states()

Returns the states for which an observation is not expected to change.

abstract get_observing_sites()

Return a list of dictionaries that contain the information necessary to be used in the planning (visibility) tool. The list should contain dictionaries each that contain sitecode, latitude, longitude and elevation.

abstract get_observation_status(observation_id)

Return the status for a single observation. observation_id should be able to be used to retrieve the status from the external service.

abstract data_products(observation_id, product_id=None)

Using an observation_id, retrieve a list of the data products that belong to this observation. In this case, the LCO module retrieves a list of frames from the LCO data archive.

class tom_observations.facility.GenericObservationForm(*args, **kwargs)

This is the class that is responsible for displaying the observation request form. Facility classes that provide a form should subclass this form. It provides some base shared functionality. Extra fields are provided below. The layout is handled by Django crispy forms which allows customizability of the form layout without needing to write html templates: https://django-crispy-forms.readthedocs.io/en/d-0/layouts.html See the documentation on Django forms for more information.

For an implementation example please see https://github.com/TOMToolkit/tom_base/blob/master/tom_observations/facilities/lco.py#L132

observation_payload()

This method is called to extract the data from the form into a dictionary that can be used by the rest of the module. In the base implementation it simply dumps the form into a json string.

Gemini

class tom_observations.facilities.gemini.GEMObservationForm(*args, **kwargs)

The GEMObservationForm defines and collects the parameters for the Gemini Target of Opportunity (ToO) observation request API. The Gemini ToO process is described at

https://www.gemini.edu/node/11005

The team must have have an approved ToO program on Gemini and define ToO template observations, complete observations without defined targets, during the Phase 2 process. Authentication is done via a “User key” tied to an email address. See the following page for help on getting a user key and the password needed for the trigger request.

https://www.gemini.edu/node/12109

The following parameters are available.

prog - program id email - email address for user key password - password for user key associated with email, site specific, emailed by the ODB obsnum - id of the template observation to clone and update, must be ‘On Hold’ target - name of the target ra - target RA [J2000], format ‘HH:MM:SS.SS’ dec - target Dec[J2000], format ‘DD:MM:SS.SSS’ mags - target magnitude information (optional) note - text to include in a “Finding Chart” note (optional) posangle - position angle [degrees E of N], defaults to 0 (optional) exptime - exposure time [seconds], if not given then value in template used (optional) group - name of the group for the new observation (optional) gstarget - name of guide star (optional, but must be set if any gs* parameter given) gsra - guide star RA [J2000] (optional, but must be set if any gs* parameter given) gsdec - guide star Dec[J2000] (optional, but must be set if any gs* parameter given) gsmags - guide star magnitude (optional) gsprobe - PWFS1, PWFS2, OIWFS, or AOWFS (optional, but must be set if any gs* parameter given) ready - if “true” set the status to “Prepared/Ready”, otherwise remains at “On Hold” (default “true”) windowDate - interpreted in UTC in the format ‘YYYY-MM-DD’ windowTime - interpreted in UTC in the format ‘HH:MM’ windowDuration - integer hours elevationType - “none”, “hourAngle”, or “airmass” elevationMin - minimum value for hourAngle/airmass elevationMax - maximum value for hourAngle/airmass

The server authenticates the request, finds the matching template observation, clones it, and then updates it with the remainder of the information. That way the template observation can be reused in the future. The target name, ra, and dec are straightforward. The note text is added to a new note, the identified purpose of which is to contain a link to a finding chart. The “ready” parameter is used to determine whether to mark the observation as “Prepared” (and thereby generate the TOO trigger) or keep it “On Hold”.

The exposure time parameter, if given, only sets the exposure time in the instrument “static component”, which is tied to the first sequence step. Any exposure times defined in additional instrument iterators in the template observation sequence will not be changed. If the exposure time is not given then the value defined in the template observation is used. The exposure time must be an integer between 1 and 1200 seconds.

If the group is specified and it does not exist (using a case-sensitive match) then a new group is created.

The guide star ra, dec, and probe are optional but recommended since there is no guarantee, especially for GMOS, that a guide star will be available at the requested position angle. If no guide star is given then the OT will attempt to find a guide star. If any gs* parameter is specified, then gsra, gsdec, and gsprobe must all be specified. Otherwise an HTTP 400 (Bad Request) is returned with the message “guide star not completely specified”. If gstarget is missing or “” but other gs* parameters are present, then it defaults to “GS”.

If “target”, “ra”, or “dec” are missing, then an HTTP 400 (Bad Request) is returned with the name of the missing parameter.

If any ra, dec, or guide probe parameter cannot be parsed, it also generates a bad request response.

Magnitudes are optional, but when supplied must contain all three elements (value, band, system). Multiple magnitudes can be supplied; use a comma to delimit them (for example “24.2/U/Vega,23.4/r/AB”). Magnitudes can be specified in Vega, AB or Jy systems in the following bands: u, U, B, g, V, UC, r, R, i, I, z, Y, J, H, K, L, M, N, Q, AP.

class tom_observations.facilities.gemini.GEMFacility

The GEMFacility is the interface to the Gemini Telescope. For information regarding Gemini observing and the available parameters, please see https://www.gemini.edu/sciops/observing-gemini.

Las Cumbres Observatory

class tom_observations.facilities.lco.LCOFacility

The LCOFacility is the interface to the Las Cumbres Observatory Observation Portal. For information regarding LCO observing and the available parameters, please see https://observe.lco.global/help/.

is_fits_facility(header)

Returns True if the ‘ORIGIN’ keyword is in the given FITS header and contains the value ‘LCOGT’, False otherwise.

Parameters

header (dictionary-like) – FITS header object

Returns

True if header matches LCOGT, False otherwise

Return type

boolean

SOAR

class tom_observations.facilities.soar.SOARFacility

The SOARFacility is the interface to the SOAR Telescope. For information regarding SOAR observing and the available parameters, please see http://www.ctio.noao.edu/soar/content/observing-soar.