FITSFigure

class aplpy.aplpy.FITSFigure(data, hdu=0, figure=None, subplot=(1, 1, 1), downsample=False, north=False, convention=None, dimensions=[0, 1], slices=[], auto_refresh=True, **kwargs)[source]

Bases: aplpy.layers.Layers, aplpy.regions.Regions, aplpy.deprecated.Deprecated

A class for plotting FITS files.

Methods Summary

add_beam(*args, **kwargs) Add a beam to the current figure.
add_colorbar(*args, **kwargs) Add a colorbar to the current figure.
add_grid(*args, **kwargs) Add a coordinate to the current figure.
add_label(x, y, text[, relative, color, ...]) Add a text label.
add_scalebar(length, *args, **kwargs) Add a scalebar to the current figure.
close() Close the figure and free up the memory.
hide_colorscale()
hide_grayscale(*args, **kwargs)
pixel2world(xp, yp) Convert pixel to world coordinates.
recenter(x, y[, radius, width, height]) Center the image on a given position and with a given radius.
refresh([force]) Refresh the display.
remove_beam([beam_index]) Removes the beam from the current figure.
remove_colorbar() Removes the colorbar from the current figure.
remove_grid() Removes the grid from the current figure.
remove_scalebar() Removes the scalebar from the current figure.
save(filename[, dpi, transparent, ...]) Save the current figure to a file.
set_auto_refresh(refresh) Set whether the display should refresh after each method call.
set_nan_color(color) Set the color for NaN pixels.
set_system_latex(usetex) Set whether to use a real LaTeX installation or the built-in matplotlib LaTeX.
set_theme(theme) Set the axes, ticks, grid, and image colors to a certain style (experimental).
set_xaxis_coord_type(coord_type) Set the type of x coordinate.
set_yaxis_coord_type(coord_type) Set the type of y coordinate.
show_arrows(x, y, dx, dy[, width, ...]) Overlay arrows on the current plot.
show_circles(xw, yw, radius[, layer, zorder]) Overlay circles on the current plot.
show_colorscale([vmin, vmid, vmax, pmin, ...]) Show a colorscale image of the FITS file.
show_contour(data[, hdu, layer, levels, ...]) Overlay contours on the current plot.
show_ellipses(xw, yw, width, height[, ...]) Overlay ellipses on the current plot.
show_grayscale([vmin, vmid, vmax, pmin, ...]) Show a grayscale image of the FITS file.
show_lines(line_list[, layer, zorder]) Overlay lines on the current plot.
show_markers(xw, yw[, layer]) Overlay markers on the current plot.
show_polygons(polygon_list[, layer, zorder]) Overlay polygons on the current plot.
show_rectangles(xw, yw, width, height[, ...]) Overlay rectangles on the current plot.
show_rgb([filename, interpolation, ...]) Show a 3-color image instead of the FITS file data.
world2pixel(xw, yw) Convert world to pixel coordinates.

Methods Documentation

add_beam(*args, **kwargs)[source]

Add a beam to the current figure.

Once this method has been run, a beam attribute becomes available, and can be used to control the aspect of the beam:

>>> f = aplpy.FITSFigure(...)
>>> ...
>>> f.add_beam()
>>> f.beam.set_color('white')
>>> f.beam.set_hatch('+')
>>> ...

If more than one beam is added, the beam object becomes a list. In this case, to control the aspect of one of the beams, you will need tp specify the beam index:

>>> ...
>>> f.beam[2].set_hatch('/')
>>> ...
add_colorbar(*args, **kwargs)[source]

Add a colorbar to the current figure.

Once this method has been run, a colorbar attribute becomes available, and can be used to control the aspect of the colorbar:

>>> f = aplpy.FITSFigure(...)
>>> ...
>>> f.add_colorbar()
>>> f.colorbar.set_width(0.3)
>>> f.colorbar.set_location('top')
>>> ...
add_grid(*args, **kwargs)[source]

