Facilities¶

Base Facility Class¶

class tom_observations.facility.CredentialStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Enum representing the status of facility credentials.

This enum is used to track the state of credentials throughout the facility lifecycle, providing clear information about whether credentials are available, where they came from, and any validation issues.

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

layout() → Layout¶

Define (and return) a crispy_forms.Layout for the fields of your subclass. It will be inserted after the common_layout and before the button_layout, as defined above in __init__(), where self.helper.layout is assigned.

This method should be implemented in your subclass to define the layout of your form fields.

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

Note: This method returns form classes, not instances, to support composite form creation in ObservationCreateView. Use create_form_instance() for direct form instantiation.

create_form_instance(observation_type, **kwargs)¶

Create a form instance with facility context injected.

The ObservationCreateView handles setting the user context on the facility instance via set_user() in its dispatch() method. Forms receive the facility instance and can query it for user-specific data (credentials, API clients, etc.) rather than handling business logic themselves.

Parameters:

observation_type – The type of observation form to create
kwargs – Additional keyword arguments for form instantiation

Returns:

Form instance configured for the observation type

get_form_classes_for_display(**kwargs)¶

This method returns a dictionary of the format:

{‘OBSERVATION_TYPE’: FacilityFormClass}

Typically this will be all or a subset of the forms in self.observation_forms

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.

get_button_label()¶: The label that will appear on observe button

get_button_tooltip()¶: The tooltip that will appear on observe button

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

class tom_observations.facility.BaseRedirectObservationFacility¶

A Redirect Facility is a facility which delegates observation creation to an external website. A RedirectFacility does not need to provide a UI for observation creation, meaning it does not include a Form. It does still implement other methods inherited from BaseObservationFacility, such as those related to fetching status, data products, etc.

Implementations will need to provide the redirect_url method. This constructs a URL that the user will be redirected to. The arguments the target id and a callback URL. The external website should be able to redirect the user back to the callback URL in order to complete the observation creation process on the TOM side, by fetching the observation either by API endpoint or some other means, and storing it in the TOM database.

The passed in callback URL will contain the following query parameters: - target_id: The ID of the target for which the observation was created. - facility: The name of the facility that created the observation.

The remote facility is responsible for adding these query params: - observation_id: The ID of the observation that was created.

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

LCO/SOAR/Blanco Redirect¶

class tom_observations.facilities.lco_redirect.LCORedirectFacility(*args, **kwargs)¶

The LCORedirectFacility is a little different from the other TOMToolkit Facilities. This facility temporarily redirects users from the TOM to the LCO observing portal, providing them with full access to the observation request options provided by that interface. Once the observation, or group of observations, are submitted, the user is redirected back to the TOM. The user must have access to the LCO observing portal, but will log in with their own credentials, rather than those stored by the TOM. In order to retrieve the observations, the TOM must have access to an LCO API token with permission to access the relevant proposals.

For more information on submitting to LCO, Soar, or Blanco, see the LCO Documentation . To use this facility you will need to add it to your TOM_FACILITY_CLASSES list in settings.py and have an api_key in your LCO dictionary in FACILITIES:

settings.py¶

TOM_FACILITY_CLASSES = [
    ...
    'tom_observations.facilities.LCORedirectFacility',
    ...
    ]

FACILITIES = {
    'LCO': {
        'portal_url': 'https://observe.lco.global',
        'api_key': os.getenv('LCO_API_KEY'),
    },
}

request_id_to_group(observation_id, user, target, parameters)¶: The OCS groups individual requests into a single RequestGroup, which is the ID it passes back. This method is responsible for querying the individual request IDs associated with the RequestGroup and mapping them to an ObservationGroup/ObservationRecord in the TOM.

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>, name_override=None)¶

The LCOFacility is the interface to the Las Cumbres Observatory Observation Portal. For information regarding LCO observing and the available parameters, please see the LCO Documentation . To use this facility you will need to update the FACILITIES in your settings.py with a portal_url and an api_key.

settings.py¶

FACILITIES = {
    'LCO': {
        'portal_url': 'https://observe.lco.global',
        'api_key': os.getenv('LCO_API_KEY'),
    },
}

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.

settings.py¶

FACILITIES = {
    'SOAR': {
        'portal_url': 'https://observe.lco.global',
        'api_key': os.getenv('LCO_API_KEY'),
    },
}

Blanco¶

class tom_observations.facilities.blanco.BLANCOImagingObservationForm(*args, **kwargs)¶: The BLANCOImagingObservationForm allows selection of blanco specific instrument parameters

class tom_observations.facilities.blanco.BLANCOFacility(facility_settings=<tom_observations.facilities.blanco.BLANCOSettings object>)¶

The BLANCOFacility is the interface to the BLANCO Telescope. For information regarding BLANCO observing and the available parameters, please see: https://noirlab.edu/science/observing-noirlab/observing-ctio/cerro-tololo/observing-blanco.

Please note that BLANCO 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.

settings.py¶

FACILITIES = {
    'BLANCO': {
        'portal_url': 'https://observe.lco.global',
        'api_key': os.getenv('LCO_API_KEY'),
    },
}

Facilities as `INSTALLED_APPS`¶

The following Facilities are implemented as INSTALLED_APPS. As such, each resides in its own git repository:

Facilities¶

Base Facility Class¶

Gemini¶

LCO/SOAR/Blanco Redirect¶

Las Cumbres Observatory¶

SOAR¶

Blanco¶

Facilities as `INSTALLED_APPS`¶

Navigation

Related Topics

Facilities¶

Base Facility Class¶

Gemini¶

LCO/SOAR/Blanco Redirect¶

Las Cumbres Observatory¶

SOAR¶

Blanco¶

Facilities as INSTALLED_APPS¶

Facilities as `INSTALLED_APPS`¶