Merge pull request #840 from TOMToolkit/feature/facility_target_selection

Added view to enable target selection for manual observing runs

Author: jchate6

docs/observing/add_facility_form_admin.png

@@ -9,6 +9,7 @@ Observing Facilities and Observations
   ../common/scripts
   strategies
   observation_module
+  selecting_targets_for_facility
   ../api/tom_observations/models
   ../api/tom_observations/facilities
   ../api/tom_observations/views
@@ -26,6 +27,8 @@ the result of prior observations, as well as how to leverage observing templates
 :doc:`Building a TOM Observation Facility Module <observation_module>` - Learn to build a module which will
 allow your TOM to submit observation requests to observatories.
 
+:doc:`Selecting Targets <selecting_targets_for_facility>` - Display a selection of targets for a specific observing facility.
+
 :doc:`Observation Models <../api/tom_observations/models>` - Learn about the models used to store observation data.
 
 :doc:`Facility Modules <../api/tom_observations/facilities>` - Take a look at the supported facilities.

docs/observing/index.rst

@@ -0,0 +1,80 @@
+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 visibility 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 will be draw
+from a predefined Target Grouping, which users can chose from the pulldown menu.
+
+The TOM will evaluate the visibility of the selected sidereal 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.  Since this is computationally expensive, the visibility is calculated at intervals
+of 10min for a 24hr period from the given start time.
+
+.. 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
+from a customized target model.
+
+The columns of the table can be configured by editing the TOM's ``settings.py`` file,
+and adding a list called ``SELECTION_EXTRA_FIELDS``, as shown in the example below.  The entries
+in this list can be one or more of the exact names of attributes on your custom Target model.
+``SELECTION_EXTRA_FIELDS`` can also include the names of methods on the custom Target model,
+provided that they return output that can be rendered as a string entry in the table.
+The list can be left empty if no additional fields should be added to the table.
+
+.. code-block:: python
+
+    # settings.py
+    SELECTION_EXTRA_FIELDS = [
+        'mag_now',
+        'priority1',
+        'priority2',
+    ]
+
+In this example, the custom Target model has fields named ``priority1``
+and ``priority2`` and a method called ``mag_now``.   Adding those fields names to
+the ``SELECTION_EXTRA_FIELDS`` list will cause three columns of the same names to appear
+in the selected targets table output, containing the priority values and the calculated output of
+the ``mag_now`` method.
+
+Adding Facilities to the Observing Facilities Table
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you would like to record a telescope facility for the purposes of observation planning, but don't want to
+add code for a new facility module, you can add it to the TOM's table of observing facilities.
+
+Currently, this can be done by the TOM's administrator, by navigating to the TOM's built-in admin interface.
+This page can be reached by adding ``/admin/`` to the end of the TOM's root URL in your browser's navigation bar, e.g.:
+
+.. code-block:: html
+
+    > https://demo.lco.global/admin/
+
+Scrolling down the list of database tables, you will find ``Facilities`` under the tables from the ``tom_observations`` app.
+Clicking on this link will take you to a list of telescopes recorded in the TOM's database.  Note that this list
+is distinct (and does not include) telescopes already known to the TOM through installed facility modules.
+
+You can record new telescopes to this table using the admin interface's ``Add Facility`` button; this will present you
+with the following form:
+
+.. image:: add_facility_form_admin.png
+  :alt: Form to add a new telescope facility
+
+Fill in the form and click ``save``. Now if you return to your TOM's usual interface, and navigate to the ``Target Selection``
+page, the facility you added will appear in the list of facilities for which visibilities can be calculated.

docs/observing/selecting_targets_for_facility.rst

@@ -12,6 +12,7 @@
     <div class="dropdown-menu">
         <a class="dropdown-item" href="{% url 'targets:list' %}">Targets</a>
         <a class="dropdown-item" href="{% url 'targets:targetgrouping' %}">Target Grouping</a>
+        <a class="dropdown-item" href="{% url 'targets:target-selection' %}">Target Selection</a>
     </div>
 </li>
 <li class="nav-item dropdown">

docs/observing/target_selection_menu_option.png

@@ -0,0 +1,17 @@
+# Generated by Django 4.2.26 on 2026-01-15 01:52
+
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('tom_observations', '0015_remove_facility_mpc_site_code_and_more'),
+    ]
+
+    operations = [
+        migrations.AlterModelOptions(
+            name='facility',
+            options={'verbose_name_plural': 'facilities'},
+        ),
+    ]

docs/observing/target_selection_table_default.png

@@ -328,5 +328,8 @@ class Facility(models.Model):
         help_text="Root URL of the facilities API endpoints"
     )
 
+    class Meta:
+        verbose_name_plural = "facilities"
+
     def __str__(self):
         return self.short_name

tom_common/templates/tom_common/navbar_content.html

@@ -108,7 +108,14 @@ def observation_plan(target, facility=None, length=2, interval=60, airmass_limit
     start_time = datetime.now()
     end_time = start_time + timedelta(days=length)
 
-    visibility_data = get_sidereal_visibility(target, start_time, end_time, interval, airmass_limit, facility)
+    visibility_data = get_sidereal_visibility(
+        target,
+        start_time,
+        end_time,
+        interval,
+        airmass_limit,
+        facility_name=facility
+    )
     i = 0
     plot_data = []
     for site, data in visibility_data.items():

tom_observations/migrations/0016_alter_facility_options.py

@@ -460,7 +460,8 @@ def test_get_visibility_sidereal(self, mock_facility):
         mock_facility.return_value = {'Fake Robotic Facility': FakeRoboticFacility}
         end = self.start + timedelta(minutes=60)
         airmass = get_sidereal_visibility(self.target, self.start, end, self.interval, self.airmass_limit)
-        airmass_data = airmass['(Fake Robotic Facility) Siding Spring'][1]
+
+        airmass_data = airmass['(FakeRoboticFacility) Siding Spring'][1]
         expected_airmass = [
             1.2619096566629477, 1.2648181328558852, 1.2703522349950636, 1.2785703053923894,
             1.2895601364316183, 1.3034413026227516, 1.3203684217446099