# SunPy map¶

## Overview¶

One of core classes in SunPy is a Map. A SunPy Map object is simply a spatially-aware data array, often an image. In order to make it easy to work with image data in SunPy, the Map object provides a number of methods for commonly performed operations.

2D map objects are subclasses of MapBase and all Map objects are created using the Map factory Map.

A number of instrument are supported by subclassing this base object. See Instrument Map Classes to see a list of all of them. More complex subclasses are also available. See Map Classes.

## Creating Map Objects¶

SunPy Map objects are constructed using the special factory class Map:

>>> x = sunpy.map.Map('file.fits')


The result of a call to Map will be either a GenericMap object, or a subclass of GenericMap which either deals with a specific type of data, e.g. AIAMap or LASCOMap (see Map Classes to see a list of all of them), or if no instrument matches, a 2D map GenericMap.

class sunpy.map.map_factory.MapFactory(default_widget_type=None, additional_validation_functions=[], registry=None)[source] [edit on github]

Map(*args, **kwargs)

Map factory class. Used to create a variety of Map objects. Valid map types are specified by registering them with the factory.

Examples

>>> import sunpy.map
>>> import sunpy.data.sample
>>> mymap = sunpy.map.Map(sunpy.data.sample.AIA_171_IMAGE)


The SunPy Map factory accepts a wide variety of inputs for creating maps

>>> mymap = sunpy.map.Map((data, header))


headers are some base of dict or collections.OrderedDict, including sunpy.io.header.FileHeader or sunpy.util.MetaDict classes.

• data, header pairs, not in tuples
>>> mymap = sunpy.map.Map(data, header)

• File names
>>> mymap = sunpy.map.Map('file1.fits')

• All fits files in a directory by giving a directory
>>> mymap = sunpy.map.Map('local_dir/sub_dir')

• Some regex globs
>>> mymap = sunpy.map.Map('eit_*.fits')

• URLs
>>> mymap = sunpy.map.Map(url_str)

• DatabaseEntry
>>> mymap = sunpy.map.Map(db_result)

• Lists of any of the above
>>> mymap = sunpy.map.Map(['file1.fits', 'file2.fits', 'file3.fits', 'directory1/'])

• Any mixture of the above not in a list
>>> mymap = sunpy.map.Map((data, header), data2, header2, 'file1.fits', url_str, 'eit_*.fits')


## Using Map Objects¶

Once a map object has been created using Map it will be a instance or a subclass of the GenericMap class. Irrespective of the instrument the map is constructed for, all maps behave the same and are interchangeable with one another. It is possible to manipulate the map or access meta data about the map from the methods and properties of the map class. The following documentation of GenericMap lists the attributes and methods that are available on all Map objects.

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

A Generic spatially-aware 2D data array

Parameters: Other Parameters: data (ndarray, list) – A 2d list or ndarray containing the map data. header (dict) – A dictionary of the original image header tags. plot_settings (dict, optional) – Plot settings. **kwargs – Additional keyword arguments are passed to NDData init.

Examples

>>> import sunpy.map
>>> import sunpy.data.sample
>>> aia = sunpy.map.Map(sunpy.data.sample.AIA_171_IMAGE)
>>> aia
SunPy Map
---------
Observatory:                 SDO
Instrument:          AIA 3
Detector:            AIA
Measurement:                 171.0 Angstrom
Wavelength:          171.0 Angstrom
Observation Date:    2011-06-07 06:33:02
Exposure Time:               0.234256 s
Dimension:           [1024. 1024.] pix
Coordinate System:   helioprojective
Scale:                       [2.402792 2.402792] arcsec / pix
Reference Pixel:     [512.5 512.5] pix
Reference Coord:     [3.22309951 1.38578135] arcsec

array([[ -96.,    7.,   -2., ..., -128., -128., -128.],
[ -97.,   -5.,    0., ...,  -99., -104., -128.],
[ -94.,    1.,   -4., ...,   -5.,  -38., -128.],
...,
[-128., -128., -128., ..., -128., -128., -128.],
[-128., -128., -128., ..., -128., -128., -128.],
[-128., -128., -128., ..., -128., -128., -128.]], dtype=float32)

>>> 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.

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).

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.

date

Image observation time.

detector

Detector name.

dimensions

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

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. 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. 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. 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. 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: bottom_left (SkyCoord or BaseCoordinateFrame) – The bottom left corner of the rectangle. width (astropy.units.Quantity) – The width of the rectangle. height (astropy.units.Quantity) – The height of the rectangle. axes (matplotlib.axes.Axes) – The axes on which to plot the rectangle, defaults to the current axes. 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.

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.

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.

measurement

Measurement name, defaults to the wavelength of image.

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

Calculate the minimum value of the data array.

name

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.

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. 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.

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. 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()

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).

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 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 out (GenericMap or subclass) – A new Map instance containing the rotated and rescaled data of the original map.

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().

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

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.
scale

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

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 out (GenericMap or subclass) – A new shifted Map.
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).

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,). out (GenericMap or subclass) – A new map instance is returned representing to specified sub-region.

