Skip to main content
`Ctrl`+`K`

# Plotting with Astroplan

`astroplan` currently has convenience functions for making three different types of plots: airmass vs time, parallactic angle vs time and sky charts. This plotting functionality in `astroplan` requires Matplotlib (although non- plotting functionality will work even without Matplotlib ). The use of additional plotting packages (like Seaborn) is not explicitly prevented, but may or may not actually work.

All `astroplan` plots return a `Axes` object (which by convention is assigned to the name `ax` in these tutorials). You can further manipulate the returned `ax` object, including using it as input for more `astroplan` plotting functions, or you can simply display/print the plot.

## Contents

> - Time Dependent Plots

> - Sky Charts

> - Finder Chart/Image

## Time Dependent Plots

Although all `astroplan` plots are time-dependent in some way, we label those that have a time-based axis as “time-dependent”.

`astroplan` currently has a few different types of “time-dependent” plots, for example `plot_airmass`, `plot_altitude` and `plot_parallactic`. These take, at minimum, `Observer`, `FixedTarget` and `Time` objects as input.

Airmass vs time plots are made the following way:

    >>> from astroplan.plots import plot_airmass

    >>> plot_airmass(target, observer, time)

Parallactic angle vs time plots are made the following way:

    >>> from astroplan.plots import plot_airmass

    >>> plot_parallactic(target, observer, time)

Below are general guidelines for working with time-dependent plots in `astroplan`. Examples use airmass but apply to parallactic angle as well.

See also

`astropy.coordinates.AltAz.secz`

`astroplan.Observer.parallactic_angle`

### Making a quick plot

Any plot function in `astroplan` with a time-based axis will allow you to make a quick plot over a 24-hour period.

After constructing `Observer` and `FixedTarget` objects, construct a `Time` object with a single instance in time and issue the plotting command.

    >>> import matplotlib.pyplot as plt
    >>> from astropy.time import Time
    >>> from astroplan.plots import plot_airmass

    >>> observe_time = Time('2000-06-15 23:30:00')

    >>> plot_airmass(target, observer, observe_time)
    >>> plt.show()

(`Source code`, `png`, `hires.png`, `pdf`, `svg`)

As you can see, the 24-hour plot is centered on the time input. You can also use array `Time` objects for these quick plots–they just can’t contain more than one instance in time.

For example, these are acceptable time inputs:

    Time(['2000-06-15 23:30:00'])

    [Time('2000-06-15 23:30:00')]

You can also add a second y-axis (on the right side) which shows the corresponding altitude of the targets:

(`Source code`, `png`, `hires.png`, `pdf`, `svg`)

You can make altitude the primary y-axis rather than airmass by using `plot_altitude`:

(`Source code`, `png`, `hires.png`, `pdf`, `svg`)

### Specifying a time window

If you want to see airmass plotted over a window that is not 24 hours long or you want to control the precision of the plot, you must specify every time for which you want to see an airmass plotted. Therefore, an array `Time` object is necessary.

To quickly populate an `Time` object with many instances of time, use Numpy and `units`. See example below.

#### Centering the window at some time

To center your window at some instance in time:

>     >>> import numpy as np
>     >>> import matplotlib.pyplot as plt
>     >>> import astropy.units as u
>     >>> from astropy.time import Time
>     >>> from astroplan.plots import plot_airmass

>     >>> observe_time = Time('2000-06-15 23:30:00')
>     >>> observe_time = observe_time + np.linspace(-5, 5, 55)*u.hour

>     >>> plot_airmass(target, observer, observe_time)
>     >>> plt.show()

(`Source code`, `png`, `hires.png`, `pdf`, `svg`)

#### Specify start and end times

If you know the start and end times of your observation run, you can use a `TimeDelta` object to create an array for time input:

    >>> import numpy as np
    >>> import matplotlib.pyplot as plt
    >>> from astropy.time import Time
    >>> from astroplan.plots import plot_airmass

    >>> start_time = Time('2000-06-15 20:00:00')
    >>> end_time = Time('2000-06-16 04:00:00')
    >>> delta_t = end_time - start_time
    >>> observe_time = start_time + delta_t*np.linspace(0, 1, 75)

    >>> plot_airmass(target, observer, observe_time)
    >>> plt.show()

