add info about BPMs. other minor fixes I caught.

geminidr/doc/tutorials/F2Img-DRTutorial/04_tips_and_tricks.rst

@@ -9,6 +9,12 @@ This is a collection of tips and tricks that can be useful for reducing
 different data, or to do it slightly differently from what is presented
 in the example.
 
+Bad Pixel Masks
+===============
+
+Please note that at this time, there are no static bad pixel masks for
+Flamingos-2 data.  DRAGONS will simply acknowledge that in the logs and
+continue with the reduction.
 
 Flatfields
 ==========

geminidr/doc/tutorials/F2Img-DRTutorial/ex1_f2im_ontarget_api.rst

@@ -266,7 +266,7 @@ data quality plane to identify the pixels beyond the circular aperture as
 but the user can easily create a fresh bad pixel mask from the flats and
 recent short darks.
 
-The Bad Pixel Mask is created as follow:
+The Bad Pixel Mask is created as follows:
 
 .. code-block:: python
     :linenos:

geminidr/doc/tutorials/GMOSImg-DRTutorial/04_tips_and_tricks.rst

@@ -1,5 +1,10 @@
 .. 04_tips_and_tricks.rst
 
+.. role:: raw-html(raw)
+   :format: html
+
+.. |verticalpadding| replace:: :raw-html:`<br>`
+
 .. _tips_and_tricks:
 
 ***************
@@ -10,6 +15,93 @@ This is a collection of tips and tricks that can be useful for reducing
 different data, or to do it slightly differently from what is presented
 in the example.
 
+.. _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.
+
+Note that at this time there no static BPMs for Flamingos-2 data.
+
+.. _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, set the
+"Obs.Type" to "BPM", if relevant for the instrument, set the "Binning".  Hit
+"Search" and the list of BPMs will show up as illustrated in the figure below.
+
+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.
+
+.. image:: _graphics/bpmassociated.png
+   :scale: 100%
+   :align: center
+
+|verticalpadding|
+
+This will be the case for new data (from late March 2023).  For old data,
+until we fix an issue recently discovered, they will not show up as
+associated calibration and you will have to find them manual as explained
+in the previous section, :ref:`manualBPM`.  We understand the issue and are
+working on a fix.
+
+
+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}/niriimg_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>
+
+
+
 .. _process_fringe_frame:
 
 Create Master Fringe Frame
@@ -92,7 +184,7 @@ Customizing input parameters
 ============================
 
 From the command line, setting the value of a primitive input parameter is
-done as follow:
+done as follows:
 
 .. code-block:: bash
 

geminidr/doc/tutorials/GMOSImg-DRTutorial/appendices/01_goa_download.rst

@@ -32,7 +32,7 @@ Science Data
 ------------
 
 Access the `Gemini Observatory Archive (GOA) <https://archive.gemini.edu/>`_
-and fill the search form as follow:
+and fill the search form as follows:
 
 * Program ID: GN-2017A-SV-151-382
 * Instrument: GMOS-N

geminidr/doc/tutorials/GMOSImg-DRTutorial/ex1_gmosim_starfield_api.rst

@@ -191,8 +191,12 @@ as calibrations.  They
 are downloadable from the archive instead of being packaged with the software.
 They are automatically associated like any other calibrations.  This means that
 the user now must download the BPMs along with the other calibrations and add
-the BPMs to the local calibration manager.  To add the BPM included in the
-data package to the local calibration database:
+the BPMs to the local calibration manager.
+
+See :ref:`getBPM` in :ref:`tips_and_tricks` to learn about the various ways
+to get the BPMs from the archive.
+
+To add the BPM included in the data package to the local calibration database:
 
 .. code-block:: python
     :linenos:
@@ -207,7 +211,7 @@ data package to the local calibration database:
 Make Master Bias
 ================
 
-We create the master bias and add it to the calibration manager as follow:
+We create the master bias and add it to the calibration manager as follows:
 
 .. code-block:: python
    :linenos:
@@ -242,7 +246,7 @@ recipe search is triggered and where it is executed.
 Make Master Flat
 ================
 
-We create the master flat field and add it to the calibration database as follow:
+We create the master flat field and add it to the calibration database as follows:
 
 .. code-block:: python
     :linenos:

geminidr/doc/tutorials/GMOSImg-DRTutorial/ex1_gmosim_starfield_cmdline.rst

@@ -182,12 +182,16 @@ Please make sure that you are still in the ``playground`` directory.
 Bad Pixel Mask
 ==============
 Starting with DRAGONS v3.1, the bad pixel masks (BPMs) are now handled as
-calibrations.  They
-are downloadable from the archive instead of being packaged with the software.
-They are automatically associated like any other calibrations.  This means that
-the user now must download the BPMs along with the other calibrations and add
-the BPMs to the local calibration manager.  To add the static BPM included in the
-data package to the local calibration database:
+calibrations.  They are downloadable from the archive instead of being
+packaged with the software. They are automatically associated like any other
+calibrations.  This means that the user now must download the BPMs along with
+the other calibrations and add the BPMs to the local calibration manager.
+
+See :ref:`getBPM` in :ref:`tips_and_tricks` to learn about the various ways
+to get the BPMs from the archive.
+
+To add the static BPM included in the data package to the local calibration
+database:
 
 ::
 

