Improved documentation

Former-commit-id: 49e17786171ec8d38cee529a04c31076a9fef2fd

docs/Makefile

@@ -16,4 +16,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/about.rst

@@ -11,4 +11,4 @@ Questions & feedback
 Attribution
 -----------
 
-Please cite Stolker et al. in prep. whenever results from *species* are used in a publication. Please also make sure to give credit the relevant papers regarding the use of the publicly available data that *species* is using, such as the photometric and spectral libraries, atmospheric models, filter transmission curves, and photometry of individual objects. More details will follow.
+Please cite `Stolker et al. (2020) <https://ui.adsabs.harvard.edu/abs/2019arXiv191213316S/>`_ whenever results from *species* are used in a publication. Please also make sure to give credit the relevant papers regarding the use of the publicly available data that *species* is using, such as the photometric and spectral libraries, atmospheric models, evolutionary models, and photometry of individual objects.

docs/configuration.rst

@@ -3,19 +3,18 @@
 Configuration
 =============
 
-A configuration file is required in the working folder with the name `species_config.ini`. The file contains the path to the HDF5 database, the path to the configuration file, and the folder where all the data is dowloaded before it is stored into the database.
-
-The paths can be either absolute or relative to the working folder. It is recommended to use the same input folder for different configurations of `species` such that data only has to be downloaded once. As an example, this is what the content of the configuration file may look like:
+A configuration file with the name `species_config.ini` is required in the working folder. At the moment, the file only contains the folder path where all the data is dowloaded before it is stored into the database. The path can be provided either absolute or relative to the working folder. This is what the content of the configuration file may look like:
 
 .. code-block:: ini
 
    [species]
-   database = species_database.hdf5
-   config = species_config.ini
-   input = /path/to/store/data/
+   data_folder = /path/to/store/data/
 
 A configuration file with default values is automatically created when `species` is initiated by running :class:`~species.core.setup.SpeciesInit` and no configuration file is present in the working folder, for example::
 
    import species
 
-   species.SpeciesInit(config_path='./')
+   species.SpeciesInit(config_path='./')
+
+.. tip::
+   The same `data_folder` can be set in multiple configuration files of `species`. In this way, the data is only downloaded once and easily reused by a new instance of :class:`~species.core.setup.SpeciesInit`.

docs/contributing.rst

@@ -3,4 +3,4 @@
 Contributing
 ============
 
-Contributions are very welcome, please consider `forking <https://help.github.com/en/articles/fork-a-repo>`_ the repository and creating a `pull request <https://github.com/tomasstolker/species/pulls>`_. Bug reports can be provided by creating an `issue <https://github.com/tomasstolker/species/issues>`_ on the Github page.
+Contributions are very welcome, please consider `forking <https://help.github.com/en/articles/fork-a-repo>`_ the repository and creating a `pull request <https://github.com/tomasstolker/species/pulls>`_. Bug reports can be provided by creating an `issue <https://github.com/tomasstolker/species/issues>`_ on the Github page.

docs/examples.rst

@@ -82,7 +82,7 @@ The following code will download the IRTF spectral library and add the spectra t
                          xlim=(1., 2.5),
                          offset=(-0.08, -0.06))
 
-.. image:: _images/photometry.png
+.. image:: https://people.phys.ethz.ch/~stolkert/species/photometry.png
    :width: 80%
    :align: center
 
@@ -116,7 +116,7 @@ Here photometric data of 51 Eri b (Rajan et al. 2017) is added to the database.
                                 output='color_mag.pdf',
                                 legend='upper left')
 
-.. image:: _images/color_mag.png
+.. image:: https://people.phys.ethz.ch/~stolkert/species/color_mag.png
    :width: 70%
    :align: center
 
@@ -146,7 +146,7 @@ In the last example, the DRIFT-PHOENIX atmospheric models are added to the datab
                          xlim=(1., 5.),
                          ylim=(0., 1.1e5))
 
-.. image:: _images/model1.png
+.. image:: https://people.phys.ethz.ch/~stolkert/species/model1.png
    :width: 80%
    :align: center
 
@@ -163,7 +163,7 @@ Or, a spectrum with the original spectral resolution can be obtained from the (d
                          xlim=(1., 5.),
                          ylim=(0., 2.15e-15))
 
-.. image:: _images/model2.png
+.. image:: https://people.phys.ethz.ch/~stolkert/species/model2.png
    :width: 80%
    :align: center
 
@@ -276,11 +276,11 @@ Which gives:
    NACO Mp [mag] = 6.407877593040467
    NACO Mp [W m-2 micron-1] = 5.9164296e-14
 
-.. image:: _images/posterior.png
+.. image:: https://people.phys.ethz.ch/~stolkert/species/posterior.png
    :width: 40%
    :align: center
 
-.. image:: _images/spectrum.png
+.. image:: https://people.phys.ethz.ch/~stolkert/species/spectrum.png
    :width: 90%
    :align: center
 
