Maps (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 GenericMap and these 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 sunpy.map Package.

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 sunpy.map Package to see a list of all of them), or if no instrument matches, a 2D map GenericMap.

Fixing map metadata

If you need to fix the metadata of a fits file before it is handed to Map, this can be done as follows:

>>> data, header = astropy.io.fits.read(filepath)[0] 
>>> header['cunit1'] = 'arcsec' 
>>> header['cunit2'] = 'arcsec' 
>>> map = sunpy.map.Map(data, header) 

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

A factory for generating coordinate aware 2D images.

This factory takes a variety of inputs, such as file paths, wildcard patterns or (data, header) pairs.

Depending on the input different return types are possible.

Parameters:

• *inputs – Inputs to parse for map objects. See the examples section for a detailed list of accepted inputs.

• sequence (bool, optional) – Return a sunpy.map.MapSequence object comprised of all the parsed maps.

• composite (bool, optional) – Return a sunpy.map.CompositeMap object comprised of all the parsed maps.

Returns:

• sunpy.map.GenericMap – If the input results in a singular map object, then that is returned.

• list of GenericMap – If multiple inputs are given and sequence=False and composite=False (the default) then a list of GenericMap objects will be returned.

• sunpy.map.MapSequence – If the input corresponds to multiple maps and sequence=True is set, then a MapSequence object is returned.

• sunpy.map.CompositeMap – If the input corresponds to multiple maps and composite=True is set, then a CompositeMap object is returned.

Examples

>>> import sunpy.map
>>> from astropy.io import fits
>>> 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

• Preloaded tuples of (data, header) pairs

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

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

• data, header pairs, not in tuples

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

• data, wcs object, in tuple

>>> from astropy.wcs import WCS
>>> wcs = WCS(sunpy.data.sample.AIA_171_ROLL_IMAGE)  
>>> data = fits.getdata(sunpy.data.sample.AIA_171_ROLL_IMAGE)  
>>> mymap = sunpy.map.Map((data, wcs))  

• data, wcs object, not in tuple

>>> from astropy.wcs import WCS
>>> wcs = WCS(sunpy.data.sample.AIA_171_ROLL_IMAGE)  
>>> data = fits.getdata(sunpy.data.sample.AIA_171_ROLL_IMAGE)  
>>> mymap = sunpy.map.Map(data, wcs)  

• 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')   

• A filesystem path expressed as a pathlib.Path

>>> import pathlib
>>> mymap = sunpy.map.Map(pathlib.Path('file1.fits'))   
>>> sub_dir = pathlib.Path('local_dir/sub_dir')
>>> mymap = sunpy.map.Map(sub_dir)   
>>> mymap = sunpy.map.Map(sub_dir / 'file3.fits')   

• 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'))  

sunpy.map Package

All sunpy Maps are derived from sunpy.map.GenericMap, all the methods and attributes are documented in that class.

sunpy.map Package

Functions

all_coordinates_from_map(smap)	Returns the coordinates of the center of every pixel in a map.
all_corner_coords_from_map(smap)	Returns the coordinates of the pixel corners in a map.
all_pixel_indices_from_map(smap)	Returns pixel pair indices of every pixel in a map.
contains_coordinate(smap, coordinates)	Checks whether a coordinate falls within the bounds of a map.
contains_full_disk(smap)	Checks if a map contains the full disk of the Sun.
contains_limb(smap)	Checks if a map contains any part of the solar limb or equivalently whether the map contains both on-disk and off-disk pixels.
contains_solar_center(smap)	Returns True if smap contains the solar center.
coordinate_is_on_solar_disk(coordinates)	Checks if the helioprojective Cartesian coordinates are on the solar disk.
extract_along_coord(smap, coord)	Extract pixel values from a map along a path that approximates a coordinate path.
is_all_off_disk(smap)	Checks if none of the coordinates in the GenericMap are on the solar disk.
is_all_on_disk(smap)	Checks if all of the coordinates in the GenericMap are on the solar disk.
map_edges(smap)	Returns the pixel locations of the edges of an input map.
on_disk_bounding_coordinates(smap)	Returns the the bottom left and top right coordinates of the smallest rectangular region that contains all the on disk coordinates of the input map.
sample_at_coords(smap, coordinates)	Samples the data in a map at given series of coordinates.
solar_angular_radius(coordinates)	Calculates the solar angular radius as seen by the observer.

