Merge pull request #22 from simontorres/update_docs_and_prepare_release

Update docs and prepare release

CHANGES.rst

@@ -1,11 +1,18 @@
-0.2.1 (Unreleased)
-==================
 
-- Created dedicated documentation for rtd
-- Fixed bug where return was missing
+.. _v0.3.0:
+
+0.3.0
+=====
+
+- Created dedicated documentation for readthedocs.
+- Fixed bug where return was missing,
 - GoodmanFocus need to be instantiated only once [#19]
+- Calling instance of GoodmanFocus can receive a list of files as input [#19]
 - Argument --file-pattern is now actually used in file selection [#18]
-- Eliminated some warnings
+- Eliminated some warnings.
+- Included plots in documentation.
+
+.. _v0.2.0:
 
 0.2.0
 =====

README.md

@@ -10,105 +10,9 @@
 
 Finds the best focus for one or more focus sequences.
 
-## How to Install
+# Documentation
 
-This tool requires python `3.6` at least to work. It will not install with `3.5`.
-
-We recommend using [astroconda](https://astroconda.readthedocs.io/en/latest/) since it is easier.
-
-### Using PYPI
-
-Create a virtual environment using `conda` and specify python version `3.6`.
-```bash
-conda create -n goodman_focus python=3.6
-```
-
-Install using `pip`
-```bash
-pip install goodman-focus
-```
-
-### Using github
-
-Clone the latest version using:
-
-```bash
-git clone https://github.com/soar-telescope/goodman_focus.git
-```
-
-Move into the new directory
-```bash
-cd goodman_focus
-```
-
-Create a virtual environment using the `environment.yml` file and activate it.
-```bash
-conda env create python=3.6 -f environment.yml
-
-conda activate goodman_focus
-
-```
-
-Install using `pip`
-```bash
-pip install .
-```
-## How to use it
-
-### From terminal
-
-There is an automatic script that will obtain focus from a folder containing
-a focus sequence.
-
-If you have `fits` files you can simply run.
-
-```bash
-goodman-focus
-```
-
-It will run with the following defaults:
-
-```text
---data-path: (Current Working Directory)
---file-pattern: *fits
---obstype: FOCUS
---features-model: gaussian
---debug: (not activated)
-
-```
-
-To get some help and a full list of options use:
-
-```bash
-goodman-focus -h
-```
-
-### In other code
-
-After installing using pip you can also import the class and instatiate it
-providing a list of arguments and values.
-
-```python
-from goodman_focus.goodman_focus import GoodmanFocus
-```
-
-If no argument is provided it will run with the default values.
-
-The list of arguments can be defined as follow:
-
-```python
-arguments = ['--data-path', '/provide/some/path',
-             '--file-pattern', '*.fits',
-             '--obstype', 'FOCUS',
-             '--features-model', 'gaussian',
-             '--debug']
-```
-
-
-``--features-model`` is the function/model to fit to each detected line. 
-``gaussian`` will use a ```Gaussian1D``` which provide more consistent results.
-and ``moffat`` will use a ```Moffat1D``` model which fits the profile better but 
-is harder to control and results are less consistent than when using a gaussian.
+All the documentation is maintained in https://goodman.readthedocs.io/projects/focus/en/latest/
 
 # Found a problem?
 

docs/conf.py

@@ -21,7 +21,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'Goodman Focus'
-copyright = '2019, Simon Torres'
+copyright = '2019, SOAR Telescope'
 author = 'Simon Torres'
 license = 'bsd3'
 
@@ -45,6 +45,7 @@
     'sphinx.ext.intersphinx',
     'sphinxcontrib.napoleon',
     'm2r',
+    'matplotlib.sphinxext.plot_directive',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/gettingdata.rst

@@ -0,0 +1,69 @@
+Getting Data
+############
+
+The goodman focus value ranges from :math:`-2000` to :math:`+2000` the best
+practice (from experience) is to sample every :math:`200`. If you want to refine
+you should not go below a :math:`100` step. If you already know the approximate
+focus value for a given setup, you don't need to do the full range, just take
+enough samples so it is possible to make a fit or see the trends.
+At least five points.
+
+
+.. note::
+
+   Always use the narrowest slit available
+
+
+Imaging
+*******
+
+For imaging, an image of the slit is obtained, illuminated by an
+uniform light such as a quartz lamp. A special ROI is used for faster reading.
+This does not affect the focus of course.
+
+.. plot::
+
+   import matplotlib.pyplot as plt
+   from ccdproc import CCDData
+
+   ccd = CCDData.read('_static/im_g_SDSS.fits', unit='adu')
+
+   fig, ax = plt.subplots(figsize=(8, 2))
+
+   ax.set_title("Imaging  - g-SDSS\nDome Lamp 40%")
+
+   ax.imshow(ccd.data, cmap='gray', clim=(484, 513))
+
+Spectroscopy
+************
+
+In spectroscopy a comparison lamp is observed and after every line is measured
+and fitted, an average is obtained with sigma clip rejection.
+
+.. plot::
+
+   import matplotlib.pyplot as plt
+   from ccdproc import CCDData
+
+   ccd = CCDData.read('_static/sp_400m1.fits', unit='adu')
+
+   fig, ax = plt.subplots(figsize=(8, 2))
+
+   ax.set_title("Spectroscopy - 400m1\nHgArNe")
+
+   ax.imshow(ccd.data, cmap='gray', clim=(490, 836))
+
+
+
+.. plot::
+
+   import matplotlib.pyplot as plt
+   from ccdproc import CCDData
+
+   ccd = CCDData.read('_static/sp_400m2.fits', unit='adu')
+
+   fig, ax = plt.subplots(figsize=(8, 2))
+
+   ax.set_title("Spectroscopy - 400m2\nHgArNe")
+
+   ax.imshow(ccd.data, cmap='gray', clim=(487, 1157))

docs/index.rst

@@ -17,11 +17,16 @@ Welcome to Goodman Focus' documentation!
     :target: https://pypi.org/project/goodman-focus/
     :alt: PyPI
 
+Overview
+========
 
-.. warning::
+This is a tool to obtain the best focus from a series of images obtained at
+different focus values. It works for imaging and for spectroscopy.
+
+This tool requires python `3.6` at least to work. It will not install with `3.5`.
+
+We recommend using `astroconda <https://astroconda.readthedocs.io/en/latest/>`_ since it is easier.
 
-   This project is under heavy development, therefore you might encounter
-   errors in documentation or it could be incomplete.
 
 .. toctree::
    :maxdepth: 2
@@ -34,6 +39,7 @@ Welcome to Goodman Focus' documentation!
    :maxdepth: 2
    :caption: How to Use it
 
+   gettingdata
    usingit
 
 
@@ -42,6 +48,12 @@ Welcome to Goodman Focus' documentation!
    :caption: Contents:
 
 
+.. toctree::
+   :maxdepth: 2
+   :caption: About
+
+   changes
+
 
 Indices and tables
 ==================

docs/install.rst

@@ -1,7 +1,12 @@
+.. note::
+
+   We recommend using a virtual environment management system such as
+   `astroconda <https://astroconda.readthedocs.io/en/latest/>`_
+
 .. _`Installing with PIP`:
 
-Using PYPI
-##########
+Install Using PYPI
+##################
 
 Create a virtual environment using `conda` and specify python version `3.6`.
 
@@ -11,8 +16,8 @@ Install using `pip`
 
   ``pip install goodman-focus``
 
-Using GitHub
-############
+Install Using GitHub
+####################
 
 Clone the latest version using:
 

docs/usingit.rst

@@ -1,5 +1,5 @@
-From terminal
-#############
+Running from terminal
+#####################
 
 There is an automatic script that will obtain focus from a folder containing
 a focus sequence.
@@ -30,8 +30,8 @@ To get some help and a full list of options use:
   ``goodman-focus -h``
 
 
-As a Library
-############
+Using it as a library
+#####################
 
 After installing :ref:`Installing with PIP` you can also import the class and instantiate it
 providing a set of arguments and values or using default ones.
@@ -82,6 +82,9 @@ Finally you need to call the instance, here is a full example.
   results = goodman_focus()
 
 
+However since version :ref:`v0.3.0` you can pass a list of files and all will only check that all files exists
+
+
 Interpreting Results
 ####################
 
@@ -104,6 +107,74 @@ explained in :ref:`decoding-mode-name`
    'SP_Red_400m1_NOFILTER': -492.0760380190095,
    'SP_Red_400m2_GG455': -1032.6413206603302}
 
+
+It is also possible to obtain a plot, from terminal, use ``--plot-results``.
+Below is a repreduction of results obtained  with test data.
+
+.. plot::
+
+  from astropy.modeling import models
+  import numpy
+  import matplotlib.pyplot as plt
+
+  best_focus = -571.483741871
+  mode_name = 'IM_Red_g-SDSS'
+
+  data = {'file': ['0186_focus_gp.fits',
+                   '0187_focus_gp.fits',
+                   '0188_focus_gp.fits',
+                   '0189_focus_gp.fits',
+                   '0190_focus_gp.fits',
+                   '0191_focus_gp.fits',
+                   '0192_focus_gp.fits',
+                   '0193_focus_gp.fits',
+                   '0194_focus_gp.fits',
+                   '0195_focus_gp.fits'],
+          'fwhm': [5.291526,
+                   4.712950,
+                   4.112902,
+                   3.449884,
+                   2.930342,
+                   2.665300,
+                   2.579470,
+                   2.611492,
+                   2.815271,
+                   3.246117],
+          'focus': [-1496,
+                    -1344,
+                    -1197,
+                    -1045,
+                    -896,
+                    -745,
+                    -598,
+                    -447,
+                    -299,
+                    -148]
+          }
+
+  polynomial = models.Polynomial1D(degree=5)
+  polynomial.c0.value = 3.93919764664
+  polynomial.c1.value = 0.00602356641338
+  polynomial.c2.value = 1.04158253e-05
+  polynomial.c3.value = 1.16769514e-08
+  polynomial.c4.value = 9.45592111846e-12
+  polynomial.c5.value = 2.8321431518e-15
+
+  fig, ax = plt.subplots(figsize=(10,7))
+
+  ax.plot(data['focus'], data['fwhm'], marker='x', label='Measured FWHM')
+  ax.axvline(best_focus, color='k', label='Best Focus')
+  ax.set_title("Best Focus:\n{} {:.3f}".format(mode_name, best_focus))
+  ax.set_xlabel("Focus Value")
+  ax.set_ylabel("FWHM or Mean FWHM")
+
+  poly_x_axis = numpy.linspace(data['focus'][0], data['focus'][-1], 1000)
+
+  ax.plot(poly_x_axis, polynomial(poly_x_axis), label='Model')
+
+  ax.legend(loc='best')
+
+
 .. _decoding-mode-name:
 Decoding de mode name
 *********************