Examples

>>> import astropy.units as u
>>> from astropy.coordinates import SkyCoord
>>> 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-06-07 06:33:02
Exposure Time:           0.234256 s
Dimension:               [334. 334.] pix
Coordinate System:       helioprojective
Scale:                   [2.402792 2.402792] arcsec / pix
Reference Pixel:         [127.5 126.5] pix
Reference Coord:         [3.22309951 1.38578135] arcsec

array([[ 451.,  566.,  586., ..., 1179., 1005.,  978.],
[ 475.,  515.,  556., ..., 1026., 1011., 1009.],
[ 547.,  621.,  621., ...,  935., 1074., 1108.],
...,
[ 203.,  195.,  226., ...,  612.,  580.,  561.],
[ 207.,  213.,  233., ...,  651.,  622.,  537.],
[ 230.,  236.,  222., ...,  516.,  586.,  591.]], dtype=float32)

>>> 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-06-07 06:33:02
Exposure Time:           0.234256 s
Dimension:               [5. 5.] pix
Coordinate System:       helioprojective
Scale:                   [2.402792 2.402792] arcsec / pix
Reference Pixel:         [512.5 512.5] pix
Reference Coord:         [3.22309951 1.38578135] arcsec

array([[-96.,   7.,  -2.,  -3.,  -1.],
[-97.,  -5.,   0.,   0.,   1.],
[-94.,   1.,  -4.,   2.,  -2.],
[-97.,  -8.,  -3.,  -5.,  -1.],
[-96.,   6.,  -5.,  -1.,  -4.]], dtype=float32)

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. out (GenericMap or subclass) – A new Map which has superpixels of the required size.

References

top_right_coord

The physical coordinate for the top left pixel.

wavelength

Wavelength of the observation.

wcs

The WCS property of the map.

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. x (Quantity) – Pixel coordinate on the CTYPE1 axis. y (Quantity) – Pixel coordinate on the CTYPE2 axis.
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.

## Map Classes¶

Defined in sunpy.map.sources are a set of GenericMap subclasses which convert the specific metadata and other differences in each instruments data to the standard GenericMap interface. These ‘sources’ also define things like the colormap and default normalisation for each instrument. These subclasses also provide a method, which describes to the Map factory which data and metadata pairs match its instrument.

### Classes¶

 CompositeMap(map1 [,map2,..]) A Composite Map class GenericMap(data, header[, plot_settings]) A Generic spatially-aware 2D data array MapCube(*args, **kwargs) A series of spatially aligned Maps.

## sunpy.map.sources Package¶

Datasource-specific classes

This is where datasource specific logic is implemented. Each mission should have its own file with one or more classes defined. Typically, these classes will be subclasses of the :modsunpy.map.Map class.

### Functions¶

 source_stretch(meta, fits_stretch) Assign the correct source-dependent image stretching function.

### Classes¶

 XRTMap(data, header, **kwargs) Hinode XRT map definition. SOTMap(data, header, **kwargs) Hinode SOT Image Map definition. SWAPMap(data, header, **kwargs) PROBA2 SWAP Image Map. RHESSIMap(data, header, **kwargs) RHESSI Image Map. AIAMap(data, header, **kwargs) AIA Image Map. HMIMap(data, header, **kwargs) HMI Image Map. EITMap(data, header, **kwargs) SOHO EIT Image Map. LASCOMap(data, header, **kwargs) SOHO LASCO Image Map MDIMap(data, header, **kwargs) SOHO MDI Image Map EUVIMap(data, header, **kwargs) STEREO-SECCHI EUVI Image Map CORMap(data, header, **kwargs) STEREO-SECCHI CORonograph Image Map. HIMap(data, header, **kwargs) STEREO-SECCHI Heliospheric Imager (HI) Map. SXTMap(data, header, **kwargs) Yohkoh SXT Image Map SJIMap(data, header, **kwargs) A 2D IRIS Slit Jaw Imager Map. TRACEMap(data, header, **kwargs) TRACE Image Map

## Writing a new Instrument Map Class¶

Any subclass of GenericMap which defines a method named is_datasource_for will automatically be registered with the Map factory. The is_datasource_for method describes the form of the data and metadata for which the GenericMap subclass is valid. For example it might check the value of the INSTRUMENT key in the metadata dictionary. This makes it straightforward to define your own GenericMap subclass for a new instrument or a custom data source like simulated data. These classes only have to be imported for this to work, as demonstrated by the following example.

import sunpy.map
class FutureMap(sunpy.map.GenericMap):

# Any Future Instrument specific keyword manipulation

# Specify a classmethod that determines if the data-header pair matches
# the new instrument
@classmethod

This class will now be available through the Map factory as long as this class has been defined, i.e. imported into the current session.
If you do not want to create a method named is_datasource_for you can manually register your class and matching method using the following method
import sunpy.map