Merge pull request #4 from DougBurke/ciao-411

Support Python 3.5 and add functionality

.gitignore

@@ -0,0 +1,13 @@
+*~
+
+examples/m87
+dist
+docs/_build
+**/api
+
+build
+__pycache__
+.cache/
+
+deproject.egg-info
+.eggs

.travis.yml

@@ -0,0 +1,37 @@
+# Based on
+# https://github.com/astrofrog/example-travis-conda/blob/master/.travis.yml
+# but all problems are mine
+#
+
+dist: xenial
+
+language: python
+
+matrix:
+  include:
+    - python: 3.7
+      env: NUMPY=1.15
+
+before_install:
+  - wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda3.sh
+  - chmod +x miniconda3.sh
+  - ./miniconda3.sh -b -p /home/travis/miniconda
+  - export PATH=/home/travis/miniconda/bin:$PATH
+  - conda update --yes conda
+
+  # DEBUG information
+  - conda info -a
+  - python --version
+
+install:
+  - conda create --yes -n test python=$TRAVIS_PYTHON_VERSION
+  # - conda activate test
+  - source activate test
+  - conda install --yes numpy=$NUMPY pytest
+  - conda install --yes -c sherpa sherpa
+
+  # I guess we should actually install the software!
+  - pip install .
+
+script:
+  - py.test

README.rst

@@ -1,25 +1,126 @@
 Deproject
 =========
 
-``Deproject`` is a CIAO Sherpa extension package to facilitate
-deprojection of two-dimensional annular X-ray spectra to recover the
-three-dimensional source properties.  For typical thermal models this would
-include the radial temperature and density profiles. This basic method 
-has been used extensively for X-ray cluster analysis and is the basis for the
-XSPEC model ``projct``.  The ``deproject`` module brings this
-functionality to *Sherpa* as a Python module that is straightforward to use and
-understand.
+``Deproject`` is a `Sherpa <https://sherpa.readthedocs.io/>`_ extension package
+to facilitate deprojection of two-dimensional annular X-ray spectra to recover
+the three-dimensional source properties.  For typical thermal models this would
+include the radial temperature and density profiles. This basic method has been
+used extensively for X-ray cluster analysis and is the basis for the XSPEC
+model ``projct``.  The ``deproject`` module brings this functionality to
+*Sherpa* as a Python module that is straightforward to use and understand.
 
 The basic physical assumption of ``deproject`` is that the extended source
 emissivity is constant and optically thin within spherical shells whose radii
 correspond to the annuli used to extract the specta.  Given this assumption one
 constructs a model for each annular spectrum that is a linear volume-weighted
 combination of shell models.
 
+Version 0.2 of ``deproject`` is limited to circular annuli.
+
+Further documentation is available at https://deproject.readthedocs.io/
+
 License
 -------
 
 The ``deproject`` module is released under the
 `BSD 2-Clause license <https://choosealicense.com/licenses/bsd-2-clause/>`_,
 available as the file ``LICENSE`` in the source distribution.
 
+Requirements
+------------
+
+The installation assumes that you are installing ``deproject`` into
+the `CIAO environment <http://cxc.harvard.edu/ciao/>`_ (CIAO 4.11 or
+later), since this is the easiest way to get the XSPEC models along
+with Sherpa. The `standalone Sherpa <https://sherpa.readthedocs.io/>`_
+version can be used, but in this case you will need to `build Sherpa
+with XSPEC support
+<https://sherpa.readthedocs.io/en/latest/install.html#xspec>`_.
+
+The following Python packages are required:
+
+ - sherpa
+ - `Astropy <http://www.astropy.org/>`_ (restricted to version 3.0 when
+   using CIAO 4.11)
+ - `SciPy <https://www.scipy.org/scipylib/>`_.
+
+Installation
+------------
+
+The ``deproject`` module should install with the following command
+(assuming CIAO 4.11 is already installed):
+
+  echo "numpy==1.12.1" > constraints.txt
+  pip install -c constraints.txt 'astropy<3.1' deproject
+
+Example
+-------
+
+If you have a set of X-ray PHA spectra called src<n>.pi, where <n> is
+an integer representing the annulus number, and the files contain the
+``XFLT0001`` to ``XFLT0005`` header keywords used by the
+`XSPEC projct model <https://asd.gsfc.nasa.gov/XSPECwiki/projct_model>`_,
+then a
+`Deproject object <https://deproject-test.readthedocs.io/en/latest/modules/api/deproject.deproject.Deproject.html#deproject.deproject.Deproject>`_
+can be created using the
+`deproject_from_xflt <https://deproject-test.readthedocs.io/en/ciao-411/modules/api/deproject.deproject.deproject_from_xflt.html>`_
+helper routine with the commands:
+
+  >>> from deproject import deproject_from_xflt
+  >>> from astropy import units as u
+  >>> dep = deproject_from_xflt('src*.pi', 0.492 * u.arcsec)
+
+where, in this example, the ``XFLT0001`` and ``XFLT0002`` keywords,
+which specify the inner and outer radii of the annulus, are in
+ACIS pixels, and so need to be multiplied by 0.492 arcseconds to
+convert to an angle (the second parameter).
+
+This will automatically load the spectra into separate Sherpa datasets,
+which *can* be fitted individually, but it is generally easier to use
+the object returned by ``deproject_from_xflt``. For instance, the
+following will set the data range to be fit for *each* spectra and ensure
+that the background is subtracted before fitting:
+
+  >>> dep.ignore(None, 0.5)
+  >>> dep.ignore(7.0, None)
+  >>> dep.subtract()
+
+Sherpa functions are used to change the statistic and optimiser:
+
+  >>> from sherpa.astro import ui
+  >>> ui.set_stat('chi2xspecvar')
+  >>> ui.set_method('levmar')
+
+The data can be fit, and errors estimated for all the parameter, using
+the onion-skin deprojection approach, with the following commands:
+
+  >>> onion = dep.fit()
+  >>> errs = dep.conf()
+
+The return value includes the density (and errors, if appropriate), as
+an `Astropy Quantity <http://docs.astropy.org/en/stable/units/>`_.
+
+  >>> print(onion['density'])
+  print(onion['density'])
+        density
+        1 / cm3
+  --------------------
+    0.1100953546292787
+   0.07736622021374819
+   0.04164827967805805
+   0.03630168106524076
+  0.025221797991301052
+  0.021845331641349316
+                   ...
+  0.012396857131392835
+   0.01336640115325031
+  0.012303975980575187
+  0.013631563529090736
+  0.013996131292837352
+  0.010843683594144967
+  0.023067220584935984
+  Length = 20 rows
+
+The `on-line documentation <https://deproject.readthedocs.io/>`_
+contains more information, including creating the ``Deproject`` object
+directly (without the need for the ``XFLTxxxx`` keywords).