@@ -376,7 +376,7 @@ In this example we fit the available photometry of beta Pic b with the DRIFT-PHO
                          offset=(-0.25, -0.06),
                          output='plot/spectrum.pdf')
 
-.. image:: _images/betapic.png
+.. image:: https://people.phys.ethz.ch/~stolkert/species/betapic.png
    :width: 100%
    :align: center
 
@@ -471,7 +471,7 @@ When creating a color-magnitude diagram, various data can be combined such as ph
                                 legend='upper right',
                                 output='isochrones.pdf')
 
-.. image:: _images/isochrone.png
+.. image:: https://people.phys.ethz.ch/~stolkert/species/isochrone.png
    :width: 60%
    :align: center
 

docs/index.rst

@@ -3,13 +3,13 @@
 Documentation for species
 =========================
 
-*species* is a toolkit for analyzing spectral and photometric data of planetary and substellar atmospheres. The package has been developed and is maintained by |stolker|.
+*species* is a toolkit for spectral and photometric analysis of planetary and substellar atmospheres. The package has been developed and is maintained by |stolker|.
 
 .. |stolker| raw:: html
 
 	<a href="https://people.phys.ethz.ch/~stolkert/" target="_blank">Tomas Stolker</a>
 
-.. figure:: _images/species.jpg
+.. figure:: https://people.phys.ethz.ch/~stolkert/species/species.jpg
    :width: 30%
    :align: center
 
@@ -34,4 +34,4 @@ Documentation for species
    :caption: About species
 
    contributing
-   about
+   about

docs/installation.rst

@@ -3,23 +3,113 @@
 Installation
 ============
 
-*species* is compatible with Python 3 and can be installed from the |pypi| with the |pip|::
+*species* is compatible with Python 3 and is available in the |pypi| and on |github|.
+
+Virtual Environment
+-------------------
+
+It is recommended to use a Python virtual environment to install and run `species` such that the correct versions of the dependencies can be installed without affecting other installed Python packages. First install `virtualenv`, for example with the |pip|:
+
+.. code-block:: console
+
+    $ pip install virtualenv
+
+Then create a virtual environment for Python 3:
+
+.. code-block:: console
+
+    $ virtualenv -p python3 folder_name
+
+And activate the environment with:
+
+.. code-block:: console
+
+    $ source folder_name/bin/activate
+
+A virtual environment can be deactivated with:
+
+.. code-block:: console
+
+    $ deactivate
+
+.. important::
+   Make sure to adjust the path where the virtual environment is installed and activated.
+
+Installation from PyPI
+----------------------
+
+*species* can be installed from the |pypi| with the |pip|::
 
     $ pip install species
 
-Alternatively, the repository can be cloned from |github|::
+If you do not use a virtual environment then you may have to add the ``--user`` argument:
+
+.. code-block:: console
+
+    $ pip install --user species
+
+To update the installation to the most recent version:
+
+.. code-block:: console
+
+   $ pip install --upgrade species
+
+Installation from Github
+------------------------
+
+Installation from Github is also possible by cloning the repository:
+
+.. code-block:: console
 
     $ git clone git@github.com:tomasstolker/species.git
 
-In that case, the dependencies can be installed from the *species* folder::
+In that case, the dependencies can be installed from the `species` repository folder:
+
+.. code-block:: console
 
     $ pip install -r requirements.txt
 
-The installation can be tested by starting Python in interactive mode and printing the version number::
+Once a local copy of the repository exists, new commits can be pulled from Github with:
+
+.. code-block:: console
+
+    $ git pull origin master
+
+And to update the dependencies for compatibility with `species`:
+
+.. code-block:: console
+
+    $ pip install --upgrade -r requirements.txt 
+
+By adding the path of the repository to the ``PYTHONPATH`` environment variable enables `species` to be imported from any location:
+
+.. code-block:: console
+
+    $ echo "export PYTHONPATH='$PYTHONPATH:/path/to/species'" >> folder_name/bin/activate
+
+.. important::
+   Make sure to adjust local path in which `species` will be cloned from the Github repository.
+
+Do you want to makes changes to the code? Then please fork the `species` repository on the Github page and clone your own fork instead of the main repository. Contributions and pull requests are very welcome (see :ref:`contributing` section).
+
+Testing species
+---------------
+
+The installation can be tested by starting Python in interactive mode and printing the `species` version:
+
+.. code-block:: python
 
     >>> import species
     >>> species.__version__
 
+.. tip::
+   If the `species` package is not find by Python then possibly the path was not set correctly. The list of folders that are searched by Python for modules can be printed in interactive mode as:
+
+      .. code-block:: python
+
+         >>> import sys
+         >>> sys.path
+
 .. |pypi| raw:: html
 
    <a href="https://pypi.org/project/species/" target="_blank">PyPI repository</a>

docs/running.rst

@@ -3,7 +3,11 @@
 Running species
 ===============
 
