Added tutorials to the docs

mauritiusdadd · Apr 30, 2024 · dfa60b6 · dfa60b6
1 parent 2980156
commit dfa60b6
Show file tree

Hide file tree

Showing 31 changed files with 232 additions and 10 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -54,6 +54,7 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
+numfig = True
 
 # -- Options for HTML output -------------------------------------------------
 

diff --git a/docs/installation.rst b/docs/installation.rst
@@ -1,3 +1,5 @@
+.. _installation_guide:
+
 .. |github_mark| image:: pics/github-mark.png
    :height: 1em
    :target: github_repo
@@ -79,6 +81,7 @@ or
 After the installation, to update redmost use
 
 .. code-block:: bash
+
     git pull
     pip install . --upgrade
 

diff --git a/docs/pics/dialog_about.png b/docs/pics/dialog_about.png
diff --git a/docs/pics/dialog_controls.png b/docs/pics/dialog_controls.png
diff --git a/docs/pics/dialog_load_spectra.png b/docs/pics/dialog_load_spectra.png
diff --git a/docs/pics/dialog_settings_appearence.png b/docs/pics/dialog_settings_appearence.png
diff --git a/docs/pics/dialog_settings_general.png b/docs/pics/dialog_settings_general.png
diff --git a/docs/pics/icons/file-plus.svg b/docs/pics/icons/file-plus.svg
diff --git a/docs/pics/icons/folder.svg b/docs/pics/icons/folder.svg
diff --git a/docs/pics/icons/maximize.svg b/docs/pics/icons/maximize.svg
diff --git a/docs/pics/icons/play.svg b/docs/pics/icons/play.svg
diff --git a/docs/pics/icons/save.svg b/docs/pics/icons/save.svg
diff --git a/docs/pics/icons/zoom-in.svg b/docs/pics/icons/zoom-in.svg
diff --git a/docs/pics/icons/zoom-out.svg b/docs/pics/icons/zoom-out.svg
diff --git a/docs/pics/main_ui_add_line.png b/docs/pics/main_ui_add_line.png
diff --git a/docs/pics/main_ui_annotated.png b/docs/pics/main_ui_annotated.png
diff --git a/docs/pics/main_ui_clean.png b/docs/pics/main_ui_clean.png
diff --git a/docs/pics/main_ui_identification.png b/docs/pics/main_ui_identification.png
diff --git a/docs/pics/main_ui_multi_lines.png b/docs/pics/main_ui_multi_lines.png
diff --git a/docs/pics/main_ui_redrock.png b/docs/pics/main_ui_redrock.png
diff --git a/docs/pics/main_ui_select_lines.png b/docs/pics/main_ui_select_lines.png
diff --git a/docs/pics/main_ui_spectrum.png b/docs/pics/main_ui_spectrum.png
diff --git a/docs/pics/menu_about.png b/docs/pics/menu_about.png
diff --git a/docs/pics/menu_edit.png b/docs/pics/menu_edit.png
diff --git a/docs/pics/menu_file.png b/docs/pics/menu_file.png
diff --git a/docs/pics/menu_tools.png b/docs/pics/menu_tools.png
diff --git a/docs/tutorials.rst b/docs/tutorials.rst
@@ -1,3 +1,5 @@
 .. toctree::
-   tutorials/tut_01
+   tutorials/tut_01_load_spectra
+   tutorials/tut_02_line_tools
+   tutorials/tut_03_use_existing_zcat
    :caption: Getting Started:
