v0.3.4

fpavogt · Jun 19, 2018 · e5064d8 · e5064d8
1 parent b0afe4c
commit e5064d8
Show file tree

Hide file tree

Showing 13 changed files with 197 additions and 117 deletions.
diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst
@@ -7,13 +7,23 @@ Changelog |last-commit|
 =======================
 
 .. todo:: 
+   - (?) include an instrument-free mode
+   - (?) add metadata to .jpg 
    - (!) formally validate the parallactic function
    - (?) add support for jitter in HAWKI (showing the max jitter area with a circle) 
    - (?) find a better way to display the allowed TT area for MUSE, e.g. shaded area with 
      ``shapley``
    - (?) make the obsdate an ``fc_params`` entry rather than a global variable
    - (?) for time critical OBs, get the time from the OB
 
+v0.3.4 June 2018, F.P.A. Vogt
+ - fixed missing relsize package in mplstyle
+ - added a check to make sure the user provides the wavelength of custom fits files
+ - added section about custom FITS file to the doc.
+ - fixed lack of `ins_mode` in new NFM OBs
+ - added new keywords for command line option, including ``--p2uid``, ``--obsid``, 
+   ``--plot-loc``, ``--data-loc``, ``--bk-image`` and ``--bk-lam``.
+
 v0.3.3 June 2018, F.P.A. Vogt:
  - corrected the orientation of the MUSE WFM field (180 flip required)
  - added correct Cassegrain field-of-view of 7.4 arcmin in radius

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -58,7 +58,7 @@
 
 # General information about the project.
 project = u'fcmaker'
-copyright = u'2017, Frédéric P.A. Vogt'
+copyright = u'2017-2018, Frédéric P.A. Vogt'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

diff --git a/docs/source/examples/gallery.rst b/docs/source/examples/gallery.rst
@@ -95,24 +95,40 @@ By default, the background image for the MUSE NFM finding charts is a mock image
 reconstructed from the Gaia catalogue (see :ref:`gaia-images`). The two finding charts 
 below illustrate the benefit of this approach, in comparison with using a DSS2 Red image.
 
-.. figure:: ./fcm_plots/MUSE_NFM_Gaia.png
-    :width: 750px
-    :align: center
-    :alt: MUSE NFM
 
 .. figure:: ./fcm_plots/MUSE_NFM_DSS2-Red.png
     :width: 750px
     :align: center
     :alt: MUSE NFM DSS2
+
+.. figure:: ./fcm_plots/MUSE_NFM_Gaia.png
+    :width: 750px
+    :align: center
+    :alt: MUSE NFM
 
 To recreate these example finding charts, download 
-:download:`local_2_fcm.muse_nfm-Gaia.txt <./local_2_fcm.muse_nfm-Gaia.txt>` and/or 
-:download:`local_2_fcm.muse_nfm-DSS.txt <./local_2_fcm.muse_nfm-DSS.txt>` and 
+:download:`local_2_fcm.muse_nfm-DSS.txt <./local_2_fcm.muse_nfm-DSS.txt>` and/or 
+:download:`local_2_fcm.muse_nfm-Gaia.txt <./local_2_fcm.muse_nfm-Gaia.txt>` and 
 run::
    
-   python -m fcmaker -l -f local_2_fcm.muse_nfm-Gaia.txt --do-png --systemtex
    python -m fcmaker -l -f local_2_fcm.muse_nfm-DSS.txt --do-png --systemtex
+   python -m fcmaker -l -f local_2_fcm.muse_nfm-Gaia.txt --do-png --systemtex
+   
+Evidently, the best case is when a real high-resolution images of the observation area is 
+available, for example from HST ACS or WFC3. Any local fits files can be used for the 
+left-hand-side finding chart, provided that it comes with proper WCS information.
+
+.. figure:: ./fcm_plots/MUSE_NFM_from-user.png
+    :width: 750px
+    :align: center
+    :alt: MUSE NFM HST
+
+To recreate this example finding chart, download 
+:download:`local_2_fcm.muse_nfm-HST.txt <./local_2_fcm.muse_nfm-HST.txt>` and run 
+(FITS file  not included!)::
    
+   python -m fcmaker -l -f local_2_fcm.muse_nfm-HST.txt --do-png --systemtex
+      
 
 HAWKI
 -----

diff --git a/...examples/local_2_fcm.muse_wfm-noao-pm.txt → ...rce/examples/local_2_fcm.muse_nfm-HST.txt b/...examples/local_2_fcm.muse_wfm-noao-pm.txt → ...rce/examples/local_2_fcm.muse_nfm-HST.txt
@@ -1,22 +1,22 @@
 #
-# A list of basic OB parameters to generate a MUSE finding chart from scratch, locally
+# A list of basic OB parameters to generate a MUSE finding chart from scratch
 #
