GenericMap

class sunpy.map.GenericMap(data, header, plot_settings=None, **kwargs)[source] [edit on github]

Bases: astropy.nddata.NDData

A Generic spatially-aware 2D data array

Parameters:
  • data (ndarray, list) – A 2d list or ndarray containing the map data
  • meta (dict) – A dictionary of the original image header tags

Examples

>>> import sunpy.map
>>> import sunpy.data.sample
>>> aia = sunpy.map.Map(sunpy.data.sample.AIA_171_IMAGE)
>>> aia   
SunPy AIAMap
---------
Observatory:         SDO
Instrument:  AIA 3
Detector:    AIA
Measurement:         171.0 Angstrom
Wavelength:  171.0 Angstrom
Obs Date:    2011-03-19 10:54:00
dt:          1.999601 s
Dimension:   [ 1024.  1024.] pix
scale:               [ 2.4  2.4] arcsec / pix

array([[ 0.3125, -0.0625, -0.125 , ...,  0.625 , -0.625 ,  0.    ],
       [ 1.    ,  0.1875, -0.8125, ...,  0.625 , -0.625 ,  0.    ],
       [-1.1875,  0.375 , -0.5   , ..., -0.125 , -0.625 , -1.1875],
       ...,
       [-0.625 ,  0.0625, -0.3125, ...,  0.125 ,  0.125 ,  0.125 ],
       [ 0.5625,  0.0625,  0.5625, ..., -0.0625, -0.0625,  0.    ],
       [ 0.5   , -0.125 ,  0.4375, ...,  0.6875,  0.6875,  0.6875]])
>>> aia.spatial_units
SpatialPair(axis1=Unit("arcsec"), axis2=Unit("arcsec"))
>>> aia.peek()   

Notes

A number of the properties of this class are returned as two-value named tuples that can either be indexed by position ([0] or [1]) or be accessed by the names (.x and .y) or (.axis1 and .axis2). Things that refer to pixel axes use the .x, .y convention, where x and y refer to the FITS axes (x for columns y for rows). Spatial axes use .axis1 and .axis2 which correspond to the first and second axes in the header. axis1 corresponds to the coordinate axis for x and axis2 corresponds to y.

This class makes some assumptions about the WCS information contained in the meta data. The first and most extensive assumption is that it is FITS-like WCS information as defined in the FITS WCS papers.

Within this scope it also makes some other assumptions.

  • In the case of APIS convention headers where the CROTAi/j arguments are provided it assumes that these can be converted to the standard PCi_j notation using equations 32 in Thompson (2006).
  • If a CDi_j matrix is provided it is assumed that it can be converted to a PCi_j matrix and CDELT keywords as described in Greisen & Calabretta (2002)
  • The ‘standard’ FITS keywords that are used by this class are the PCi_j matrix and CDELT, along with the other keywords specified in the WCS papers. All subclasses of this class must convert their header information to this formalism. The CROTA to PCi_j conversion is done in this class.

Warning

This class currently assumes that a header with the CDi_j matrix information also includes the CDELT keywords, without these keywords this class will not process the WCS. Also the rotation_matrix does not work if the CDELT1 and CDELT2 keywords are exactly equal. Also, if a file with more than two dimensions is feed into the class, only the first two dimensions (NAXIS1, NAXIS2) will be loaded and the rest will be discarded.

Attributes Summary