Add a coordinate to the current figure.

Once this method has been run, a grid attribute becomes available, and can be used to control the aspect of the grid:

>>> f = aplpy.FITSFigure(...)
>>> ...
>>> f.add_grid()
>>> f.grid.set_color('white')
>>> f.grid.set_alpha(0.5)
>>> ...
add_label(x, y, text, relative=False, color='black', family=None, style=None, variant=None, stretch=None, weight=None, size=None, fontproperties=None, horizontalalignment='center', verticalalignment='center', layer=None, **kwargs)[source]

Add a text label.

Parameters :

x, y : float

Coordinates of the text label

text : str

The label

relative : str, optional

Whether the coordinates are to be interpreted as world coordinates (e.g. RA/Dec or longitude/latitude), or coordinates relative to the axes (where 0.0 is left or bottom and 1.0 is right or top).

family : str, optional

The family of the font to use. This can either be a generic font family name, either ‘serif’, ‘sans-serif’, ‘cursive’, ‘fantasy’, or ‘monospace’, or a list of font names in decreasing order of priority.

style : str, optional

The font style. This can be ‘normal’, ‘italic’ or ‘oblique’.

variant : str, optional

The font variant. This can be ‘normal’ or ‘small-caps’

stretch : str or int or float, optional

The stretching (spacing between letters) for the font. This can either be a numeric value in the range 0-1000 or one of ‘ultra-condensed’, ‘extra-condensed’, ‘condensed’, ‘semi-condensed’, ‘normal’, ‘semi-expanded’, ‘expanded’, ‘extra-expanded’ or ‘ultra-expanded’.

weight : str or int or float, optional

The weight (or boldness) of the font. This can either be a numeric value in the range 0-1000 or one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’.

size : str or int or float, optional

The size of the font. This can either be a numeric value (e.g. 12), giving the size in points, or one of ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, or ‘xx-large’.

add_scalebar(length, *args, **kwargs)[source]

Add a scalebar to the current figure.

Once this method has been run, a scalebar attribute becomes available, and can be used to control the aspect of the scalebar:

>>> f = aplpy.FITSFigure(...)
>>> ...
>>> f.add_scalebar(0.01) # length has to be specified
>>> f.scalebar.set_label('100 AU')
>>> ...
close()[source]

Close the figure and free up the memory.

hide_colorscale()[source]
hide_grayscale(*args, **kwargs)[source]
pixel2world(xp, yp)[source]

Convert pixel to world coordinates.

Parameters :

xp : float or list or ndarray

x pixel coordinate

yp : float or list or ndarray

y pixel coordinate

Returns :

xw : float or list or ndarray

x world coordinate

yw : float or list or ndarray

y world coordinate

recenter(x, y, radius=None, width=None, height=None)[source]

Center the image on a given position and with a given radius.

Either the radius or width/heigh arguments should be specified.

Parameters :

x, y : float

Coordinates to center on

radius : float, optional

Radius of the region to view. This produces a square plot.

width : float, optional

Width of the region to view. This should be given in conjunction with the height argument.

height : float, optional

Height of the region to view. This should be given in conjunction with the width argument.

refresh(force=True)[source]

Refresh the display.

Parameters :

force : str, optional

If set to False, refresh() will only have an effect if auto refresh is on. If set to True, the display will be refreshed whatever the auto refresh setting is set to. The default is True.

remove_beam(beam_index=None)[source]

Removes the beam from the current figure.

If more than one beam is present, the index of the beam should be specified using beam_index=

remove_colorbar()[source]

Removes the colorbar from the current figure.

remove_grid()[source]

Removes the grid from the current figure.

remove_scalebar()[source]

Removes the scalebar from the current figure.

save(filename, dpi=None, transparent=False, adjust_bbox=True, max_dpi=300, format=None)[source]

Save the current figure to a file.

Parameters :

filename : str or fileobj

