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 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] = sunpy.io.fits.read(filepath) 
>>> 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)[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
>>> 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.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')   
  • 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.

Functions

all_coordinates_from_map(smap)

Returns the coordinates of every pixel in a map.

all_pixel_indices_from_map(smap)

Returns pixel pair indices of every pixel in 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.

coordinate_is_on_solar_disk(coordinates)

Checks if the helioprojective Cartesian coordinates are on the solar disk.

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.

make_fitswcs_header(data, coordinate[, …])

Function to create a FITS-WCS header from a coordinate object (SkyCoord) that is required to create a GenericMap.

map_edges(smap)

Returns the pixel locations of the edges of an input map.

meta_keywords()

Returns the metadata keywords that are used when creating a sunpy.map.GenericMap.

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.

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

MapSequence(*args[, sortby, derotate])

A series of Maps in a single object.

Class Inheritance Diagram

Inheritance diagram of sunpy.map.compositemap.CompositeMap, sunpy.map.mapbase.GenericMap, sunpy.map.mapsequence.MapSequence

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.

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

KCorMap(data, header, **kwargs)

K-Cor Image Map.

Class Inheritance Diagram

Inheritance diagram of sunpy.map.sources.hinode.XRTMap, sunpy.map.sources.hinode.SOTMap, sunpy.map.sources.proba2.SWAPMap, sunpy.map.sources.rhessi.RHESSIMap, sunpy.map.sources.sdo.AIAMap, sunpy.map.sources.sdo.HMIMap, sunpy.map.sources.soho.EITMap, sunpy.map.sources.soho.LASCOMap, sunpy.map.sources.soho.MDIMap, sunpy.map.sources.stereo.EUVIMap, sunpy.map.sources.stereo.CORMap, sunpy.map.sources.stereo.HIMap, sunpy.map.sources.yohkoh.SXTMap, sunpy.map.sources.iris.SJIMap, sunpy.map.sources.trace.TRACEMap, sunpy.map.sources.mlso.KCorMap

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