geminidr/doc/tutorials/GMOSImg-DRTutorial/ex1_gmosim_starfield_dataset.rst

@@ -26,6 +26,10 @@ The calibratons we use in this example are:
   use biases contemporary to the twilights.
 * Twilight flats.
 
+.. warning::  The Bad Pixel Masks (BPMs) are now found in the archive rather
+   than packaged with the software.  You must get the static BPM from the
+   archive.  See :ref:`getBPM` in :ref:`tips_and_tricks`.
+
 +---------------+---------------------+--------------------------------+
 | Science       || N20170614S0201-205 || 10 s, i-band                  |
 +---------------+---------------------+--------------------------------+

geminidr/doc/tutorials/GMOSImg-DRTutorial/ex2_gmosim_separateCCDs_api.rst

@@ -236,8 +236,12 @@ as calibrations.  They
 are downloadable from the archive instead of being packaged with the software.
 They are automatically associated like any other calibrations.  This means that
 the user now must download the BPMs along with the other calibrations and add
-the BPMs to the local calibration manager.  To add the BPM included in the
-data package to the local calibration database:
+the BPMs to the local calibration manager.
+
+See :ref:`getBPM` in :ref:`tips_and_tricks` to learn about the various ways
+to get the BPMs from the archive.
+
+To add the BPM included in the data package to the local calibration database:
 
 .. code-block:: python
     :linenos:
@@ -254,7 +258,7 @@ the biases and it keeps the CCDs separated, always.  Because of that, the
 reduction of the biases for the "Separate CCDs" recipe is exactly the same
 as for the default recipe.
 
-We create the master bias and add it to the calibration manager as follow:
+We create the master bias and add it to the calibration manager as follows:
 
 .. code-block:: python
    :linenos:
@@ -296,7 +300,7 @@ flats does not mosaic the flats and it keeps the CCDs separated, always.
 Because of that, the reduction of the flats for the "Separate CCDs" recipe
 is exactly the same as for the default recipe.
 
-We create the master flat field and add it to the calibration database as follow:
+We create the master flat field and add it to the calibration database as follows:
 
 .. code-block:: python
     :linenos:

geminidr/doc/tutorials/GMOSImg-DRTutorial/ex2_gmosim_separateCCDs_cmdline.rst

@@ -225,12 +225,16 @@ Please make sure that you are still in the ``playground`` directory.
 Bad Pixel Mask
 ==============
 Starting with DRAGONS v3.1, the bad pixel masks (BPMs) are now handled as
-calibrations.  They
-are downloadable from the archive instead of being packaged with the software.
-They are automatically associated like any other calibrations.  This means that
-the user now must download the BPMs along with the other calibrations and add
-the BPMs to the local calibration manager.  To add the static BPM included in the
-data package to the local calibration database:
+calibrations.  They are downloadable from the archive instead of being
+packaged with the software. They are automatically associated like any other
+calibrations.  This means that the user now must download the BPMs along with
+the other calibrations and add the BPMs to the local calibration manager.
+
+See :ref:`getBPM` in :ref:`tips_and_tricks` to learn about the various ways
+to get the BPMs from the archive.
+
+To add the static BPM included in the data package to the local calibration
+database:
 
 ::
 

geminidr/doc/tutorials/GMOSImg-DRTutorial/ex2_gmosim_separateCCDs_dataset.rst

@@ -25,6 +25,10 @@ The calibratons we use in this example are:
   and the twilight frame, respectively.
 * Twilight flats.
 
+.. warning::  The Bad Pixel Masks (BPMs) are now found in the archive rather
+   than packaged with the software.  You must get the static BPM from the
+   archive.  See :ref:`getBPM` in :ref:`tips_and_tricks`.
+
 .. important::
     For accurate photometry, observations of photometric standard of various
     colors should be obtained and observed on each of the 3 CCDs.

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

@@ -1,11 +1,102 @@
 .. 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.
+
+Note that at this time there no static BPMs for Flamingos-2 data.
+
+.. _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, set the
+"Obs.Type" to "BPM", if relevant for the instrument, set the "Binning".  Hit
+"Search" and the list of BPMs will show up as illustrated in the figure below.
+
+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.
+
+.. image:: _graphics/bpmassociated.png
+   :scale: 100%
+   :align: center
+
+|verticalpadding|
+
+This will be the case for new data (from late March 2023).  For old data,
+until we fix an issue recently discovered, they will not show up as
+associated calibration and you will have to find them manual as explained
+in the previous section, :ref:`manualBPM`.  We understand the issue and are
+working on a fix.
+
+
+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}/niriimg_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>
+
+
 .. _plot_1d:
 
 Plot a 1-D spectrum

geminidr/doc/tutorials/GMOSLS-DRTutorial/ex1_gmosls_dithered_api.rst

@@ -303,8 +303,12 @@ as calibrations.  They
 are downloadable from the archive instead of being packaged with the software.
 They are automatically associated like any other calibrations.  This means that
 the user now must download the BPMs along with the other calibrations and add
-the BPMs to the local calibration manager.  To add the BPM included in the
-data package to the local calibration database:
+the BPMs to the local calibration manager.
+
+See :ref:`getBPM` in :ref:`tips_and_tricks` to learn about the various ways
+to get the BPMs from the archive.
+
+To add the BPM included in the data package to the local calibration database:
 
 .. code-block:: python
     :linenos: