Input/output (sunpy.io)

sunpy.io contains readers for files that are commonly used in solar physics.

Unified File Readers

sunpy.io Package

Functions

detect_filetype(filepath)

Attempts to determine the type of file a given filepath is.

read_file(filepath[, filetype])

Automatically determine the filetype and read the file.

read_file_header(filepath[, filetype])

Reads the header from a given file.

write_file(fname, data, header[, filetype])

Write a file from a data & header pair using one of the defined file types.

sunpy.io.header Module

This module provides a generic FileHeader object for the readers.

Classes

FileHeader(*args, **kwargs)

FileHeader is designed to provide a consistent interface to all other sunpy classes that expect a generic file.

Class Inheritance Diagram

Inheritance diagram of sunpy.io.header.FileHeader

sunpy.io.jp2 Module

This module provides a JPEG 2000 file reader.

Functions

read(filepath, **kwargs)

Reads a JPEG2000 file.

get_header(filepath)

Reads the header from the file.

write(fname, data, header, **kwargs)

Take a data header pair and write a JP2 file.

sunpy.io.ana Module

This module provides an ANA file Reader.

This is a modified version of pyana.

Warning

The reading and writing of ana files is not supported under Windows.

Functions

read(filename[, debug])

Loads an ANA file and returns the data and a header in a list of (data, header) tuples.

get_header(filename[, debug])

Loads an ANA file and only return the header consisting of the dimensions, size (defined as the product of all dimensions times the size of the datatype, this not relying on actual filesize) and comments.

write(filename, data[, comments, compress, ...])

Saves a 2D numpy.array as an ANA file and returns the bytes written or NULL.

Special File Readers

sunpy.io.special.genx Module

This module implements a solarsoft genx file reader.

Functions

read_genx(filename)

solarsoft genx file reader.

asdf (Advanced Scientific Data Format)

ASDF is a modern file format designed to meet the needs of the astronomy community. It has deep integration with Python, SunPy, and Astropy, as well as implementations in other languages. It can be used to store known Python objects in a portable, well defined file format. It is primarily useful for storing complex Astropy and SunPy objects in a way that can be loaded back into the same form as they were saved. It is designed to be an archive file format, with human readable metadata and a simple on-disk layout.

sunpy currently implements support for saving Map and coordinate frame objects into asdf files. As asdf tightly integrates into Python, saving a map to an asdf file will save the metadata, data and mask. In comparison, the mask is not currently saved to FITS. The following code shows to to save and load a sunpy Map to an asdf file

>>> import asdf
>>> import sunpy.map
>>> from sunpy.data.sample import AIA_171_IMAGE  
>>> aiamap = sunpy.map.Map(AIA_171_IMAGE)  
>>> tree = {'amap': aiamap}  
>>> with asdf.AsdfFile(tree) as asdf_file:  
...     asdf_file.write_to("sunpy_map.asdf")  
>>> input_asdf = asdf.open("sunpy_map.asdf")  
>>> input_asdf['amap']  
  <sunpy.map.sources.sdo.AIAMap object at ...>
  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:     [511.5 511.5] pix
  Reference Coord:     [3.22309951 1.38578135] arcsec
  array([[ -95.92475  ,    7.076416 ,   -1.9656711, ..., -127.96519  ,
          -127.96519  , -127.96519  ],
         [ -96.97533  ,   -5.1167884,    0.       , ...,  -98.924576 ,
          -104.04137  , -127.919716 ],
         [ -93.99607  ,    1.0189276,   -4.0757103, ...,   -5.094638 ,
           -37.95505  , -127.87541  ],
         ...,
         [-128.01454  , -128.01454  , -128.01454  , ..., -128.01454  ,
          -128.01454  , -128.01454  ],
         [-127.899666 , -127.899666 , -127.899666 , ..., -127.899666 ,
          -127.899666 , -127.899666 ],
         [-128.03072  , -128.03072  , -128.03072  , ..., -128.03072  ,
          -128.03072  , -128.03072  ]], dtype=float32)
 >>> input_asdf.close()

When saving a Map to ASDF all maps are saved as a GenericMap and not a specific source class. This comes with some trade-offs. If you are using custom map sources defined outside of the sunpy core package, and these sources are imported after asdf has been invoked for the first time (used, not just imported), then they will not be registered with the asdf converter. Also if the custom map subclass is not registered with sunpy.map.Map upon loading of the map, it will be returned as a GenericMap. This approach has been chosen despite these limitations so that once a map is saved to an ASDF file it can always be loaded back into a map rather than the asdf library returning it as a Python dictionary. It also follows the philosophy of the way maps are saved and loaded in the FITS format, where the components of the Map are serialised and the way meta data is handled depends solely on the contents of the .meta attribute.

CDF (common data format)

CDF files are commonly used to store timeseries data observed by instruments taking in-situ measurements of plasmas throughout the heliosphere. sunpy provides support for reading in CDF files that conform to the Space Physics Guidelines for CDF.

sunpy.io.cdf Module

Functions

read_cdf(fname)

Read a CDF file that follows the ISTP/IACG guidelines.