The name of the file to save the plot to. This can be for example a PS, EPS, PDF, PNG, JPEG, or SVG file. Note that it is also possible to pass file-like object.

dpi : float, optional

The output resolution, in dots per inch. If the output file is a vector graphics format (such as PS, EPS, PDF or SVG) only the image itself will be rasterized. If the output is a PS or EPS file and no dpi is specified, the dpi is automatically calculated to match the resolution of the image. If this value is larger than max_dpi, then dpi is set to max_dpi.

transparent : str, optional

Whether to preserve transparency

adjust_bbox : str, optional

Auto-adjust the bounding box for the output

max_dpi : float, optional

The maximum resolution to output images at. If no maximum is wanted, enter None or 0.

format : str, optional

By default, APLpy tries to guess the file format based on the file extension, but the format can also be specified explicitly. Should be one of ‘eps’, ‘ps’, ‘pdf’, ‘svg’, ‘png’.

set_auto_refresh(refresh)[source]

Set whether the display should refresh after each method call.

Parameters :

refresh : str

Whether to refresh the display every time a FITSFigure method is called. The default is True. If set to false, the display can be refreshed manually using the refresh() method

set_nan_color(color)[source]

Set the color for NaN pixels.

Parameters :

color : str

This can be any valid matplotlib color

set_system_latex(usetex)[source]

Set whether to use a real LaTeX installation or the built-in matplotlib LaTeX.

Parameters :

usetex : str

Whether to use a real LaTex installation (True) or the built-in matplotlib LaTeX (False). Note that if the former is chosen, an installation of LaTex is required.

set_theme(theme)[source]

Set the axes, ticks, grid, and image colors to a certain style (experimental).

Parameters :

theme : str

The theme to use. At the moment, this can be ‘pretty’ (for viewing on-screen) and ‘publication’ (which makes the ticks and grid black, and displays the image in inverted grayscale)

set_xaxis_coord_type(coord_type)[source]

Set the type of x coordinate.

Options are:

  • scalar: treat the values are normal decimal scalar values
  • longitude: treat the values as a longitude in the 0 to 360 range
  • latitude: treat the values as a latitude in the -90 to 90 range
set_yaxis_coord_type(coord_type)[source]

Set the type of y coordinate.

Options are:

  • scalar: treat the values are normal decimal scalar values
  • longitude: treat the values as a longitude in the 0 to 360 range
  • latitude: treat the values as a latitude in the -90 to 90 range
show_arrows(x, y, dx, dy, width='auto', head_width='auto', head_length='auto', layer=False, zorder=None, **kwargs)[source]

Overlay arrows on the current plot.

Parameters :

x, y, dx, dy : float or list or ndarray

Origin and displacement of the arrows in world coordinates. These can either be scalars to plot a single arrow, or lists or arrays to plot multiple arrows.

width : float, optional

The width of the arrow body, in pixels (default: 2% of the arrow length)

head_width : float, optional

The width of the arrow head, in pixels (default: 5% of the arrow length)

head_length : float, optional

The length of the arrow head, in pixels (default: 5% of the arrow length)

layer : str, optional

The name of the arrow(s) layer. This is useful for giving custom names to layers (instead of line_set_n) and for replacing existing layers.

kwargs :

Additional keyword arguments (such as color, offsets, linestyle, or linewidth) are passed to Matplotlib FancyArrow class, and can be used to control the appearance of the arrows.

show_circles(xw, yw, radius, layer=False, zorder=None, **kwargs)[source]

Overlay circles on the current plot.

Parameters :

xw : list or ndarray

The x postions of the circles (in world coordinates)

yw : list or ndarray

The y positions of the circles (in world coordinates)

radius : int or float or list or ndarray

The radii of the circles (in world coordinates)

layer : str, optional

The name of the circle layer. This is useful for giving custom names to layers (instead of circle_set_n) and for replacing existing layers.

kwargs :