(`Source code`, `png`, `hires.png`, `pdf`, `svg`)

### Plotting a quantity for multiple targets

If you want to plot airmass information for multiple targets, simply reissue the `plot_airmass` command, using a different `FixedTarget` object as input this time. Repeat until you have as many targets on the plot as you wish:

    >>> import numpy as np
    >>> import matplotlib.pyplot as plt
    >>> from astropy.time import Time
    >>> from astroplan.plots import plot_airmass

    >>> observe_time = Time('2000-06-30 23:30:00') + np.linspace(-7.0, 5.5, 50)*u.hour

    >>> plot_airmass(target, observer, observe_time)
    >>> plot_airmass(other_target, observer, observe_time)
    >>> plot_airmass(third_target, observer, observe_time)

    >>> plt.legend(shadow=True, loc=2)
    >>> plt.show()

(`Source code`, `png`, `hires.png`, `pdf`, `svg`)

When you’re ready to make a different plot, use `ax.cla()` to clear the current `Axes` object.

### Changing style options

The default line for time-dependent plots is solid and the default label (should you choose to display a legend) is the name contained in the `Target` object. You can change the linestyle, color, label and other plotting properties by setting the style_kwargs option.

    >>> import matplotlib.pyplot as plt
    >>> from astroplan.plots import plot_airmass

    >>> sirius_styles = {'linestyle': '--', 'color': 'r'}
    >>> pollux_styles = {'color': 'g'}

    >>> plot_airmass(target, observer, observe_time, style_kwargs=sirius_styles)
    >>> plot_airmass(other_target, observer, observe_time, style_kwargs=pollux_styles)

    >>> plt.legend(shadow=True, loc=2)
    >>> plt.show()

(`Source code`, `png`, `hires.png`, `pdf`, `svg`)

See the Matplotlib documentation for information on plotting styles in line plots.

#### Dark Theme Plots

By default, `astroplan` uses the Astropy style sheet for Matplotlib to generate plots with more pleasing settings than provided for by the matplotlib defaults. When using `astroplan` at night, you may prefer to make plots with dark backgrounds, rather than the default white background, to preserve your night vision. To do so, you may use the `astroplan` dark style sheet to produce dark-themed plots by using the style_sheet keyword argument in any plotting function:

    >>> from astroplan.plots import dark_style_sheet, plot_airmass
    >>> plot_airmass(target, observatory, time, style_sheet=dark_style_sheet)

(`Source code`)

#### Additional Options

You can also shade the background according to the darkness of the sky (light shading for 0 degree twilight, darker shading for -18 degree twilight) with the `brightness_shading` keyword, and display additional y-axis ticks on the right side of the axis with the altitudes in degrees using the `altitude_yaxis` keyword:

    >>> import matplotlib.pyplot as plt
    >>> from astropy.time import Time
    >>> from astroplan import FixedTarget, Observer
    >>> from astroplan.plots import plot_airmass

    >>> time = Time('2018-01-02 19:00')
    >>> target = FixedTarget.from_name('HD 189733')
    >>> apo = Observer.at_site('APO')
    >>> plot_airmass(target, apo, time, brightness_shading=True, altitude_yaxis=True)

(`Source code`)

Return to Top

## Sky Charts

Many users planning an observation run will want to see the positions of targets with respect to their local horizon, as well as the positions of familiar stars or other objects to act as guides.

`plot_sky` allows you to plot the positions of targets at a single instance or over some window of time. You make this plot the following way:

    >>> from astroplan.plots import plot_sky

    >>> plot_sky(target, observer, time)

Note

`plot_sky` currently produces polar plots in altitude/azimuth coordinates only. Plots are centered on the observer’s zenith.

See also

`astroplan.Observer.altaz`

### Making a plot for one instance in time

After constructing your `Observer` and `FixedTarget` objects, construct a time input using an array of length 1.

That is, either an `Time` object with an array containing one time value (e.g., `Time(['2000-1-1'])`) or an array containing one scalar `Time` object (e.g., `[Time('2000-1-1')]`).