bottom_left_coord The physical coordinate for the bottom left [0,0] pixel.
carrington_longitude Carrington longitude (crln_obs)
center Return a coordinate object for the center pixel of the array.
coordinate_frame An astropy.coordinates.BaseFrame instance created from the coordinate information for this Map.
coordinate_system Coordinate system used for x and y axes (ctype1/2)
date Image observation time
detector Detector name
dimensions The dimensions of the array (x axis first, y axis second).
dsun The observer distance from the Sun.
dtype The numpy.dtype of the array of the map.
exposure_time Exposure time of the image in seconds.
heliographic_latitude Heliographic latitude
heliographic_longitude Heliographic longitude
instrument Instrument name
latex_name LaTeX formatted description of the Map.
measurement Measurement name, defaults to the wavelength of image
name Human-readable description of the Map.
ndim The value of numpy.ndarray.ndim of the data array of the map.
nickname An abbreviated human-readable description of the map-type; part of
observatory Observatory or Telescope name
observer_coordinate The Heliographic Stonyhurst Coordinate of the observer.
processing_level Returns the FITS processing level if present.
reference_coordinate Reference point WCS axes in data units (i.e.
reference_pixel Reference point axes in pixels (i.e.
rotation_matrix Matrix describing the rotation required to align solar North with the top of the image.
rsun_meters Radius of the sun in meters
rsun_obs Radius of the Sun.
scale Image scale along the x and y axes in units/pixel (i.e.
shifted_value The total shift applied to the reference coordinate by past applications of shift.
size The number of pixels in the array of the map.
spatial_units Image coordinate units along the x and y axes (i.e.
top_right_coord The physical coordinate for the top left pixel.
wavelength wavelength of the observation
wcs The WCS property of the map.
xrange

Deprecated since version 0.8.

yrange

Deprecated since version 0.8.

Methods Summary

data_to_pixel(coordinate[, origin])

Deprecated since version 0.8.0.

draw_contours(levels[, axes]) Draw contours of the data
draw_grid([axes, grid_spacing]) Draws a coordinate overlay on the plot in the Heliographic Stonyhurst coordinate system.
draw_limb([axes]) Draws a circle representing the solar limb
draw_rectangle(bottom_left, width, height[, …]) Draw a rectangle defined in world coordinates on the plot.
max(*args, **kwargs) Calculate the maximum value of the data array.
mean(*args, **kwargs) Calculate the mean of the data array.
min(*args, **kwargs) Calculate the minimum value of the data array.
peek([draw_limb, draw_grid, colorbar, …]) Displays the map in a new figure
pixel_to_data(x, y[, origin])

Deprecated since version 0.8.0.

pixel_to_world(x, y[, origin]) Convert a pixel coordinate to a data (world) coordinate by using wcs_pix2world.
plot([annotate, axes, title]) Plots the map object using matplotlib, in a method equivalent to plt.imshow() using nearest neighbour interpolation.
resample(dimensions[, method]) Returns a new Map that has been resampled up or down
rotate([angle, rmatrix, order, scale, …]) Returns a new rotated and rescaled map.
save(filepath[, filetype]) Saves the SunPy Map object to a file.
shift(axis1, axis2) Returns a map shifted by a specified amount to, for example, correct for a bad map location.
std(*args, **kwargs) Calculate the standard deviation of the data array.
submap(bottom_left[, top_right]) Returns a submap of the map defined by the rectangle given by the [bottom_left, top_right] coordinates.
superpixel(dimensions[, offset, func]) Returns a new map consisting of superpixels formed by applying ‘func’ to the original map data.
world_to_pixel(coordinate[, origin]) Convert a world (data) coordinate to a pixel coordinate by using wcs_world2pix.

Attributes Documentation

bottom_left_coord

The physical coordinate for the bottom left [0,0] pixel.

carrington_longitude

Carrington longitude (crln_obs)

center

Return a coordinate object for the center pixel of the array.

coordinate_frame

An astropy.coordinates.BaseFrame instance created from the coordinate information for this Map.

coordinate_system

Coordinate system used for x and y axes (ctype1/2)

date

Image observation time

detector

Detector name

dimensions

The dimensions of the array (x axis first, y axis second).

dsun

The observer distance from the Sun.

dtype

The numpy.dtype of the array of the map.

exposure_time

Exposure time of the image in seconds.

heliographic_latitude

Heliographic latitude

heliographic_longitude

Heliographic longitude

instrument

Instrument name

latex_name

LaTeX formatted description of the Map.

measurement

Measurement name, defaults to the wavelength of image

name

Human-readable description of the Map.

ndim

The value of numpy.ndarray.ndim of the data array of the map.

nickname

An abbreviated human-readable description of the map-type; part of the Helioviewer data model

observatory

Observatory or Telescope name

observer_coordinate

The Heliographic Stonyhurst Coordinate of the observer.

processing_level

Returns the FITS processing level if present.

reference_coordinate

Reference point WCS axes in data units (i.e. crval1, crval2). This value includes a shift if one is set.

reference_pixel

Reference point axes in pixels (i.e. crpix1, crpix2)

rotation_matrix

Matrix describing the rotation required to align solar North with the top of the image.

rsun_meters

Radius of the sun in meters

rsun_obs

Radius of the Sun.

scale

Image scale along the x and y axes in units/pixel (i.e. cdelt1, cdelt2)

shifted_value

The total shift applied to the reference coordinate by past applications of shift.

size

The number of pixels in the array of the map.

spatial_units

Image coordinate units along the x and y axes (i.e. cunit1, cunit2).

top_right_coord

The physical coordinate for the top left pixel.

wavelength

wavelength of the observation

wcs

The WCS property of the map.

xrange

Deprecated since version 0.8: This property is only valid for non-rotated WCS

Return the X range of the image from edge to edge.

yrange

Deprecated since version 0.8: This property is only valid for non-rotated WCS

Return the Y range of the image from edge to edge.

Methods Documentation

data_to_pixel(coordinate, origin=0)[source] [edit on github]

Deprecated since version 0.8.0: The data_to_pixel function is deprecated and may be removed in a future version. Use sunpy.map.GenericMap.world_to_pixel instead.

See world_to_pixel

draw_contours(levels, axes=None, **contour_args)[source] [edit on github]

Draw contours of the data

Parameters:
  • levels (Quantity) – A list of numbers indicating the level curves to draw given in percent.
  • axes (matplotlib.axes.Axes) – The axes on which to plot the rectangle, defaults to the current axes.
Returns:

cs (list) – The QuadContourSet object, after it has been added to axes.

Notes

Extra keyword arguments to this function are passed through to the contour function.

draw_grid(axes=None, grid_spacing=<Quantity 15.0 deg>, **kwargs)[source] [edit on github]

Draws a coordinate overlay on the plot in the Heliographic Stonyhurst coordinate system.

To overlay other coordinate systems see the WCSAxes Documentation

Parameters:
  • axes (axes or None) –
  • to plot limb on or None to use current axes. (Axes) –
  • grid_spacing (Quantity) – Spacing for longitude and latitude grid, if length two it specifies (lon, lat) spacing.
Returns:

overlay (CoordinatesMap) – The wcsaxes coordinate overlay instance.

Notes

Keyword arguments are passed onto the sunpy.visualization.wcsaxes_compat.wcsaxes_heliographic_overlay function.

draw_limb(axes=None, **kwargs)[source] [edit on github]

Draws a circle representing the solar limb

Parameters:axes (axes or None) – Axes to plot limb on or None to use current axes.
Returns:circ (list) – A list containing the Circle object that has been added to the axes.

Notes

Keyword arguments are passed onto matplotlib.patches.Circle.

draw_rectangle(bottom_left, width, height, axes=None, **kwargs)[source] [edit on github]

Draw a rectangle defined in world coordinates on the plot.

Parameters:
Returns:

rect (list) – A list containing the Rectangle object, after it has been added to axes.

Notes

Extra keyword arguments to this function are passed through to the Rectangle instance.

max(*args, **kwargs)[source] [edit on github]

Calculate the maximum value of the data array.

mean(*args, **kwargs)[source] [edit on github]

Calculate the mean of the data array.

min(*args, **kwargs)[source] [edit on github]

Calculate the minimum value of the data array.

peek(draw_limb=False, draw_grid=False, colorbar=True, basic_plot=False, **matplot_args)[source] [edit on github]

Displays the map in a new figure

Parameters:
  • draw_limb (bool) – Whether the solar limb should be plotted.
  • draw_grid (bool or Quantity) – Whether solar meridians and parallels are plotted. If Quantity then sets degree difference between parallels and meridians.
  • gamma (float) – Gamma value to use for the color map
  • colorbar (bool) – Whether to display a colorbar next to the plot
  • basic_plot (bool) – If true, the data is plotted by itself at it’s natural scale; no title, labels, or axes are shown.
  • **matplot_args (dict) – Matplotlib Any additional imshow arguments that should be used when plotting.
pixel_to_data(x, y, origin=0)[source] [edit on github]

Deprecated since version 0.8.0: The pixel_to_data function is deprecated and may be removed in a future version. Use sunpy.map.GenericMap.pixel_to_world instead.

See pixel_to_world

pixel_to_world(x, y, origin=0)[source] [edit on github]

Convert a pixel coordinate to a data (world) coordinate by using wcs_pix2world.

Parameters:
  • x (Quantity) – Pixel coordinate of the CTYPE1 axis. (Normally solar-x).
  • y (Quantity) – Pixel coordinate of the CTYPE2 axis. (Normally solar-y).
  • origin (int) – Origin of the top-left corner. i.e. count from 0 or 1. Normally, origin should be 0 when passing numpy indices, or 1 if passing values from FITS header or map attributes. See wcs_pix2world for more information.
Returns:

coord (astropy.coordinates.SkyCoord) – A coordinate object representing the output coordinate.

plot(annotate=True, axes=None, title=True, **imshow_kwargs)[source] [edit on github]

Plots the map object using matplotlib, in a method equivalent to plt.imshow() using nearest neighbour interpolation.

Parameters:
  • annotate (bool) – If True, the data is plotted at it’s natural scale; with title and axis labels.
  • axes (axes or None) – If provided the image will be plotted on the given axes. Else the current matplotlib axes will be used.
  • **imshow_kwargs (dict) – Any additional imshow arguments that should be used when plotting.

Examples

>>> # Simple Plot with color bar
>>> aia.plot()   
>>> plt.colorbar()   
>>> # Add a limb line and grid
>>> aia.plot()   
>>> aia.draw_limb()   
>>> aia.draw_grid()   
resample(dimensions, method='linear')[source] [edit on github]

Returns a new Map that has been resampled up or down

Arbitrary resampling of the Map to new dimension sizes.

Uses the same parameters and creates the same co-ordinate lookup points as IDL’’s congrid routine, which apparently originally came from a VAX/VMS routine of the same name.

Parameters:
  • dimensions (Quantity) – Pixel dimensions that new Map should have. Note: the first argument corresponds to the ‘x’ axis and the second argument corresponds to the ‘y’ axis.
  • method ({'neighbor' | 'nearest' | 'linear' | 'spline'}) –
    Method to use for resampling interpolation.
    • neighbor - Closest value from original data
    • nearest and linear - Uses n x 1-D interpolations using scipy.interpolate.interp1d
    • spline - Uses ndimage.map_coordinates
Returns:

out (GenericMap or subclass) – A new Map which has been resampled to the desired dimensions.

References

rotate(angle=None, rmatrix=None, order=4, scale=1.0, recenter=False, missing=0.0, use_scipy=False)[source] [edit on github]

Returns a new rotated and rescaled map.

Specify either a rotation angle or a rotation matrix, but not both. If neither an angle or a rotation matrix are specified, the map will be rotated by the rotation angle in the metadata.

The map will be rotated around the reference coordinate defined in the meta data.

This method also updates the rotation_matrix attribute and any appropriate header data so that they correctly describe the new map.

Parameters:
  • angle (Quantity) – The angle (degrees) to rotate counterclockwise.
  • rmatrix (2x2) – Linear transformation rotation matrix.
  • order (int 0-5) – Interpolation order to be used. When using scikit-image this parameter is passed into skimage.transform.warp() (e.g., 4 corresponds to bi-quartic interpolation). When using scipy it is passed into scipy.ndimage.interpolation.affine_transform() where it controls the order of the spline. Faster performance may be obtained at the cost of accuracy by using lower values. Default: 4
  • scale (float) – A scale factor for the image, default is no scaling
  • recenter (bool) – If True, position the axis of rotation at the center of the new map Default: False
  • missing (float) – The numerical value to fill any missing points after rotation. Default: 0.0
  • use_scipy (bool) – If True, forces the rotation to use scipy.ndimage.interpolation.affine_transform(), otherwise it uses the skimage.transform.warp(). Default: False, unless scikit-image can’t be imported
Returns:

out (GenericMap or subclass) – A new Map instance containing the rotated and rescaled data of the original map.

See also

sunpy.image.transform.affine_transform()
The routine this method calls

for()

Notes

This function will remove old CROTA keywords from the header. This function will also convert a CDi_j matrix to a PCi_j matrix.

See sunpy.image.transform.affine_transform() for details on the transformations, situations when the underlying data is modified prior to rotation, and differences from IDL’s rot().

save(filepath, filetype='auto', **kwargs)[source] [edit on github]

Saves the SunPy Map object to a file.

Currently SunPy can only save files in the FITS format. In the future support will be added for saving to other formats.

Parameters:
  • filepath (str) – Location to save file to.
  • filetype (str) – ‘auto’ or any supported file extension
shift(axis1, axis2)[source] [edit on github]

Returns a map shifted by a specified amount to, for example, correct for a bad map location. These values are applied directly to the reference_coordinate. To check how much shift has already been applied see shifted_value

Parameters:
  • axis1 (Quantity) – The shift to apply to the Longitude (solar-x) coordinate.
  • axis2 (Quantity) – The shift to apply to the Latitude (solar-y) coordinate
Returns:

out (GenericMap or subclass) – A new shifted Map.

std(*args, **kwargs)[source] [edit on github]

Calculate the standard deviation of the data array.

submap(bottom_left, top_right=None)[source] [edit on github]

Returns a submap of the map defined by the rectangle given by the [bottom_left, top_right] coordinates.

Parameters:
  • bottom_left (astropy.units.Quantity or SkyCoord) – The bottom_left coordinate of the rectangle. If a SkyCoord it can have shape (2,) and also define top_right. If specifying pixel coordinates it must be given as an Quantity object with units of pixel.
  • top_right (astropy.units.Quantity or SkyCoord) – The top_right coordinate of the rectangle. Can only be omitted if bottom_left has shape (2,).
Returns:

out (GenericMap or subclass) – A new map instance is returned representing to specified sub-region

Examples

>>> import astropy.units as u
>>> import sunpy.map
>>> import sunpy.data.sample
>>> aia = sunpy.map.Map(sunpy.data.sample.AIA_171_IMAGE)
>>> bl = SkyCoord(-300*u.arcsec, -300*u.arcsec, frame=aia.coordinate_frame)
>>> tr = SkyCoord(500*u.arcsec, 500*u.arcsec, frame=aia.coordinate_frame
>>> aia.submap(bl, tr)   
SunPy Map
---------
Observatory:             SDO
Instrument:              AIA 3
Detector:                AIA
Measurement:             171.0 Angstrom
Wavelength:              171.0 Angstrom
Observation Date:        2011-03-19 10:54:00
Exposure Time:           1.999601 s
Dimension:               [ 333.  333.] pix
Coordinate System:       helioprojective
Scale:                   [ 2.4  2.4] arcsec / pix
Reference Pixel:         [ 125.5  125.5] pix
Reference Coord:         [ 0.  0.] arcsec

array([[ 365.625 ,  438.1875,  395.1875, ...,  201.375 ,  204.4375,  216.    ],
    [ 386.125 ,  389.5   ,  370.3125, ...,  207.3125,  202.1875,  196.75  ],
    [ 380.75  ,  342.875 ,  320.875 , ...,  187.5   ,  196.9375,
        178.875 ],
    ...,
    [ 225.3125,  219.1875,  211.1875, ...,  359.8125,  324.5625,
        305.375 ],
    [ 228.625 ,  228.8125,  225.8125, ...,  358.5   ,  318.    ,
        297.1875],
    [ 220.6875,  221.125 ,  209.625 , ...,  390.4375,  329.375 ,
        302.3125]])
>>> aia.submap([0,0]*u.pixel, [5,5]*u.pixel)   
SunPy Map
---------
Observatory:             SDO
Instrument:              AIA 3
Detector:                AIA
Measurement:             171.0 Angstrom
Wavelength:              171.0 Angstrom
Observation Date:        2011-03-19 10:54:00
Exposure Time:           1.999601 s
Dimension:               [ 5.  5.] pix
Coordinate System:       helioprojective
Scale:                   [ 2.4  2.4] arcsec / pix
Reference Pixel:         [ 512.5  512.5] pix
Reference Coord:         [ 0.  0.] arcsec

array([[ 0.3125, -0.0625, -0.125 ,  0.    , -0.375 ],
    [ 1.    ,  0.1875, -0.8125,  0.125 ,  0.3125],
    [-1.1875,  0.375 , -0.5   ,  0.25  , -0.4375],
    [-0.6875, -0.3125,  0.8125,  0.0625,  0.1875],
    [-0.875 ,  0.25  ,  0.1875,  0.    , -0.6875]])
superpixel(dimensions, offset=<Quantity [ 0., 0.] pix>, func=<function sum>)[source] [edit on github]

Returns a new map consisting of superpixels formed by applying ‘func’ to the original map data.

Parameters:
  • dimensions (tuple) – One superpixel in the new map is equal to (dimension[0], dimension[1]) pixels of the original map. Note: the first argument corresponds to the ‘x’ axis and the second argument corresponds to the ‘y’ axis.
  • offset (tuple) – Offset from (0,0) in original map pixels used to calculate where the data used to make the resulting superpixel map starts.
  • func (function applied to the original data) – The function ‘func’ must take a numpy array as its first argument, and support the axis keyword with the meaning of a numpy axis keyword (see the description of sum for an example.) The default value of ‘func’ is sum; using this causes superpixel to sum over (dimension[0], dimension[1]) pixels of the original map.
Returns:

out (GenericMap or subclass) – A new Map which has superpixels of the required size.

References

world_to_pixel(coordinate, origin=0)[source] [edit on github]

Convert a world (data) coordinate to a pixel coordinate by using wcs_world2pix.

Parameters:
  • coordinate (SkyCoord or BaseFrame) – The coordinate object to convert to pixel coordinates.
  • origin (int) – Origin of the top-left corner. i.e. count from 0 or 1. Normally, origin should be 0 when passing numpy indices, or 1 if passing values from FITS header or map attributes. See wcs_world2pix for more information.
Returns:

  • x (Quantity) – Pixel coordinate on the CTYPE1 axis.
  • y (Quantity) – Pixel coordinate on the CTYPE2 axis.