diff --git a/docs/tutorials/tut_01.rst b/docs/tutorials/tut_01.rst
diff --git a/docs/tutorials/tut_01_load_spectra.rst b/docs/tutorials/tut_01_load_spectra.rst
@@ -0,0 +1,113 @@
+.. _tutorial_1:
+
+Tutorial 1 - Basic operations
+=============================
+
+What do you need for this tutorial
+----------------------------------
+
+    .. _item_a:
+
+a) A working installation of redmost (see :ref:`Installation Guide<installation_guide>`)
+
+    .. _item_b:
+
+b) Test files: `https://github.com/mauritiusdadd/redmost/tree/main/test/data <https://github.com/mauritiusdadd/redmost/tree/main/test/data>`_
+
+Running Redmost
+---------------
+
+As described in the installation guide, you can run redmost by executing it in
+a terminal ``redmost`` and the main window should appear
+like in :numref:`fig_main_ui`. Since no spectra have been loaded yet, most of
+the controls are disabled, so the first step is to load at least one spectrum.
+
+.. _fig_main_ui:
+.. figure:: ../pics/main_ui_annotated.png
+   :figwidth: 100 %
+   :alt: Redmost main window.
+
+   This is the main window of Redmost. The labels indicate:
+   the menu bar [1]; the toolbar [2]; the open spectra list widget [3];
+   the current spectrum header info [4]; the current spectrum flux plot
+   widget [5]; the current spectrum variance, wavelegth dispersion, and sky
+   plots widgets [6]; The plot options tools [7]; The current spectrum
+   redshift value and quality flag selector [8]; The available redshift
+   measurement tools [9].
+
+Load spectra
+------------
+
+.. |import_spectra_ico| image:: ../pics/icons/file-plus.svg
+
+Spectra can be loaded using the button |import_spectra_ico| on the tool bar
+(:numref:`fig_main_ui` [2]) or the menù "File" > "Import spectra"
+(:numref:`fig_menu_file`). A dialog will appear where you can select one or
+multiple files to load. For this tutorial we will use the test spectra that are
+in "test/data" folder of the github repository, so make sure to download all
+the files from (:ref:`b <item_b>`) into a dedicated folder. Then, in the
+"Import Spectra" dialog select all the FITS files whose names begin with
+"spec" and click on the "Open" button (:numref:`fig_dialog_load_spectra`).
+
+.. _fig_menu_file:
+.. figure:: ../pics/menu_file.png
+   :figwidth: 50 %
+   :alt: File menù
+
+   The "File" menù.
+
+.. _fig_dialog_load_spectra:
+.. figure:: ../pics/dialog_load_spectra.png
+   :figwidth: 100 %
+   :alt: Open file dialog
+
+   Dialog windows used to select the files to load.
+
+Spectrum plot widgets
+---------------------
+
+.. |zoom_in_ico| image:: ../pics/icons/zoom-in.svg
+.. |zoom_out_ico| image:: ../pics/icons/zoom-out.svg
+.. |zoom_fit_ico| image:: ../pics/icons/maximize.svg
+
+The open spectra list widget (:numref:`fig_main_ui` [2]) should be now
+populated with the files opened in the previous step. If you clik on one of
+the element of this list, the corresponding spectrum is shown in the flux plot
+widgets (:numref:`fig_main_ui` [5]). If variance, wavelength dispersion or sky
+spectra are available, they will be shown in the corresponding plot widgets
+(:numref:`fig_main_ui` [6]). In the "Object info" panel, the header of the
+primary fits extension is also shown. Smoothing can be enabled using the
+corresponding check-box in the "Plot Options" panel
+(:numref:`fig_main_ui` [5]), in this case the smoothed spectrum will be plotted
+in orange on top of the original spectrum (:numref:`fig_main_ui_spectrum`).
+The check-box "Show lines" toggles the visualization of the most common
+amission/absorption lines at the redshift of the object and you can also select
+which type of line to show using the combo-box on the right.
+
+You can zoom-in on a region of the spectrum by clicking with the left mouse
+button and then dragging to select the area you want to zoom in. You can also
+control the zoom using the mouse wheel + Ctrl.
+Another way to control the zoom is by using the buttons |zoom_in_ico|,
+|zoom_out_ico|, and |zoom_fit_ico| to respectively zoom-in, zoom-out and
+fit the spectrum in the widget area.
+
+.. _fig_main_ui_spectrum:
+.. figure:: ../pics/main_ui_spectrum.png
+   :figwidth: 100 %
+   :alt: Main window showing a spectrum.
+
+   The main window when a spectrum is selected from the open spectra list.
+
+
+
+Save and load projects
+----------------------
+
+.. |save_project_ico| image:: ../pics/icons/save.svg
+.. |load_project_ico| image:: ../pics/icons/folder.svg
+
+Now that we have loaded a bunch of spectra, we can save the current project
+using the button |save_project_ico| on the tool bar (:numref:`fig_main_ui` [2])
+or the menù "File" > "Save" (:numref:`fig_menu_file`). To load a previously
+saved project, use the button |load_project_ico| on the tool bar or the menù
+"File" > "Open Project" (:numref:`fig_menu_file`).
diff --git a/docs/tutorials/tut_02_line_tools.rst b/docs/tutorials/tut_02_line_tools.rst
@@ -0,0 +1,99 @@
+.. _tutorial_2:
+
+Tutorial 2 - Redshift measurements
+==================================
+
+What do you need for this tutorial
+----------------------------------
+
+    .. _item_a:
+
+a) A working installation of redmost (see :ref:`Installation Guide<installation_guide>`)
+
+    .. _item_b:
+
+b) Test files: `https://github.com/mauritiusdadd/redmost/tree/main/test/data <https://github.com/mauritiusdadd/redmost/tree/main/test/data>`_
+
+
+Manually with the lines tool
+----------------------------
+
+First of all, load the test spectra (:ref:`b <item_b>`), as described in
+:ref:`Tutorial 1<tutorial_1>`, and select the one named  "spec_95.fits". This
+is the spectrum of a passive galaxy with clear and easily identifiable CaII H&K
+lines. Let's first zoom-in on these lines, then move to the "Lines" tab in the
+"Redshift tools" panel (:numref:`fig_main_ui` [9]) and then click the button
+"Add line". Now most of the controls are disabled and the mouse cursor has
+changed to indicate that the application is waiting for you to select where the
+line is: just move the mouse cursor on the peak of the absorption of the
+CaII K, like in :numref:`fig_main_ui_add_line`, and then click with the left
+mouse button. A new entry has been added to the "Identification" list with the
+wavelength we just picked up with the mouse. We can now associate to this
+entry the restframe wavelength of the CaII K by first selecting it from the
+list with the mouse and then selecting "CaII_K - 3933.70A" from the combo-box
+"Set current line to", like shown in :numref:`fig_main_ui_identification`.
+This operation automatically compute the redshift and updates the restframe
+wavelength for other identified lines. The redshift value appears in the top
+panel of "Redshift Tools" and can also be changed manually.
+
+A quality flag for the redshift estimation can be set using the "quality flag"
+combo-box. Setting a quality flag also changes the color of the corresponding
+element in the open spectra list (:numref:`fig_main_ui` [3]), in this way it is
+easy to distinguish the objects for which you already measured the redshift
+from those you have not looked at yet.
+
+.. _fig_main_ui_add_line:
+.. figure:: ../pics/main_ui_add_line.png
+   :figwidth: 100 %
+   :alt: Main window showing how to add a line.
+
+   The main window when a spectrum is selected from the open spectra list.
+
+.. _fig_main_ui_identification:
+.. figure:: ../pics/main_ui_identification.png
+   :figwidth: 50 %
+   :alt: Main window - identification tool.
+
+   Identification tool.
+
+Multi-lines matching
+--------------------
+
+If you are able to identify more that one line, but you are not sure about what
+line they are, you can try to use the multi-lines matching tool. Just click
+on the button "Match selected" and a list of possible redshift will appear,
+like in :numref:`fig_main_ui_multi_lines`. Just click on one of the
+redshifts to set it as the redshift value for the object.
+
+
+.. _fig_main_ui_multi_lines:
+.. figure:: ../pics/main_ui_multi_lines.png
+   :figwidth: 50 %
+   :alt: Main window - multi-lines matching tool.
+
+   Three lines (CaII H&K and NaD) have been matched using the multi-lines
+   matching tools and a list of possible redshift has been produced.
+   A pseudo-probability (p) is associated to each redshift, where p=1.0
+   indicates a perfect match.
+
+Using Redrock backend
+---------------------
+
+.. |play_ico| image:: ../pics/icons/play.svg
+
+If you have redrock configured and installed, then you can move to the tab
+"Redrock" in the "Redshift tools" (:numref:`fig_main_ui` [9]). In the panel
+"Options" you can specify whether to measure the redshift for all the loaded
+spectra (default), only for the selected spectra, or for the current object
+only. Once you have set the desired working mode, just clik on the
+button "|play_ico| Run" to run redrock. The output of redrock will be printed
+out in the "Status" text-box, so you can check what is going on.
+Once redrock has finished, redmost will automatically collect the best redshift
+estimations for each objects.
+
+.. _fig_main_ui_redrock:
+.. figure:: ../pics/main_ui_redrock.png
+   :figwidth: 50 %
+   :alt: Main window - redrock backend.
+
+   The redrock backend interface.
diff --git a/docs/tutorials/tut_03_use_existing_zcat.rst b/docs/tutorials/tut_03_use_existing_zcat.rst
@@ -0,0 +1,6 @@
+.. _tutorial_3:
+
+Tutorial 3 - Using existing specrtoscopic catalogs
+==================================================
+
+TODO