Let’s say that you created `FixedTarget` objects for Polaris, Altair, Vega and Deneb. To plot a map of the sky:

    >>> import matplotlib.pyplot as plt
    >>> from astropy.time import Time
    >>> from astroplan.plots import plot_sky

    >>> observe_time = Time(['2000-03-15 15:30:00'])

    >>> polaris_style = {color': 'k'}
    >>> vega_style = {'color': 'g'}
    >>> deneb_style = {'color': 'r'}

    >>> plot_sky(polaris, observer, observe_time, style_kwargs=polaris_style)
    >>> plot_sky(altair, observer, observe_time)
    >>> plot_sky(vega, observer, observe_time, style_kwargs=vega_style)
    >>> plot_sky(deneb, observer, observe_time, style_kwargs=deneb_style)

    >>> plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5))
    >>> plt.show()

Note

Since `plot_sky` uses `scatter` (which gives the same color to different plots made on the same set of axes), you have to specify the color for each target via a style dictionary if you don’t want all targets to have the same color.

(`Source code`, `png`, `hires.png`, `pdf`, `svg`)

### Showing movement over time

If you want to see how your targets move over time, you need to explicitly specify every instance in time.

Say I want to know how Altair moves in the sky over a 9-hour period:

    >>> import numpy as np
    >>> import matplotlib.pyplot as plt
    >>> import astropy.units as u
    >>> from astroplan.plots import plot_sky

    >>> observe_time = Time('2000-03-15 17:00:00')
    >>> observe_time = observe_time + np.linspace(-4, 5, 10)*u.hour

    >>> plot_sky(altair, observer, observe_time)

    >>> plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5))
    >>> plt.show()

(`Source code`, `png`, `hires.png`, `pdf`, `svg`)

For more examples on how to populate time objects, see `Time` documentation, or Specifying a time window.

Note

Note that in the case of an object being under the horizon (or having negative altitude) at any of the times in your time input, `plot_sky` will warn you. Your object(s) will not show up on the plot for those particular times, but any positions above the horizon will still be plotted as normal.

### Customizing your sky plot

`astroplan` plots use Matplotlib defaults, so you can customize your plots in much the same way you tweak any Matplotlib plot.

#### Setting style options

The default marker for `plot_sky` is a circle and the default label (should you choose to display a legend) is the name contained in the `Target` object. You can change the marker, color, label and other plotting properties by setting the style_kwargs option, in the same way shown for the time-dependent plots.

One situation in which this is particularly useful is the plotting of guide positions, such as a few familiar stars or any body used in calibrating your telescope. You can also use this feature to set apart different types of targets (e.g., high-priority, candidates for observing run, etc.).

See the Matplotlib documentation for information on plotting styles in scatter plots.

#### Changing coordinate defaults

As seen in the above examples, the default position of North is at the top of the plot, and South at the bottom, with azimuth increasing counter-clockwise (CCW), putting East to the left, and West to the right.

You can’t change the position of North or South (either in the actual plotting of the data, or the labels), but you can “flip” East/West by changing the direction in which azimuth increases via the north_to_east_ccw option:

    >>> import matplotlib.pyplot as plt
    >>> from astroplan.plots import plot_sky

    >>> guide_style = {'marker': '*'}

    >>> plot_sky(polaris, observer, observe_time, snorth_to_east_ccw=False, style_kwargs=guide_style)
    >>> plot_sky(altair, observer, observe_time, north_to_east_ccw=False)

    >>> plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5))
    >>> plt.show()

(`Source code`, `png`, `hires.png`, `pdf`, `svg`)

Some observatories may need to offset or rotate the azimuth labels due to their particular telescope setup.

To do this, set az_label_offset equal to the number of degrees by which you wish to rotate the labels. By default, az_label_offset is set to 0 degrees. A positive offset is in the same direction as azimuth increase (see the north_to_east_ccw option):

    >>> import matplotlib.pyplot as plt
    >>> from astroplan.plots import plot_sky

    >>> guide_style = {'marker': '*'}

    >>> plot_sky(polaris, observer, observe_time, style_kwargs=guide_style, az_label_offset=180.0*u.deg)
    >>> plot_sky(altair, observer, observe_time, az_label_offset=180.0*u.deg)

    >>> plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5))
    >>> plt.show()