Classes

CompositeMap(map1 [,map2,..])	A Composite Map class
GenericMap(data, header[, plot_settings])	A Generic spatially-aware 2D data array
MapMetaValidationError
MapSequence(*args[, sortby, derotate])	A series of Maps in a single object.
PixelPair(x, y)

Variables

Map	A factory for generating coordinate aware 2D images.
maxwell	CGS unit for magnetic flux

Class Inheritance Diagram

Header helpers

The header_helper sub-module contains helper functions for generating FITS-WCS headers from Python objects.

sunpy.map.header_helper Module

Functions

meta_keywords()	Returns the metadata keywords that are used when creating a sunpy.map.GenericMap.
make_fitswcs_header(data, coordinate[, ...])	Function to create a FITS-WCS header from a coordinate object (SkyCoord) that is required to create a GenericMap.
get_observer_meta(observer[, rsun])	Function to get observer meta from coordinate frame.
make_heliographic_header(date, ...[, ...])	Construct a FITS-WCS header for a full-Sun heliographic (Carrington or Stonyhurst) coordinate frame.

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

sunpy.map.sources Package

Functions

from_helioviewer_project(meta)	Test determining if the given metadata contains Helioviewer Project sourced data.
source_stretch(meta, fits_stretch)	Assign the correct source-dependent image stretching function.

Classes

AIAMap(data, header, **kwargs)	AIA Image Map.
CORMap(data, header, **kwargs)	STEREO-SECCHI CORonograph Image Map.
EITMap(data, header, **kwargs)	SOHO EIT Image Map.
EUIMap(data, header, **kwargs)	EUI Image Map
EUVIMap(data, header, **kwargs)	STEREO-SECCHI EUVI Image Map
HIMap(data, header, **kwargs)	STEREO-SECCHI Heliospheric Imager (HI) Map.
HMIMap(data, header, **kwargs)	HMI Image Map.
HMISynopticMap(data, header, **kwargs)	SDO/HMI Synoptic Map.
KCorMap(data, header, **kwargs)	K-Cor Image Map.
LASCOMap(data, header, **kwargs)	SOHO LASCO Image Map
MDIMap(data, header, **kwargs)	SOHO MDI Image Map
MDISynopticMap(data, header, **kwargs)	SOHO MDI synoptic magnetogram Map.
RHESSIMap(data, header, **kwargs)	RHESSI Image Map.
SJIMap(data, header[, plot_settings])	A 2D IRIS Slit Jaw Imager Map.
SOTMap(data, header, **kwargs)	Hinode SOT Image Map definition.
SUVIMap(data, header, **kwargs)	SUVI Image Map.
SWAPMap(data, header, **kwargs)	PROBA2 SWAP Image Map.
SXTMap(data, header, **kwargs)	Yohkoh SXT Image Map
TRACEMap(data, header, **kwargs)	TRACE Image Map
WISPRMap(data, header[, plot_settings])	WISPR Map
XRTMap(data, header, **kwargs)	Hinode XRT map definition.

Class Inheritance Diagram

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

    def __init__(self, data, header, **kwargs):

        super(FutureMap, self).__init__(data, header, **kwargs)

        # Any Future Instrument specific keyword manipulation

   # Specify a classmethod that determines if the data-header pair matches
   # the new instrument
   @classmethod
   def is_datasource_for(cls, data, header, **kwargs):
        """Determines if header corresponds to an AIA image"""
        return str(header.get('instrume', '')).startswith('FUTURESCOPE')

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

sunpy.map.Map.register(FutureMap, FutureMap.some_matching_method)