rewrite of tutorial (needs figures for retrieving BPMs from the archive)

geminidr/doc/tutorials/GHOST-DRTutorial/05_tips_and_tricks.rst

@@ -0,0 +1,92 @@
+.. 05_tips_and_tricks.rst
+
+.. role:: raw-html(raw)
+   :format: html
+
+.. |verticalpadding| replace:: :raw-html:`<br>`
+
+.. _tips_and_tricks:
+
+***************
+Tips and Tricks
+***************
+
+.. _getBPM:
+
+Getting Bad Pixel Masks from the archive
+========================================
+Starting with DRAGONS v3.1, the static bad pixel masks (BPMs) are now handled as
+calibrations. They are downloadable from the archive instead of being packaged
+with the software.  There are various ways to get the BPMs.
+
+
+.. _manualBPM:
+
+Manual search
+-------------
+Ideally, the BPMs will show up in the list of associated calibrations, the
+"Load Associated Calibration" tab on the archive search form (next section).
+This will happen of all new data.  For old data, until we fix an issue
+recently discovered, they will not show up as associated calibration.  But
+they are there and can easily be found.
+
+On the archive search form, set the "Instrument" to match your data and set the
+"Obs.Type" to "BPM".  Hit
+"Search" and the list of BPMs will show up as illustrated in the figure below.
+**FIGURE NEEDS CREATING**
+
+The date in the BPM file name is a "Valid-from" date.  It is valid for data
+taken **on or after** that date.  Find the one most recent BPM that is valid
+for your date and download (click on "D") it.  Then follow the instructions
+found in the tutorial examples.
+
+.. image:: _graphics/bpmsearch.png
+   :scale: 100%
+   :align: center
+
+|verticalpadding|
+
+Associated calibrations
+-----------------------
+The BPMs are now handled like other calibrations.  This means that they are
+also downloaded from the archive.  From the archive search form, once you
+have identified your science data, select the "Load Associated Calibrations"
+(which turns to "View Calibrations" once the table is loaded).  The BPM will
+show up with the green background. **FIGURE**
+
+.. image:: _graphics/bpmassociated.png
+   :scale: 100%
+   :align: center
+
+|verticalpadding|
+
+
+Calibration service
+-------------------
+The calibration service in DRAGONS 3.1 adds several new features.  One of them
+is the ability to search multiple databases in a serial way, including online
+database, like the Gemini archive.
+
+The system will look first in your local database for processed calibration
+and BPMs.  If it does not find anything that matches, it will look in the
+next database.  To activate this feature, in ``~/.dragons/``, create or edit
+the configuration file ``dragonsrc`` as follows:
+
+.. code-block:: none
+
+    [calibs]
+    databases = ${path_to_my_data}/ghost_tutorial/playground/cal_manager.db get store
+                https://archive.gemini.edu get
+
+If you know that you will be connected to the internet when you reduce the data,
+you do not need to pre-download the BPM, DRAGONS will find it for you in the
+archive.
+
+If you want to pre-download the BPM without having to search for it, like in the
+previous two sections, you can let DRAGONS find it and download it for you:
+
+.. code-block:: none
+
+    $ reduce -r getBPM <file_for_which_you_need_bpm>
+    $ caldb add calibrations/processed_bpm/<the_bpm>
+

geminidr/doc/tutorials/GHOST-DRTutorial/cal_service.rst

@@ -23,32 +23,32 @@ System User Manual.
 The Configuration File
 ======================
 
-The database is configured in the DRAGONS configuration file under the
+The database is configure in the DRAGONS configuration file under the
 ``[calibs]`` section.
 
-In ``~/.geminidr/``, create or edit the configuration file ``rsys.cfg`` as
+In ``~/.dragons/``, create or edit the configuration file ``dragonsrc`` as
 follow:
 
 .. code-block:: none
 
     [calibs]
-    standalone = True
-    database_dir = <path_to_my_data>/ghost_tutorial/playground
+    databases = ${path_to_my_data}/ghost_tutorial/playground/cal_manager.db get store
 
-The ``[calibs]`` section tells the system where to put the calibration database.
-The database file name is ``cal_manager.db``.  In
-DRAGONS 3.0, you can only set the path to the database not the name.  As for
-the ``standalone`` setting, just make sure it is set to True.  This setting
-is used at Gemini by internal systems.
+The ``[calibs]`` section tells the system where to put the calibration database
+and how to name it.  Here we use ``cal_manager.db`` to match what was used in
+the pre-v3.1 version of DRAGONS, but you can now set the name of the database
+to what suits your needs and preferences.
 
-The database will keep track of the processed calibrations that we are going to
-send to it.  The database will be used
-by DRAGONS to automatically *get* matching calibrations. You will have to
-``caldb add`` (command line) or ``caldb.add_cal()`` (API)
-your calibration products yourself however.
+That database will keep track of the processed calibrations that we are going to
+send to it.  With the "get" and "store" options, the database will be used
+by DRAGONS to automatically *get* matching calibrations and to automatically
+*store* master calibrations that you produce.  If you remove the "store" option
+you will have to ``caldb add`` (command line) or ``caldb.add_cal()`` (API)
+your calibration product yourself (like what needed to be done in DRAGONS
+v3.0).
 
 .. note:: The tilde (``~``) in the path above refers to your home directory.
-   Also, mind the dot in ``.geminidr``.
+   Also, mind the dot in ``.dragons``.
 
 .. _cal_service_cmdline:
 
@@ -80,11 +80,11 @@ From the API, the calibration database is initialized as follows:
 
 .. code-block:: python
 
-    caldb = cal_service.CalibrationService()
-    caldb.config()
+    from recipe_system import cal_service
+
+    caldb = cal_service.set_local_database()
     caldb.init()
 
-    cal_service.set_calservice()
 
 The calibration service is now ready to use.