(`Source code`, `png`, `hires.png`, `pdf`, `svg`)

Note

The az_label_offset option does not rotate the actual positions on the plot, but simply the theta grid labels (which are drawn regardless of gridline presence). Since labels are drawn with every call to `plot_sky`, we recommend you use the same az_label_offset argument for every target on the same plot.

It is not advised that most users change this option, as it may appear that your alt/az data does not coincide with the definition of altazimuth (local horizon) coordinate system.

You can turn off the grid lines by setting the grid option to False:

    >>> import matplotlib.pyplot as plt
    >>> from astroplan.plots import plot_sky

    >>> guide_style = {'marker': '*'}

    >>> plot_sky(polaris, observer, observe_time, style_kwargs=guide_style, grid=False)
    >>> plot_sky(altair, observer, observe_time, grid=False)

    >>> plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5))
    >>> plt.show()

(`Source code`, `png`, `hires.png`, `pdf`, `svg`)

Note

Since grids are redrawn with every call to `plot_sky`, you must set `grid=False` for every target in the same plot.

#### Other tweaks

You can easily change other plot attributes by acting on the returned `matplotlib.axes.Axes` object or via `matplotlib.pyplot` calls (e.g., `plt.figure`, `plt.rc`, etc.).

For instance, you can increase the size of your plot and its font:

    >>> # Set the figure size/font before you issue the plotting command.
    >>> plt.figure(figsize=(8,6))
    >>> plt.rc('font', size=14)

    >>> plot_sky(polaris, observer, observe_time)
    >>> plot_sky(altair, observer, observe_time)

    >>> plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5))
    >>> plt.show()

    >>> # Change font size back to default once done plotting.
    >>> plt.rc('font', size=12)

Return to Top

#### Miscellaneous

The easiest way to reuse the `Axes` object that is the base of your plots is to just let `astroplan`’s plotting functions take care of it in the background. You do, however, have the option of explicitly passing in a named axis, assuming that you have created the appropriate type for the particular plot you want.

We can explicitly give a name to the `Axes` object returned by `plot_sky` when plotting Polaris and reuse it to plot Altair:

    >>> my_ax = plot_sky(polaris, observer, observe_time, style_kwargs=guide_style)
    >>> plot_sky(altair, observer, observe_time, my_ax)

We can also create a `Axes` object entirely outside of `plot_sky`, then pass it in:

    >>> my_ax = plt.gcf().add_subplot(projection='polar')
    >>> plot_sky(polaris, observer, observe_time, my_ax)

Passing in named `matplotlib.axes.Axes` objects comes in handy when you want to make multiple plots:

    >>> from astroplan.plots import plot_sky
    >>> import matplotlib.pyplot as plt

    >>> my_ax = plot_sky(polaris, observer, observe_time, style_kwargs=polaris_style)
    >>> plot_sky(altair, observer, observe_time, my_ax, style_kwargs=altair_style)
    >>> plt.legend(loc='center left', bbox_to_anchor=(1.3, 0.5))

    >>> # Note that this plt.show (or another action, such as saving a figure) is critical in maintaining two separate plots.
    >>> plt.show()

    >>> other_ax = plot_sky(vega, observer, observe_time, style_kwargs=vega_style)
    >>> plot_sky(deneb, observer, observe_time, other_ax, style_kwargs=deneb_style)
    >>> plt.legend(loc='center left', bbox_to_anchor=(1.25, 0.5))
    >>> plt.show()

(`Source code`, `png`, `hires.png`, `pdf`, `svg`)

(`png`, `hires.png`, `pdf`, `svg`)

Return to Top

## Finder Chart/Image

`astroplan` includes a function for generating quick finder images from Python, `plot_finder_image`, by querying for images from sky surveys centered on a `FixedTarget`. This function depends on astroquery (in addition to Matplotlib). In this example, we’ll quickly make a finder image centered on The Crab Nebula (M1):

    >>> from astroplan.plots import plot_finder_image
    >>> from astroplan import FixedTarget
    >>> import matplotlib.pyplot as plt

    >>> messier1 = FixedTarget.from_name("M1")
    >>> ax, hdu = plot_finder_image(messier1)
    >>> plt.show()

(`Source code`)

Return to Top