Additional keyword arguments (such as facecolor, edgecolor, alpha, or linewidth) are passed to Matplotlib Circle class, and can be used to control the appearance of the circles.

show_colorscale(vmin=None, vmid=None, vmax=None, pmin=0.25, pmax=99.75, stretch='linear', exponent=2, cmap='default', smooth=None, kernel='gauss', aspect='equal', interpolation='nearest')[source]

Show a colorscale image of the FITS file.

Parameters :

vmin : None or float, optional

Minimum pixel value to use for the colorscale. If set to None, the minimum pixel value is determined using pmin (default).

vmax : None or float, optional

Maximum pixel value to use for the colorscale. If set to None, the maximum pixel value is determined using pmax (default).

pmin : float, optional

Percentile value used to determine the minimum pixel value to use for the colorscale if vmin is set to None. The default value is 0.25%.

pmax : float, optional

Percentile value used to determine the maximum pixel value to use for the colorscale if vmax is set to None. The default value is 99.75%.

stretch : { ‘linear’, ‘log’, ‘sqrt’, ‘arcsinh’, ‘power’ }, optional

The stretch function to use

vmid : None or float, optional

Baseline value used for the log and arcsinh stretches. If set to None, this is set to zero for log stretches and to vmin - (vmax - vmin) / 30. for arcsinh stretches

exponent : float, optional

If stretch is set to ‘power’, this is the exponent to use

cmap : str, optional

The name of the colormap to use

smooth : int or tuple, optional

Default smoothing scale is 3 pixels across. User can define whether they want an NxN kernel (integer), or NxM kernel (tuple). This argument corresponds to the ‘gauss’ and ‘box’ smoothing kernels.

kernel : { ‘gauss’, ‘box’, numpy.array }, optional

Default kernel used for smoothing is ‘gauss’. The user can specify if they would prefer ‘gauss’, ‘box’, or a custom kernel. All kernels are normalized to ensure flux retention.

aspect : { ‘auto’, ‘equal’ }, optional

Whether to change the aspect ratio of the image to match that of the axes (‘auto’) or to change the aspect ratio of the axes to match that of the data (‘equal’; default)

interpolation : str, optional

The type of interpolation to use for the image. The default is ‘nearest’. Other options include ‘none’ (no interpolation, meaning that if exported to a postscript file, the colorscale will be output at native resolution irrespective of the dpi setting), ‘bilinear’, ‘bicubic’, and many more (see the matplotlib documentation for imshow).

show_contour(data, hdu=0, layer=None, levels=5, filled=False, cmap=None, colors=None, returnlevels=False, convention=None, dimensions=[0, 1], slices=[], smooth=None, kernel='gauss', overlap=False, **kwargs)[source]

Overlay contours on the current plot.

Parameters :

data : see below

The FITS file to plot contours for. The following data types can be passed:

string astropy.io.fits.PrimaryHDU astropy.io.fits.ImageHDU pyfits.PrimaryHDU pyfits.ImageHDU astropy.wcs.WCS np.ndarray

hdu : int, optional

By default, the image in the primary HDU is read in. If a different HDU is required, use this argument.

layer : str, optional

The name of the contour layer. This is useful for giving custom names to layers (instead of contour_set_n) and for replacing existing layers.

levels : int or list, optional

This can either be the number of contour levels to compute (if an integer is provided) or the actual list of contours to show (if a list of floats is provided)

filled : str, optional

Whether to show filled or line contours

cmap : str, optional

The colormap to use for the contours

colors : str or tuple, optional

If a single string is provided, all contour levels will be shown in this color. If a tuple of strings is provided, each contour will be colored according to the corresponding tuple element.

returnlevels : str, optional

Whether to return the list of contours to the caller.

convention : str, optional

This is used in cases where a FITS header can be interpreted in multiple ways. For example, for files with a -CAR projection and CRVAL2=0, this can be set to ‘wells’ or ‘calabretta’ to choose the appropriate convention.

dimensions : tuple or list, optional

The index of the axes to use if the data has more than three dimensions.

slices : tuple or list, optional

If a FITS file with more than two dimensions is specified, then these are the slices to extract. If all extra dimensions only have size 1, then this is not required.

smooth : int or tuple, optional

Default smoothing scale is 3 pixels across. User can define whether they want an NxN kernel (integer), or NxM kernel (tuple). This argument corresponds to the ‘gauss’ and ‘box’ smoothing kernels.

kernel : { ‘gauss’ , ‘box’ , numpy.array }, optional

Default kernel used for smoothing is ‘gauss’. The user can specify if they would prefer ‘gauss’, ‘box’, or a custom kernel. All kernels are normalized to ensure flux retention.

overlap str, optional :

Whether to include only contours that overlap with the image area. This significantly speeds up the drawing of contours and reduces file size when using a file for the contours covering a much larger area than the image.

kwargs :

Additional keyword arguments (such as alpha, linewidths, or linestyles) will be passed on directly to Matplotlib’s contour() or contourf() methods. For more information on these additional arguments, see the Optional keyword arguments sections in the documentation for those methods.

show_ellipses(xw, yw, width, height, angle=0, layer=False, zorder=None, **kwargs)[source]

Overlay ellipses on the current plot.

Parameters :

xw : list or ndarray

The x postions of the ellipses (in world coordinates)

yw : list or ndarray

The y positions of the ellipses (in world coordinates)

width : int or float or list or ndarray

The width of the ellipse (in world coordinates)

height : int or float or list or ndarray

The height of the ellipse (in world coordinates)

angle : int or float or list or ndarray, optional

rotation in degrees (anti-clockwise). Default angle is 0.0.

layer : str, optional

The name of the ellipse layer. This is useful for giving custom names to layers (instead of ellipse_set_n) and for replacing existing layers.

kwargs :

Additional keyword arguments (such as facecolor, edgecolor, alpha, or linewidth) are passed to Matplotlib Ellipse class, and can be used to control the appearance of the ellipses.

show_grayscale(vmin=None, vmid=None, vmax=None, pmin=0.25, pmax=99.75, stretch='linear', exponent=2, invert='default', smooth=None, kernel='gauss', aspect='equal', interpolation='nearest')[source]

Show a grayscale image of the FITS file.

Parameters :

vmin : None or float, optional

Minimum pixel value to use for the grayscale. If set to None, the minimum pixel value is determined using pmin (default).

vmax : None or float, optional

Maximum pixel value to use for the grayscale. If set to None, the maximum pixel value is determined using pmax (default).

pmin : float, optional

Percentile value used to determine the minimum pixel value to use for the grayscale if vmin is set to None. The default value is 0.25%.

pmax : float, optional

Percentile value used to determine the maximum pixel value to use for the grayscale if vmax is set to None. The default value is 99.75%.

stretch : { ‘linear’, ‘log’, ‘sqrt’, ‘arcsinh’, ‘power’ }, optional

The stretch function to use

vmid : None or float, optional

Baseline value used for the log and arcsinh stretches. If set to None, this is set to zero for log stretches and to vmin - (vmax - vmin) / 30. for arcsinh stretches

exponent : float, optional

If stretch is set to ‘power’, this is the exponent to use

invert : str, optional

Whether to invert the grayscale or not. The default is False, unless set_theme is used, in which case the default depends on the theme.

smooth : int or tuple, optional

Default smoothing scale is 3 pixels across. User can define whether they want an NxN kernel (integer), or NxM kernel (tuple). This argument corresponds to the ‘gauss’ and ‘box’ smoothing kernels.

kernel : { ‘gauss’, ‘box’, numpy.array }, optional

Default kernel used for smoothing is ‘gauss’. The user can specify if they would prefer ‘gauss’, ‘box’, or a custom kernel. All kernels are normalized to ensure flux retention.