-###### OB Info #####
-ob_name:   MUSE_WFM_NOAO_pm #
-ob_id:     12345678       # 
-pi:        jdoe           #
-prog_id:   0100.Z-9999    #
-inst:      MUSE           #
-ins_mode:  WFM-NOAO-N     #
+##### OB Info #####
+ob_name:   MUSE_NFM       # OB name, required to name the output files!
+ob_id:     12345678       # optional
+pi:        jdoe           # optional
+prog_id:   0100.Z-9999    # optional
+inst:      MUSE           # optional
+ins_mode:  NFM            #
 
 ##### Target #####
 equinox:   J2000          #
 epoch:     2000.0         #
-ra:        21h17m11.400s  #
-dec:       -38d51m30.000s #
-pmra:      0.0000         # proper motion in arcsec/year
-pmdec:     0.0000         # proper motion in arcsec/year
-ephemeris:                # relative path+filename of an ephemeris file
+ra:        01h04m01.5539s #
+dec:       -72d02m21.669s #
+pmra:      0              # proper motion in arcsec/year
+pmdec:     0              # propers motion in arcsec/year
+ephemeris:                # relative path+filename of an ephemeris file, optional
 
 ##### Acquisition #####
 bos_ra:    0              # Blind-offset (RA)
@@ -25,26 +25,26 @@ acq_pa:    0              # Acquisition Position Angle (degrees)
 is_gs:     False          # User-defined Guide Star ?
 gs_ra:                    #
 gs_dec:                   #
-is_tts:    False          # User-defined tip-tilt star ?
+is_tts:    False          # User-defined tip-tilt stars ?
 tts1_ra:                  #
 tts1_dec:                 #
 tts2_ra:                  #
 tts2_dec:                 #
-oatt_ra:                  # On-axis TT star, for NFM.
-oatt_dec:                 #
-           
+oatt_ra:  01h04m01.8049s  # On-axis TT star, for NFM.
+oatt_dec: -72d02m20.4919s #
+
 ##### Observation #####
 noff:      3              #
-obstype:   [O S O]        #
+obstype:   [O O O]        #
 coordtype: SKY            #
-posang:    [0 0 90]       #
-off1:      [0 -65 66]     #
-off2:      [0 40 -42]     #
+posang:    [0 0 0]        #
+off1:      [0 0.2 -0.4]   #
+off2:      [0 0.2 -0.4]   #
 return:    True           #
 
 ##### Other params #####
-bk_image:  DSS2 Red       # None, Bk images to download from SkyView, or local fits file
-bk_lam:    None           # None, or else overrides SkyView default.
+bk_image:  F673N_drc.fits # None, Bk images to download from SkyView, Gaia, or local fits file
+bk_lam:    HST-WFC3 673nm # None, or else overrides SkyView default.
 data_loc:  fcm_data       # Relative path to the bk images 
 plot_loc:  fcm_plots      # Relative path to store the finding charts 
 
diff --git a/docs/source/faq.rst b/docs/source/faq.rst
@@ -1,14 +1,7 @@
 .. _faq:
 
 FAQ 
-====
-
-
-**Q: If fcmaker is not an official ESO tool, will the fcmaker charts still be accepted in Phase 2?**
-
-   **A**: fcmaker is developed by an ESO Fellow with duties on UT4 at the VLT, but it is *not* an official ESO tool. Still, the fcmaker charts match all the official ESO requirements for finding charts, and were fine-tuned to meet the specific needs of the telescope operators and night astronomers during operations. The hope is that the inclusion of fcmaker finding charts in OBs will thus remain tolerated. Even for those instruments for which the use of the GuideCam Tool may be compulsory, I would still encourage the use of
-   fcmaker once the OB has been finalized.
-
+====   
 
 **Q: How does fcmaker deal with proper motions?**
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -45,11 +45,6 @@ Instruments and modes currently supported
    * **XSHOOTER**: all modes
    * targets with proper motions, ephemeris files
 
-.. warning::
-   fcmaker is neither supported nor officially endorsed by the 
-   European Southern Observatory: it is merely tolerated. As a rule, never blindly rely on 
-   what fcmaker does.
-
 Contents
 ---------
 .. toctree::
@@ -96,15 +91,14 @@ fcmaker utterly fails to do something useful/elegant, `I'd be keen to know about
    From that perspective, fcmaker is very much complementary to the `GUideCam Tool (GUCT) <https://www.eso.org/sci/observing/phase2/SMGuidelines/GUCT.generic.html>`_. 
 
 .. warning::
-   fcmaker is developed by an ESO Fellow with duties on UT4 at the VLT: initially, to meet 
-   his own observational needs. It is shared publicly with the community, in the hope 
-   that it can be useful to others. 
+   fcmaker is developed by an ESO Fellow with duties on UT4 at the VLT. It is shared 
+   with the community, in the hope that it can be useful to others. 
 
-   But please note that **fcmaker is neither supported nor officially endorsed by the 
-   European Southern Observatory.**
+   But please note that **fcmaker is not an official tool from the European Southern 
+   Observatory.**
 
