Debian Codegraph @

docs/index.rst

raw
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: