Merge pull request #9 from soar-telescope/pre_release_changes

Pre release changes
soar-telescope · Sep 7, 2022 · f302732 · f302732
2 parents cb32807 + 8b5e58d
commit f302732
Show file tree

Hide file tree

Showing 15 changed files with 495 additions and 61 deletions.
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -0,0 +1,17 @@
+
+.. _v1.0.0:
+
+1.0.0 07-09-2022
+================
+
+- First functional version
+- Uses ApertureStats to obtain sources' statistics
+- Fully documented
+- Fully tested
+
+.. _v0.0.1.dev0:
+
+0.0.1.dev0 06-05-2022
+=====================
+
+- Initial release of a non-functional tool but will all the packaging setup.
diff --git a/README.md b/README.md
@@ -1,10 +1,21 @@
-# TripleSpec Focus Calculator
+# TripleSpec Slit Viewer Focus Calculator
 
 [![TripleSpec Focus](https://github.com/soar-telescope/triplespec_focus/actions/workflows/python-package.yml/badge.svg)](https://github.com/soar-telescope/triplespec_focus/actions/workflows/python-package.yml)
+[![codecov](https://codecov.io/gh/soar-telescope/triplespec_focus/branch/main/graph/badge.svg?token=S6Y6R7AQNY)](https://codecov.io/gh/soar-telescope/triplespec_focus)
 [![Upload to PYPI](https://github.com/soar-telescope/triplespec_focus/actions/workflows/python-publish.yml/badge.svg)](https://github.com/soar-telescope/triplespec_focus/actions/workflows/python-publish.yml)
 [![Documentation Status](https://readthedocs.org/projects/triplespec-focus/badge/?version=latest)](https://triplespec-focus.readthedocs.io/en/latest/?badge=latest)
 [![pypi](https://img.shields.io/pypi/v/triplespec_focus.svg?style=flat)](https://pypi.org/project/triplespec-focus/)
-[![Total alerts](https://img.shields.io/lgtm/alerts/g/soar-telescope/triplespec_focus.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/soar-telescope/triplespec_focus/alerts/)
-[![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/soar-telescope/triplespec_focus.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/soar-telescope/triplespec_focus/context:python)
+[![CodeQL](https://github.com/soar-telescope/triplespec_focus/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/soar-telescope/triplespec_focus/actions/workflows/codeql-analysis.yml)
+[![Python 3.8](https://img.shields.io/badge/Python-3.8-blue.svg)](https://www.python.org/downloads/release/python-380/)
+[![GitHub license](https://img.shields.io/github/license/soar-telescope/triplespec_focus)](https://github.com/soar-telescope/triplespec_focus/blob/main/LICENSE)
 
-TripleSpec Focus Calculator
+
+![Test Coverage](https://codecov.io/gh/soar-telescope/triplespec_focus/branch/main/graphs/sunburst.svg?token=S6Y6R7AQNY)
+
+
+TripleSpec is a fixed configuration Near Infrared Spectrograph. For more information please visit [NOIRLab Official Website](https://noirlab.edu/science/programs/ctio/instruments/triplespec41-nir-imaging-spectrograph) for
+triplespec.
+
+# Documentation
+
+For documentation please visit the [ReadTheDocs Site](https://triplespec-focus.readthedocs.io/en/latest/?badge=latest) 
diff --git a/docs/_static/focus_results.png b/docs/_static/focus_results.png
diff --git a/docs/_static/in_terminal_help.png b/docs/_static/in_terminal_help.png
diff --git a/docs/_static/slit_view_sample.png b/docs/_static/slit_view_sample.png
diff --git a/docs/about.rst b/docs/about.rst
@@ -0,0 +1,10 @@
+Change History
+##############
+
+.. include:: ../CHANGES.rst
+
+
+License
+#######
+
+.. include:: ../LICENSE
diff --git a/docs/data_overview.rst b/docs/data_overview.rst
@@ -0,0 +1,10 @@
+Data and Process Overview
+#########################
+
+You have seen already a sample of the data. You will get typically 10 to 15 images taken at different focus values.
+
+A quick examination routine will select the sharpest image by selecting the most intense image whose peak is also below
+the saturation level which for TripleSpec Slit Viewer camera is set to :math:`40.000 ADU`
+
+On this selected image the ``DAOStarFinder`` routing will be used to detect all the sources, the the most intense sources
+are selected to obtain the :math:`FWHM` using ``ApertureStats`` which is then fitted with a ``Chebyshev1D`` of order :math:`6`.
diff --git a/docs/index.rst b/docs/index.rst
@@ -6,13 +6,77 @@
 Welcome to TripleSpec Focus's documentation!
 ============================================
 
+.. image::  https://github.com/soar-telescope/triplespec_focus/actions/workflows/python-package.yml/badge.svg
+    :alt: TripleSpec Focus
+    :target: https://github.com/soar-telescope/triplespec_focus/actions/workflows/python-package.yml
+.. image::  https://codecov.io/gh/soar-telescope/triplespec_focus/branch/main/graph/badge.svg?token=S6Y6R7AQNY
+    :alt: Codecov
+    :target: https://codecov.io/gh/soar-telescope/triplespec_focus
+.. image::  https://github.com/soar-telescope/triplespec_focus/actions/workflows/python-publish.yml/badge.svg
+    :alt: Upload to PYPI
+    :target: https://github.com/soar-telescope/triplespec_focus/actions/workflows/python-publish.yml
+.. image::  https://readthedocs.org/projects/triplespec-focus/badge/?version=latest
+    :alt: Documentation Status
+    :target: https://triplespec-focus.readthedocs.io/en/latest/?badge=latest
+.. image::  https://img.shields.io/pypi/v/triplespec_focus.svg?style=flat
+    :alt: pypi
+    :target: https://pypi.org/project/triplespec-focus/
+.. image::  https://github.com/soar-telescope/triplespec_focus/actions/workflows/codeql-analysis.yml/badge.svg
+    :alt: CodeQL
+    :target: https://github.com/soar-telescope/triplespec_focus/actions/workflows/codeql-analysis.yml
+.. image::  https://img.shields.io/badge/Python-3.8-blue.svg
+    :alt: Python 3.8
+    :target: https://www.python.org/downloads/release/python-380/
+.. image::  https://img.shields.io/github/license/soar-telescope/triplespec_focus
+    :alt: Licence
+    :target: https://github.com/soar-telescope/triplespec_focus/blob/main/LICENSE
+
+
+Test Coverage
+=============
+
+.. image:: https://codecov.io/gh/soar-telescope/triplespec_focus/branch/main/graphs/sunburst.svg?token=S6Y6R7AQNY
+    :alt: Test Coverage
+
+
+Overview
+========
+
+This is a tool to obtain the best focus value for the Slit Viewer camera of the TripleSpec NIR spectrograph.
+More information on TripleSpec can be found at `NOIRLab Official Website <https://noirlab.edu/science/programs/ctio/instruments/triplespec41-nir-imaging-spectrograph>`_
+
+
+TripleSpec is a fixed configuration, this means that it has a fixed focus with respect to the telescope, but there is a
+slit viewing Camera that need focus adjustment.
+
+A slit viewing image looks like this:
+
+.. image:: _static/slit_view_sample.png
+
+The slit is visible near the top center.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: How to install
+
+   install
+
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: How to use it
+
+   data_overview
+   Using in a Terminal <use_from_terminal>
+   Using as a Library <use_as_library>
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: About
+
+   about
 
-A
-=
-bbb
 
 Indices and tables
 ==================

diff --git a/docs/install.rst b/docs/install.rst
@@ -0,0 +1,14 @@
+Install with pip
+################
+
+.. note::
+
+   We recommend using a virtual environment management system such as
+   `astroconda <https://astroconda.readthedocs.io/en/latest/>`_
+
+
+To install you need to have at least python 3.8, it is tested with python 3.9 and 3.10 as well.
+
+Just run the following command in a terminal.
+
+   ``pip install triplespec-focus``
diff --git a/docs/use_as_library.rst b/docs/use_as_library.rst
@@ -0,0 +1,160 @@
+Using as a Library
+##################
+
+
+This library can be integrated into other software, just import ``TripleSpecFocus`` create an instance and call it.
+
+
+.. code-block:: python
+
+   from triplespec_focus import TripleSpecFocus
+
+   focus = TripleSpecFocus(debug=False,
+                           date_key='DATE',
+                           date_time_key='DATE-OBS',
+                           focus_key='TELFOCUS',
+                           filename_key='FILENAME',
+                           file_pattern='*.fits',
+                           n_brightest=5,
+                           saturation=40000,
+                           plot_results=False,
+                           debug_plots=False)
+
+
+Since in this case all the parameters are the default ones it is equivalent to do:
+
+.. code-block:: python
+
+   from triplespec_focus import TripleSpecFocus
+
+   focus = TripleSpecFocus()
+
+
+Once the instance is created you can just call it or you can modify certain parameters.
+
+.. code-block:: python
+
+   results = focus()
+
+
+or
+
+
+.. code-block:: python
+
+   from pathlib import Path
+
+   data_path = Path('./')
+
+   results = focus(data_path=data_path,
+                   source_fwhm=7.0,
+                   det_threshold=5.0,
+                   mask_threshold=1,
+                   n_brightest=5,
+                   saturation_level=40000,
+                   show_mask=False,
+                   plot_results=False,
+                   debug_plots=False,
+                   print_all_data=False)
+
+
+Usually you would want to have more control so you can modify any parameters, but the most interesting
+part is that you can pass a list of files.
+
+Using the same ``data_path`` variable created in the previous example
+
+.. code-block:: python
+
+   file_list = sorted(data_path.glob(pattern='*.fits'))
+
+
+or create the list manually or programatically
+
+
+.. code-block:: python
+
+   file_list = [
+   '/path/to/file_001.fits',
+   '/path/to/file_003.fits',
+   '/path/to/file_007.fits',
+   '/path/to/file_008.fits',
+   '/path/to/file_010.fits',
+   '/path/to/file_012.fits',
+   ]
+
+   results = focus(file_list=file_list,
+                   source_fwhm=7.0,
+                   det_threshold=5.0,
+                   mask_threshold=1,
+                   n_brightest=5,
+                   saturation_level=40000,
+                   show_mask=False,
+                   plot_results=False,
+                   debug_plots=False,
+                   print_all_data=False)
+
+
+Interpreting the Results
+########################
+
+Using the option ``--plot-results``  or set ``plot_results=True`` you will get the following information at the end.
+
+.. figure:: _static/focus_results.png
+
+The sources used are plotted to the left and to the right you get the data and fitted models plot. The dashed vertical
+lines represent the best focus for each individual star. The solid vertical line represent the
+best focus value.
+
+
+The result is a  dictionary.
+
+
+.. code-block:: python
+
+   {
+        "date": "2022-04-14",
+        "time": "2022-04-14T02:00:16.472",
+        "mean_focus": -1037.9334768407,
+        "median_focus": -1042.3437309744,
+        "focus_std": 12.4463329703,
+        "fwhm": 4.400507903,
+        "best_image_name": "SV_ARC_13-04-2022_0013.fits",
+        "best_image_focus": -1059.0,
+        "best_image_fwhm": 4.451495851,
+        "focus_data": [
+            -1389.0,
+            -1279.0,
+            -1202.0,
+            -1169.0,
+            -1162.0,
+            -1122.0,
+            -1081.99,
+            -1059.0,
+            -1042.0,
+            -1002.0,
+            -962.0,
+            -949.0,
+            -922.0,
+            -882.0,
+            -839.0,
+            -729.0
+        ],
+        "fwhm_data": [
+            8.8346668203,
+            7.9968682153,
+            6.520501982,
+            6.6366621644,
+            5.6593294617,
+            4.9156293967,
+            4.8462257042,
+            4.451495851,
+            4.4960399387,
+            4.4620697186,
+            4.9432397845,
+            5.3684107482,
+            5.6873559877,
+            6.8445617244,
+            7.3650931863,
+            8.2617132835
+        ]
+    }
diff --git a/docs/use_from_terminal.rst b/docs/use_from_terminal.rst
@@ -0,0 +1,36 @@
+Use from terminal
+#################
+
+The installation will create a terminal entrypoint ``triplespec-focus``
+
+Getting help is as easy as running with the ``-h`` argument:
+
+
+.. figure:: _static/in_terminal_help.png
+
+If you run ``triplespec-focus`` from the same data folder as the location of the data, you don't need to specify any
+argument.
+
+The arguments, default values and options are listed in the following table:
+
+.. table:: Default values for arguments
+
+  ====================================== ============================ ========================
+        Argument                              Default Value               Options
+  ====================================== ============================ ========================
+   ``--data-path <input>``                Current Working Directory    Any valid path
+   ``--file-pattern <input>``             ``*.fits``                   Any pattern
+   ``--focus-key <input>``                ``TELFOCUS``                 Any valid FITS keyword
+   ``--filename-key <input>``             ``FILENAME``                 Any valid FITS keyword
+   ``--brightest <input>``                :math:`5`                    Any positive integer
+   ``--saturation <input>``               :math:`40000`                Any positive float
+   ``--source-fwhm <input>``              :math:`7`                    Any positive float
+   ``--detection-threshold <input>``      :math:`5`                    Any positive float
+   ``--plot-results``                     False                        True
+   ``--show-mask``                        False                        True
+   ``--debug``                            False                        True
+   ``--debug-plots``                      False                        True
+  ====================================== ============================ ========================
+
+
+After running the script with all desired parameters the result will be printed in the terminal.
diff --git a/triplespec_focus/entrypoints.py b/triplespec_focus/entrypoints.py
@@ -11,6 +11,7 @@ def run_triplespec_focus(args=None):
     focus = TripleSpecFocus(debug=args.debug,
                             focus_key=args.focus_key,
                             filename_key=args.filename_key,
+                            file_pattern=args.file_pattern,
                             n_brightest=args.brightest,
                             saturation=args.saturation,
                             plot_results=args.plot_results,