aspect : { ‘auto’, ‘equal’ }, optional

Whether to change the aspect ratio of the image to match that of the axes (‘auto’) or to change the aspect ratio of the axes to match that of the data (‘equal’; default)

interpolation : str, optional

The type of interpolation to use for the image. The default is ‘nearest’. Other options include ‘none’ (no interpolation, meaning that if exported to a postscript file, the grayscale will be output at native resolution irrespective of the dpi setting), ‘bilinear’, ‘bicubic’, and many more (see the matplotlib documentation for imshow).

show_lines(line_list, layer=False, zorder=None, **kwargs)[source]

Overlay lines on the current plot.

Parameters :

line_list : list

A list of one or more 2xN numpy arrays which contain the [x, y] positions of the vertices in world coordinates.

layer : str, optional

The name of the line(s) layer. This is useful for giving custom names to layers (instead of line_set_n) and for replacing existing layers.

kwargs :

Additional keyword arguments (such as color, offsets, linestyle, or linewidth) are passed to Matplotlib LineCollection class, and can be used to control the appearance of the lines.

show_markers(xw, yw, layer=False, **kwargs)[source]

Overlay markers on the current plot.

Parameters :

xw : list or ndarray

The x postions of the markers (in world coordinates)

yw : list or ndarray

The y positions of the markers (in world coordinates)

layer : str, optional

The name of the scatter layer. This is useful for giving custom names to layers (instead of marker_set_n) and for replacing existing layers.

kwargs :

Additional keyword arguments (such as marker, facecolor, edgecolor, alpha, or linewidth) will be passed on directly to Matplotlib’s scatter() method (in particular, have a look at the Optional keyword arguments in the documentation for that method).

show_polygons(polygon_list, layer=False, zorder=None, **kwargs)[source]

Overlay polygons on the current plot.

Parameters :

polygon_list : list or tuple

A list of one or more 2xN or Nx2 Numpy arrays which contain the [x, y] positions of the vertices in world coordinates. Note that N should be greater than 2.

layer : str, optional

The name of the circle layer. This is useful for giving custom names to layers (instead of circle_set_n) and for replacing existing layers.

kwargs :

Additional keyword arguments (such as facecolor, edgecolor, alpha, or linewidth) are passed to Matplotlib Polygon class, and can be used to control the appearance of the polygons.

show_rectangles(xw, yw, width, height, layer=False, zorder=None, **kwargs)[source]

Overlay rectangles on the current plot.

Parameters :

xw : list or ndarray

The x postions of the rectangles (in world coordinates)

yw : list or ndarray

The y positions of the rectangles (in world coordinates)

width : int or float or list or ndarray

The width of the rectangle (in world coordinates)

height : int or float or list or ndarray

The height of the rectangle (in world coordinates)

layer : str, optional

The name of the rectangle layer. This is useful for giving custom names to layers (instead of rectangle_set_n) and for replacing existing layers.

kwargs :

Additional keyword arguments (such as facecolor, edgecolor, alpha, or linewidth) are passed to Matplotlib Rectangle class, and can be used to control the appearance of the rectangles.

show_rgb(filename=None, interpolation='nearest', vertical_flip=False, horizontal_flip=False, flip=False)[source]

Show a 3-color image instead of the FITS file data.

Parameters :

filename, optional :

The 3-color image should have exactly the same dimensions as the FITS file, and will be shown with exactly the same projection. If FITSFigure was initialized with an AVM-tagged RGB image, the filename is not needed here.

vertical_flip : str, optional

Whether to vertically flip the RGB image

horizontal_flip : str, optional

Whether to horizontally flip the RGB image

world2pixel(xw, yw)[source]

Convert world to pixel coordinates.

Parameters :

xw : float or list or ndarray

x world coordinate

yw : float or list or ndarray

y world coordinate

Returns :

xp : float or list or ndarray

x pixel coordinate

yp : float or list or ndarray

y pixel coordinate

Page Contents