-Here you find a first example to get an impression of what a typical workflow with `species` looks like. The atmospheric model spectra will be downloaded and added to the database. The grid of spectra is then interpolated and plotted for the given parameter values, together with the photometry of PZ Tel B and the filter transmission curves. The code can be executed from the command line or within a `Jupyter notebook <https://jupyter.org/>`_.
+To get a first impression, this page shows what a typical workflow with `species` looks like.
+
+First, the atmospheric model spectra will be downloaded and added to the database. Available photometry of PZ Tel B will be read from :class:`~species.data.companions` dictionary and added to the database. Alternatively, the :func:`~species.data.database.Database.add_object` function can be used for manually creating an planet or other type of object in the database. Then, the model spectra are read from the database, interpolated at the provided parameter values, and stored in a :class:`~species.core.box.ModelBox`. The data of PZ Tel B is read from the database and stored in a :class:`~species.core.box.ObjectBox`. The :class:`~species.core.box.Box` objects are given to the :func:`~species.plot.plot_spectrum.plot_spectrum` function, together with the filter names for which the photometry is available.
+
+The following code can be executed from the command line or within a `Jupyter notebook <https://jupyter.org/>`_.
 
 .. code-block:: python
 
@@ -15,40 +19,41 @@ Here you find a first example to get an impression of what a typical workflow wi
    # create a database object
    database = species.Database()
 
-   # add the AMES-Dusty atmospheric models
-   database.add_model(model='ames-dusty',
-                      wavelength=(0.1, 6.),
-                      teff=(2500., 3500.),
-                      specres=1000.)
+   # add the AMES-Cond atmospheric models
+   database.add_model(model='ames-cond',
+                      wavel_range=(0.1, 6.),
+                      teff_range=(2800., 3000.),
+                      spec_res=1000.)
 
    # add the photometry of PZ Tel B that is available in species.data.companions
    database.add_companion(name='PZ Tel B')
 
    # create an object for reading model spectra
-   readmodel = species.ReadModel(model='ames-dusty',
-                                 wavelength=(0.1, 6.0))
+   readmodel = species.ReadModel(model='ames-cond',
+                                 wavel_range=(0.1, 6.))
 
    # interpolate the grid of spectra
-   modelbox = readmodel.get_model(model_par={'teff': 3000.,
-                                             'logg': 4.0,
-                                             'feh': 0.0,
-                                             'radius': 2.2,
-                                             'distance': 47.13},
-                                  specres=100.)
+   modelbox = readmodel.get_model(model_param={'teff': 2900.,
+                                               'logg': 4.5,
+                                               'feh': 0.0,
+                                               'radius': 2.2,
+                                               'distance': 47.13},
+                                  spec_res=100.)
 
    # read the photometry of PZ Tel B
    objectbox = database.get_object(object_name='PZ Tel B')
 
    # plot the spectrum, photometry, and filter transmission curves
+   # the objectbox requires colors for the photometry and spectrum (set to None)
    species.plot_spectrum(boxes=(modelbox, objectbox),
                          filters=objectbox.filter,
-                         colors=('black', ('tomato', )),
-                         offset=(-0.08, -0.07),
+                         colors=('black', ('tomato', None)),
+                         offset=(-0.08, -0.06),
                          xlim=(0.2, 5.5),
                          ylim=(0., 4.8e-14),
                          legend='upper right',
                          output='spectrum.pdf')
 
-.. image:: _images/example.png
+.. image:: https://people.phys.ethz.ch/~stolkert/species/example.png
    :width: 100%
    :align: center

requirements.txt

@@ -1,4 +1,4 @@
-astropy ~= 3.2
+astropy ~= 4.0
 astroquery ~= 0.3
 corner ~= 2.0
 emcee ~= 3.0

species/core/setup.py

@@ -1,5 +1,5 @@
 """
-Setup module.
+Module for setting up species in the working folder.
 """
 
 import os
@@ -13,7 +13,8 @@
 
 class SpeciesInit:
     """
-    Text.
+    Class for initiating species by creating the database and configuration file in case they are
+    not present in the working folder, and creating the data folder for storage of input data.
     """
 
     def __init__(self,
@@ -48,8 +49,7 @@ def __init__(self,
             with open(config_file, 'w') as file_obj:
                 file_obj.write('[species]\n')
                 file_obj.write('database = species_database.hdf5\n')
-                file_obj.write('config = species_config.ini\n')
-                file_obj.write('input = ./\n')
+                file_obj.write('data_folder = ./data/\n')
 
             sys.stdout.write(' [DONE]\n')
             sys.stdout.flush()
@@ -58,13 +58,13 @@ def __init__(self,
         config.read_file(open(config_file))
 
         database_file = config['species']['database']
-        input_path = config['species']['input']
+        data_folder = config['species']['data_folder']
 
-        if not os.path.exists(input_path):
-            sys.stdout.write('Creating input folder...')
+        if not os.path.exists(data_folder):
+            sys.stdout.write('Creating data folder...')
             sys.stdout.flush()
 
-            os.makedirs(input_path)
+            os.makedirs(data_folder)
 
             sys.stdout.write(' [DONE]\n')
             sys.stdout.flush()