-   **As such, you should never blindly rely on what fcmaker does.** If the finding 
-   chart generated by fcmaker looks different from what you expected, this means that:
+   As such, never blindly rely on what fcmaker does. If the finding chart generated by 
+   fcmaker looks different from what you expected, this means that:
 
    A) there is a real design flaw in your OB, or
    B) there is a yet undiscovered bug in fcmaker.

diff --git a/docs/source/running.rst b/docs/source/running.rst
@@ -108,19 +108,28 @@ fcmaker will create the associated finding chart, store it where specified, and
 The fcmaker flags
 -----------------
 
-A series of flags allow to fine-tune the way fcmaker works. They are:
+Here are all the flags that allow to fine-tune the way fcmaker works. They are:
 
  * ``--help,-h`` : prints the basic help
  * ``--version`` : prints the fcmaker version
- * ``--montage`` : will use Montage, to force the finding charts to be rotated North (soon to be retired).
- * ``--systemtex`` : will use the system-wide LaTeX, rather than the matplotlib one. Finding charts will be prettier. [encouraged!]
- * ``--no-upload`` : tells fcmaker never to try to upload the finding chart(s) to p2.
+ * ``--p2uid username``: p2 user ID
+ * ``--obid 12345678``: Observing Block ID on p2
+ * ``-f filename``: specify a parameter filename
+ * ``--obsdate YYYY-MM-DD hh:mm:ss TZ`` : allows to specify the observing date (and time, and time zone), in case of large proper motions or moving target. Assuming UTC by default.
+ * ``--bk-image filename.fits``: a FITS filename for the background image. Must be stored in ``--data-loc``.
+ * ``--bk-lam some text``: specifies the wavelength of the background image.
  * ``--do-pdf`` : tells fcmaker to save a .pdf version of the finding chart (in addition to the jpg one).
  * ``--do-png`` : tells fcmaker to save a .png version of the finding chart (in addition to the jpg one).
- * ``--obsdate`` : allows to specify the observing date (and time), in case of large proper motions or moving target.
  * ``--do-parang``: forces the drawing of the instrument field-of-view when a parallactic angle is set. This will be accurate, but *very* time-dependant!
+ * ``--data-loc path/to/folder``: relative path to store the downloaded data (default: ./fcm_data)
+ * ``--plot-loc path/to/folder``: relative path to store the finding charts (default: ./fcm_plots)
+ * ``--no-upload`` : tells fcmaker never to try to upload the finding chart(s) to p2. 
+ * ``-l`` or ``--local``: flags the parameter file as a local OB definition
+ * ``--montage`` : will use Montage, to force the finding charts to be rotated North (soon to be retired).
+ * ``--systemtex`` : will use the system-wide LaTeX, rather than the matplotlib one. Finding charts will be prettier. [encouraged!]
  * ``--clear-SkyView-cache`` : does as it says. Note that the SkyView cache is *not* the same as the ``fcm_data`` folder in which fcmaker stores the downloaded FITS files.
 
+
 For example, if you want to boost the aesthetic appeal of your finding charts with the 
 exquisite Computer Modern Bright sans-serif font (why wouldn't you?), try::
 
@@ -131,9 +140,9 @@ The background images
 ----------------------
 
 With the exception of MUSE NFM finding charts (see :ref:`gaia-images`), fcmaker relies on 
-``astroquery.skyview`` to download background images for the finding charts (if no local 
-FITS file is provided by the user). To display the full list of surveys available, type in 
-a Python shell::
+``astroquery.skyview`` to download background images for the finding charts (unless a local 
+FITS file is provided by the user, see :ref:`local-FITS`). To display the full list of 
+surveys available, type in a Python shell::
  
    from astroquery.skyview import SkyView
    SkyView.survey_dict['overlay_blue']
@@ -150,6 +159,7 @@ The default background survey images for the instruments supported by fcmaker ar
    to only use ``DSS2 Red`` or ``SDSSr`` for optical instruments, and ``2MASS-J``, 
    ``2MASS-H`` or ``2MASS-K`` for IR instruments.
 
+
 .. _gaia-images:
 
 Mock Gaia images for MUSE NFM
@@ -169,7 +179,18 @@ resulting image is saved as a fully-fledged FITS file in the ``data_loc`` locati
 See the Gallery (:ref:`examples-NFM`) for an illustration of the benefit of these mock 
 Gaia images.
 
+.. _local-FITS: 
+
+Using local FITS files
+++++++++++++++++++++++++ 
+
+Users interested in providing their own background image can do so (for the left-hand-side plot)
+via the ``bk_images`` and ``bk_lams`` parameters. The former specifies the filename, 
+assuming that the FITS file is placed in the ``data_loc`` directory. The latter allows the
+user to specify the text to be displayed on the chart. To meet ESO's requirements, this
+text should specify the wavelength of the image. 
+
+See the Gallery (:ref:`examples-NFM`) for an illustration of this approach.
 
-