| 1 |
******************* |
| 2 |
APLpy documentation |
| 3 |
******************* |
| 4 |
|
| 5 |
`APLpy <http://aplpy.github.io>`_ (the Astronomical Plotting Library in Python - |
| 6 |
pronounced *apple pie*) is a Python package module aimed at producing |
| 7 |
publication-quality plots of astronomical imaging data, and has been around |
| 8 |
since 2009. |
| 9 |
|
| 10 |
Since APLpy 2.0, APLpy relies on Astropy's `WCSAxes |
| 11 |
<http://docs.astropy.org/en/stable/visualization/wcsaxes/index.html>`_ package |
| 12 |
to draw the coordinate axes and grids, which in turn uses `Matplotlib |
| 13 |
<https://matplotlib.org>`_ to do the rendering. This is a big change compared to |
| 14 |
previous versions of APLpy, which handled the drawing of the coordinate axes and |
| 15 |
grids directly. For information about backward-compatibility, see the |
| 16 |
`Backward-compatibility notes`_. |
| 17 |
|
| 18 |
Note that APLpy 2.x is only compatible with Python 3.5 and later. |
| 19 |
|
| 20 |
If you use APLpy for a publication, please consider citing it as described in |
| 21 |
the `CITATION <https://github.com/aplpy/aplpy/blob/master/CITATION>`__ file. |
| 22 |
|
| 23 |
Should you use APLpy? |
| 24 |
===================== |
| 25 |
|
| 26 |
The `WCSAxes`_ package in Astropy can be used without APLpy to produce plots of |
| 27 |
astronomical images. It provides a programmatic interface that is conceptually |
| 28 |
very close to Matplotlib, and can be used to make plots that are more complex |
| 29 |
than what APLpy has historically been able to do. If you want to be able to |
| 30 |
control the appearance of your plots in detail, including for example adding |
| 31 |
overlay coordinate systems, or if you simply want a programmatic interface that |
| 32 |
is consistent with Matplotlib, then we recommend you use `WCSAxes`_ directly. If |
| 33 |
you have a FITS file and just want to make it into a plot in a couple of lines, |
| 34 |
then APLpy is the package for you. |
| 35 |
|
| 36 |
Installing APLpy |
| 37 |
================ |
| 38 |
|
| 39 |
You can install APLpy with pip using:: |
| 40 |
|
| 41 |
pip install aplpy |
| 42 |
|
| 43 |
If you prefer to use conda, you can install APLpy with:: |
| 44 |
|
| 45 |
conda install -c astropy aplpy |
| 46 |
|
| 47 |
Using APLpy |
| 48 |
=========== |
| 49 |
|
| 50 |
APLpy includes a :class:`~aplpy.FITSFigure` class that provides a simple |
| 51 |
interface to make plots and provides easy methods for overlaying shapes, beams, |
| 52 |
adding colorbars, and overplotting regions. |
| 53 |
|
| 54 |
.. toctree:: |
| 55 |
:maxdepth: 1 |
| 56 |
|
| 57 |
fitsfigure/quickstart.rst |
| 58 |
fitsfigure/quick_reference.rst |
| 59 |
fitsfigure/arbitrary_coordinate_systems.rst |
| 60 |
fitsfigure/slicing.rst |
| 61 |
fitsfigure/howto_noninteractive.rst |
| 62 |
fitsfigure/howto_avm.rst |
| 63 |
fitsfigure/howto_subplot.rst |
| 64 |
rgb |
| 65 |
|
| 66 |
.. _backcompat: |
| 67 |
|
| 68 |
Backward-compatibility notes |
| 69 |
============================ |
| 70 |
|
| 71 |
APLpy continues to include a :class:`~aplpy.FITSFigure` class that provides a |
| 72 |
simpler interface and deals with the reading of FITS files and constructing WCS |
| 73 |
objects. This class uses `WCSAxes`_ behind the scenes, but provides easy methods |
| 74 |
for overlaying shapes, beams, adding colorbars, and overplotting regions. The |
| 75 |
interface of this class is intended to be backward-compatible with existing |
| 76 |
scripts that used APLpy 1.0 and earlier. If you run into issues with old |
| 77 |
scripts, please report the issues in the `issue tracker |
| 78 |
<https://github.com/aplpy/aplpy/issues>`_. |
| 79 |
|
| 80 |
Note however that if you have made adjustments to figures in the past using private |
| 81 |
attributes (e.g. ``fig._ax1``), these will no longer work and this cannot be |
| 82 |
fixed in APLpy 2.x. |
| 83 |
|
| 84 |
In any case, if you have issues with APLpy 2.x and want to continue using APLpy |
| 85 |
1.x, you can always restrict the version of APLpy when installing it using |
| 86 |
e.g.:: |
| 87 |
|
| 88 |
pip install "aplpy<2" |
| 89 |
|
| 90 |
or:: |
| 91 |
|
| 92 |
conda install "aplpy<2" |
| 93 |
|
| 94 |
If critical bugs are found in the 1.x releases and can easily be fixed, we may |
| 95 |
release new 1.x versions. |
| 96 |
|
| 97 |
.. _api: |
| 98 |
|
| 99 |
Reference/API |
| 100 |
============= |
| 101 |
|
| 102 |
.. automodapi:: aplpy |
| 103 |
:no-main-docstr: |
| 104 |
:no-heading: |
| 105 |
:no-inheritance-diagram: |
| 106 |
:inherited-members: |