Facilities

Base Facility Class

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

This is the class that is responsible for displaying the observation request form. This form is meant to be subclassed by more specific BaseForm classes that represent a form for a particular type of facility. For implementing your own form, please look to the other BaseObservationForms.

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

get_validation_message()

Override this or self.validation_message to return a validation message that is shown when the Validate button is clicked and the form is valid

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.

class tom_observations.facility.BaseRoboticObservationForm(*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.

This specific class is intended for use with robotic facilities, such as LCO, Gemini, and SOAR.

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

tom_observations.facility.GenericObservationForm

alias of tom_observations.facility.BaseRoboticObservationForm

class tom_observations.facility.BaseManualObservationForm(*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.

This specific class is intended for use with classical-style manual facilities.

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

class tom_observations.facility.BaseObservationFacility

This is the class that is responsible for defining the base facility class. This form is meant to be subclassed by more specific BaseFacility classes that represent a form for a particular type of facility. For implementing your own form, please look to the other BaseObservationFacilities.

abstract get_form(observation_type)

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

get_facility_context_data(**kwargs)

This method provides an opportunity for the Facility subclass to add additional context data. It will be called by the OberservationCreateView.get_context_data() method and the context dictionary passed to the template will be updated with the returned facility context dictionary.

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”

Typically called by the ObservationForm.is_valid() method.

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 an iterable of dictionaries that contain the information necessary to be used in the planning (visibility) tool. The iterable should contain dictionaries each that contain sitecode, latitude, longitude and elevation. This is the static information about a site.

get_facility_weather_urls()

Returns a dictionary containing a URL for weather information for each site in the Facility SITES. This is intended to be useful in observation planning.

facility_weather = {‘code’: ‘XYZ’, ‘sites’: [ site_dict, … ]} where site_dict = {‘code’: ‘XYZ’, ‘weather_url’: ‘http://path/to/weather’}

get_facility_status()

Returns a dictionary describing the current availability of the Facility telescopes. This is intended to be useful in observation planning. The top-level (Facility) dictionary has a list of sites. Each site is represented by a site dictionary which has a list of telescopes. Each telescope has an identifier (code) and an status string.

The dictionary hierarchy is of the form:

facility_dict = {‘code’: ‘XYZ’, ‘sites’: [ site_dict, … ]} where site_dict = {‘code’: ‘XYZ’, ‘telescopes’: [ telescope_dict, … ]} where telescope_dict = {‘code’: ‘XYZ’, ‘status’: ‘AVAILABILITY’}

See lco.py for a concrete implementation example.

cancel_observation(observation_id)

Takes an observation id and submits a request to the observatory that the observation be cancelled.

If the cancellation was successful, return True. Otherwise, return False.

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.

class tom_observations.facility.BaseRoboticObservationFacility

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.

This specific class is intended for use with robotic facilities, such as LCO, Gemini, and SOAR.

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

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.

tom_observations.facility.GenericObservationFacility

alias of tom_observations.facility.BaseRoboticObservationFacility

class tom_observations.facility.BaseManualObservationFacility

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.

This specific class is intended for use with classical-style manual facilities.

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) noteTitle - title for the note, “Finding Chart” if not provided (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/observing/start-here

Las Cumbres Observatory

class tom_observations.facilities.lco.LCOSettings(facility_name='LCO')

LCO Specific settings

get_fits_facility_header_value()

Should return the expected value in the fits facility header for data from this facility

class tom_observations.facilities.lco.LCOOldStyleObservationForm(*args, **kwargs)

The LCOOldStyleObservationForm provides the backwards compatibility for the Imaging and Spectral Sequence forms to remain the same as they were previously despite the upgrades to the other LCO forms.

get_instruments()

Filter the instruments from the OCSBaseObservationForm.get_instruments() (i.e. the super class) in an LCO-specifc way.

class tom_observations.facilities.lco.LCOImagingObservationForm(*args, **kwargs)

The LCOImagingObservationForm allows the selection of parameters for observing using LCO’s Imagers. The list of Imagers and their details can be found here: https://lco.global/observatory/instruments/

class tom_observations.facilities.lco.LCOMuscatImagingObservationForm(*args, **kwargs)

The LCOMuscatImagingObservationForm allows the selection of parameter for observing using LCO’s Muscat imaging instrument. More information can be found here: https://lco.global/observatory/instruments/muscat3/

class tom_observations.facilities.lco.LCOSpectroscopyObservationForm(*args, **kwargs)

The LCOSpectroscopyObservationForm allows the selection of parameters for observing using LCO’s Spectrographs. The list of spectrographs and their details can be found here: https://lco.global/observatory/instruments/

class tom_observations.facilities.lco.LCOPhotometricSequenceForm(*args, **kwargs)

The LCOPhotometricSequenceForm provides a form offering a subset of the parameters in the LCOImagingObservationForm. The form is modeled after the Supernova Exchange application’s Photometric Sequence Request Form, and allows the configuration of multiple filters, as well as a more intuitive proactive cadence form.

clean_start()

Unless included in the submission, set the start time to now.

clean_end()

Override clean_end in order to avoid the superclass attempting to date-parse an empty string.

clean()

This clean method does the following:

• Adds an end time that corresponds with the cadence frequency

instrument_choices()

This method returns only the instrument choices available in the current SNEx photometric sequence form.

class tom_observations.facilities.lco.LCOFacility(facility_settings=<tom_observations.facilities.lco.LCOSettings object>)

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/.

SOAR

class tom_observations.facilities.soar.SOARFacility(facility_settings=<tom_observations.facilities.soar.SOARSettings object>)

The SOARFacility is the interface to the SOAR Telescope. For information regarding SOAR observing and the available parameters, please see https://noirlab.edu/science/observing-noirlab/observing-ctio/observing-soar.

Please note that SOAR is only available in AEON-mode. It also uses the LCO API key, so to use this module, the LCO dictionary in FACILITIES in settings.py will need to be completed.