diff --git a/docs/observing/index.rst b/docs/observing/index.rst index 752a68ccc..18048d8df 100644 --- a/docs/observing/index.rst +++ b/docs/observing/index.rst @@ -28,3 +28,5 @@ allow your TOM to submit observation requests to observatories. :doc:`Facility Modules <../api/tom_observations/facilities>` - Take a look at the supported facilities. :doc:`Observation Views <../api/tom_observations/views>` - Familiarize yourself with the available Observation Views. + +:doc:`Selecting Targets ` - Display a selection of targets for a specific observing facility. diff --git a/docs/observing/selecting_targets_for_facility.rst b/docs/observing/selecting_targets_for_facility.rst new file mode 100644 index 000000000..6f4eb0592 --- /dev/null +++ b/docs/observing/selecting_targets_for_facility.rst @@ -0,0 +1,252 @@ +Selecting Targets for an Observing Facility +=========================================== + +During observing runs, particularly at manually- or remotely-operated telescope +facilities, it can often be very useful to display a selection of targets to be +observed on a particular night. This needs to take into account target visibiliy from +the telescope site, as well as any prioritization of targets that the team have made. + +TOMs provide support for this through the Target Selection option under the Target menu +in the main navigation bar. + +.. image:: target_selection_menu_option.png + :alt: Menu option for Target Selection view + +Observers can select the telescope facility that they are observing from using the form +provided, indicating the date of the observing run. The selected targets can be draw +from a predefined Target Grouping, but if none is specified then targets will be drawn +from all of the targets that the user has permission to see. + +The TOM will evaluate the visibility of the selected targets for the telescope on the +night in question, and the resulting table will include all objects with a minimum +airmass less than 2.0. + +.. image:: target_selection_table_default.png + :alt: Default table output for target selection + +Customizing the Selected Targets Table +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, this table will include the essential parameters necessary to point a +telescope at the target, but it can be easily extended to add further information. + +The columns of the table can be configured by editing the TOM's ``settings.py`` file. +Additional parameters can be defined for each target by adding dictionary definitions +to the ``EXTRA_FIELDS`` list, as shown in the example below: + +.. code-block:: python + + # settings.py + EXTRA_FIELDS = [ + {'name': 'Mag_now', 'type': 'number'}, + {'name': 'Priority1', 'type': 'number'}, + {'name': 'Priority2', 'type': 'string'} + ] + SELECTION_EXTRA_FIELDS = [ + 'Mag_now', + 'Priority1', + 'Priority2', + ] + +In this example, we have added ``EXTRA_FIELDS`` named ``Mag_now``, ``Priority1`` +and ``Priority2``, which the user can set either by editing each Target's parameters +directly, or programmatically. Having done so, we can add those ``EXTRA_FIELDS`` to +the target selection table by adding the parameter names to the list of ``SELECTION_EXTRA_FIELDS``. +This produces the table displayed below. + +.. image:: target_selection_table_extra_fields.png + :alt: Target Selection table with additional columns added + + +Adding An Observing Facility to the Target Selection Form +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Target selection form inherits all of the TOM's built-in observing facility classes. +This can be extended to include additional telescopes, including those that are +operated manually, just by declaring a new telescope class. + +In the top level of your TOM's code directory, add a new directory called ``facilities``: + +.. code:: python + + cd mytom/ + mkdir facilities + +:: + + ├── facilities/ + ├── data + ├── db.sqlite3 + ├── manage.py + ├── mytom + │ ├── __init__.py + │ ├── settings.py + │ ├── urls.py + │ └── wsgi.py + ├── static + ├── templates + └── tmp + +We need to add an ``__init__.py`` file to this sub-directory, to let Python know that +this is an application. This file should be empty, so we just create it: + +.. code:: python + + touch facilities/__init__.py + +Now we can create the new telescope facility class within this ``facilities`` directory. +The easiest way to do this is to download a copy of the `example facility `__ +provided in the TOM Toolkit's repository. You can rename this file to distinguish it +from other facilities. In this example, we will add the El Leoncito Astronomical Complex, +also known as CASLEO: + +:: + + ├── facilities/ + │ ├── __init__.py + │ ├── casleo.py + +The new telescope class file can now be updated to provide the essential information +about the site. The code block below highlights the sections of the file that need to be +updated by comparing the default with the customized example. + +First we need to declare the exact location of the observatory site. Note that the sites +dictionary can accept multiple dictionaries, each describing a different site. This is how +the TOM handles observatories that have multiple sites, such as the `LCO network `__. + +.. code:: python + + # casleo.py + + # DEFAULT: + try: + EXAMPLE_MANUAL_SETTINGS = settings.FACILITIES['EXAMPLE_MANUAL'] + except KeyError: + EXAMPLE_MANUAL_SETTINGS = { + } + + EXAMPLE_SITES = { + 'Example Manual Facility': { + 'sitecode': 'Example', + 'latitude': 0.0, + 'longitude': 0.0, + 'elevation': 0.0 + }, + } + EXAMPLE_TERMINAL_OBSERVING_STATES = ['Completed'] + + # UPDATED TO: + try: + CASLEO_SETTINGS = settings.FACILITIES['CASLEO'] + except KeyError: + CASLEO_SETTINGS = { + } + + CASLEO_SITES = { + 'El Leoncito': { + 'sitecode': 'CASLEO', + 'latitude': -31.7986, + 'longitude': -69.2956, + 'elevation': 2483.0 + }, + } + TERMINAL_OBSERVING_STATES = ['Completed'] + +Then we give the facility class a distinctive name: + +.. code:: python + + # casleo.py + + # DEFAULT: + class ExampleManualFacility(BaseManualObservationFacility): + """ + """ + + name = 'Example' + observation_types = [('OBSERVATION', 'Manual Observation')] + + # UPDATED TO: + class CASLEOFacility(BaseManualObservationFacility): + """ + """ + + name = 'El Leoncito' + observation_types = [('OBSERVATION', 'Manual Observation')] + +We also need to update the reference to the list of possible end states of observing requests. +This list can be expanded for telescopes that are programmatically accessible, but it can be left +with the default list for manual facilities. + +.. code:: python + + # casleo.py + + # DEFAULT: + def get_terminal_observing_states(self): + """ + Returns the states for which an observation is not expected + to change. + """ + return EXAMPLE_TERMINAL_OBSERVING_STATES + + + # UPDATED TO: + def get_terminal_observing_states(self): + """ + Returns the states for which an observation is not expected + to change. + """ + return TERMINAL_OBSERVING_STATES + + +Lastly, we need to make sure that the method to fetch the information on observing sites refers to the +list of dictionaries that we specified above. + +.. code:: python + + # casleo.py + + # DEFAULT: + def get_observing_sites(self): + """ + 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. + """ + return EXAMPLE_SITES + + + # UPDATED TO: + def get_observing_sites(self): + """ + 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. + """ + return CASLEO_SITES + + +The new facility is now ready. To make sure that the TOM includes it, +we simply need to add it to our TOM's list of facilities in the ``settings.py`` file: + + +.. code-block:: python + + # settings.py + TOM_FACILITY_CLASSES = [ + 'tom_observations.facilities.lco.LCOFacility', + 'tom_observations.facilities.gemini.GEMFacility', + 'tom_observations.facilities.soar.SOARFacility', + 'facilities.casleo.CASLEOFacility', + ] + + +Returning to the target selection form, the new observatory now appears as +an option in the Observatory pulldown menu. + + +.. image:: target_selection_table_new_facility.png + :alt: Target selection table with new telescope facility added diff --git a/docs/observing/target_selection_menu_option.png b/docs/observing/target_selection_menu_option.png new file mode 100644 index 000000000..ac35cd1a2 Binary files /dev/null and b/docs/observing/target_selection_menu_option.png differ diff --git a/docs/observing/target_selection_table_default.png b/docs/observing/target_selection_table_default.png new file mode 100644 index 000000000..3a2016f61 Binary files /dev/null and b/docs/observing/target_selection_table_default.png differ diff --git a/docs/observing/target_selection_table_extra_fields.png b/docs/observing/target_selection_table_extra_fields.png new file mode 100644 index 000000000..f9214f9fb Binary files /dev/null and b/docs/observing/target_selection_table_extra_fields.png differ diff --git a/docs/observing/target_selection_table_new_facility.png b/docs/observing/target_selection_table_new_facility.png new file mode 100644 index 000000000..74f20fd60 Binary files /dev/null and b/docs/observing/target_selection_table_new_facility.png differ diff --git a/tom_common/templates/tom_common/navbar_content.html b/tom_common/templates/tom_common/navbar_content.html index 7419d9342..27a570cca 100644 --- a/tom_common/templates/tom_common/navbar_content.html +++ b/tom_common/templates/tom_common/navbar_content.html @@ -12,6 +12,7 @@
Targets Target Grouping + Target Selection
  • diff --git a/tom_setup/templates/tom_setup/settings.tmpl b/tom_setup/templates/tom_setup/settings.tmpl index d2d123881..c9198cb94 100644 --- a/tom_setup/templates/tom_setup/settings.tmpl +++ b/tom_setup/templates/tom_setup/settings.tmpl @@ -282,6 +282,7 @@ HARVESTERS = { # {'name': 'dicovery_date', 'type': 'datetime'} # ] EXTRA_FIELDS = [] +SELECTION_EXTRA_FIELDS = [] # Authentication strategy can either be LOCKED (required login for all views) # or READ_ONLY (read only access to views) diff --git a/tom_targets/forms.py b/tom_targets/forms.py index a752ef5ce..ee31ca73d 100644 --- a/tom_targets/forms.py +++ b/tom_targets/forms.py @@ -1,10 +1,11 @@ from django import forms +from django.conf import settings from astropy.coordinates import Angle from astropy import units as u from django.forms import ValidationError, inlineformset_factory -from django.conf import settings from django.contrib.auth.models import Group from guardian.shortcuts import assign_perm, get_groups_with_perms, remove_perm +from tom_observations import facility from tom_dataproducts.sharing import get_sharing_destination_options from .models import ( @@ -203,3 +204,18 @@ class TargetListShareForm(forms.Form): def __init__(self, *args, **kwargs): super().__init__(*args, **kwargs) self.fields['share_destination'].choices = get_sharing_destination_options() + + +class TargetSelectionForm(forms.Form): + """ + Form for selecting the targets from a pre-existing TargetList + """ + target_list = forms.ModelChoiceField( + TargetList.objects.all(), + required=False) + facilities = [(x, x) for x in facility.get_service_classes()] + observatory = forms.ChoiceField(required=True, choices=facilities) + date = forms.DateTimeField(required=True, help_text='YYYY-MM-DD') + + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) diff --git a/tom_targets/templates/tom_targets/target_facility_selection.html b/tom_targets/templates/tom_targets/target_facility_selection.html new file mode 100644 index 000000000..cef5e08f4 --- /dev/null +++ b/tom_targets/templates/tom_targets/target_facility_selection.html @@ -0,0 +1,46 @@ +{% extends 'tom_common/base.html' %} +{% load bootstrap4 targets_extras dataproduct_extras static %} +{% block title %}Target Selection{% endblock %} +{% block additional_css %} + +{% endblock %} +{% block content %} +

    Select Targets for an Observing Facility

    +
    +
    + {% csrf_token %} +
    +
    + {% bootstrap_field form.observatory %} +
    +
    + {% bootstrap_field form.date %} +
    +
    + {% bootstrap_field form.target_list %} +
    +
    + +
    +
    +
    +
    +
    + {% if observable_targets %} + + + {% for col in table_columns %} + + {% endfor %} + + {% for entry in observable_targets %} + + {% for item in entry %} + + {% endfor %} + + {% endfor %} + {% endif %} +
    {{col}}
    {{item}}
    +
    +{% endblock %} \ No newline at end of file diff --git a/tom_targets/urls.py b/tom_targets/urls.py index 8abfd394b..7c7a7c0fb 100644 --- a/tom_targets/urls.py +++ b/tom_targets/urls.py @@ -4,6 +4,7 @@ from .views import TargetDeleteView, TargetListView, TargetImportView, TargetExportView, TargetShareView from .views import TargetGroupingView, TargetGroupingDeleteView, TargetGroupingCreateView, TargetAddRemoveGroupingView from .views import TargetGroupingShareView, TargetHermesPreloadView, TargetGroupingHermesPreloadView +from .views import TargetFacilitySelectionView from .api_views import TargetViewSet, TargetExtraViewSet, TargetNameViewSet, TargetListViewSet from tom_common.api_router import SharedAPIRootRouter @@ -34,5 +35,6 @@ path('targetgrouping//share/', TargetGroupingShareView.as_view(), name='share-group'), path('targetgrouping//hermes-preload/', TargetGroupingHermesPreloadView.as_view(), name='group-hermes-preload'), + path('targetselection/', TargetFacilitySelectionView.as_view(), name='target-selection'), ] diff --git a/tom_targets/views.py b/tom_targets/views.py index 1c4229281..f976e918a 100644 --- a/tom_targets/views.py +++ b/tom_targets/views.py @@ -33,7 +33,7 @@ from tom_observations.models import ObservationTemplate from tom_targets.filters import TargetFilter from tom_targets.forms import SiderealTargetCreateForm, NonSiderealTargetCreateForm, TargetExtraFormset -from tom_targets.forms import TargetNamesFormset, TargetShareForm, TargetListShareForm +from tom_targets.forms import TargetNamesFormset, TargetShareForm, TargetListShareForm, TargetSelectionForm from tom_targets.sharing import share_target_with_tom from tom_dataproducts.sharing import (share_data_with_hermes, share_data_with_tom, sharing_feedback_handler, share_target_list_with_hermes) @@ -44,8 +44,11 @@ ) from tom_targets.models import Target, TargetList from tom_targets.utils import import_targets, export_targets +from tom_observations.utils import get_sidereal_visibility from tom_dataproducts.alertstreams.hermes import BuildHermesMessage, preload_to_hermes - +import numpy as np +from astropy.coordinates import SkyCoord +from astropy import units as u logger = logging.getLogger(__name__) @@ -749,3 +752,97 @@ def post(self, request, *args, **kwargs): return HttpResponseRedirect(load_url) else: return HttpResponseBadRequest("Must have hermes section with HERMES_API_KEY set in DATA_SHARING settings") + + +class TargetFacilitySelectionView(Raise403PermissionRequiredMixin, FormView): + """ + View to select targets suitable to observe from a specific facility/location, taking into account target visibility + from that site, as well as other user-defined constraints. + """ + template_name = 'tom_targets/target_facility_selection.html' + paginate_by = 25 + strict = False + model = Target + permission_required = 'tom_targets.view_target' + form_class = TargetSelectionForm + + def get_context_data(self, *args, **kwargs): + """ + Adds the ``TargetListShareForm`` to the context and prepopulates the hidden fields. + :returns: context object + :rtype: dict + """ + context = super().get_context_data(*args, **kwargs) + # Surely this needs to verify that the user has permission? + context['form'] = TargetSelectionForm() + + return context + + def post(self, request, *args, **kwargs): + """ + Handles POST requests to select targets suitable for observation from this facility + + :param request: The HTML request object + :param args: Optional arguments if any + :param kwargs: Optional kwargs if any + :return: HTTPRequest + """ + + # Configuration: + # Maximum airmass limit to consider a target visible + # Number of intervals with which to calculate visibility throughout a single night + airmass_max = 2.0 + visibiliy_intervals = 10 + context = super().get_context_data(*args, **kwargs) + + # Gather the list of targets, either from the selected target list, or all targets accessible + # to the user. This produces a QuerySet either way. + if len(request.POST.get('target_list')) > 0: + target_list = TargetList.objects.get(id=request.POST.get('target_list')) + targets = target_list.targets.all() + else: + targets = get_objects_for_user(request.user, 'tom_targets.view_target').distinct() + + # Configure output target table. + # The displayed table can be extended to include selected extra_fields for each target, + # if configured in the TOM's settings.py. So we set the list of table columns accordingly. + table_columns = [ + 'Target', 'RA', 'Dec', 'Site', 'Min airmass' + ] + settings.SELECTION_EXTRA_FIELDS + # for param in settings.SELECTION_EXTRA_FIELDS: + # table_columns.append(param) + + # Calculate the visibility of all selected targets on the date given + # Since some observatories include multiple sites, the visibiliy_data returned is always + # a dictionary indexed by site code. Our purpose here is to verify whether each target is ever + # visible at lower airmass than the limit from any site - if so the target is considered to be visible + observable_targets = [] + for object in targets: + start_time = datetime.strptime(request.POST.get('date')+'T00:00:00', '%Y-%m-%dT%H:%M:%S') + end_time = datetime.strptime(request.POST.get('date')+'T23:59:59', '%Y-%m-%dT%H:%M:%S') + visibility_data = get_sidereal_visibility( + object, start_time, end_time, + visibiliy_intervals, airmass_max, + observation_facility=request.POST.get('observatory') + ) + for site, vis_data in visibility_data.items(): + airmass_data = np.array([x for x in vis_data[1] if x]) + if len(airmass_data) > 0: + s = SkyCoord(object.ra, object.dec, frame='icrs', unit=(u.deg, u.deg)) + target_data = [ + object.name, s.ra.to_string(u.hour), s.dec.to_string(u.deg, alwayssign=True), + site, round(airmass_data.min(), 1) + ] + + # Extract any requested extra parameters for this object, if available + for param in settings.SELECTION_EXTRA_FIELDS: + if param in object.extra_fields.keys(): + target_data.append(object.extra_fields[param]) + else: + target_data.append(None) + observable_targets.append(target_data) + + context['table_columns'] = table_columns + context['observable_targets'] = observable_targets + + return self.render_to_response(context)