Input/output (sunpy.io
)#
sunpy.io
contains readers for files that are commonly used in solar physics.
Unified File Readers#
sunpy.io Package#
Functions#
|
Attempts to determine the type of file a given filepath is. |
|
Automatically determine the filetype and read the file. |
|
Reads the header from a given file. |
|
Write a file from a data & header pair using one of the defined file types. |
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.
By default, this module is not installed on platforms other than Linux (x86-64) and macOS (x86-64 and ARM64). See the installation guide for more info.
Functions#
|
Loads an ANA file and returns the data and a header in a list of (data, header) tuples. |
|
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. |
|
Saves a 2D |
Special File Readers#
sunpy.io.special.genx Module#
This module implements a solarsoft genx file reader.
Functions#
|
solarsoft genx file reader. |
sunpy
has a custom reader for NOAA SWPC Solar Region Summary (SRS) files:
sunpy.io.special.srs Module#
This module implements a SRS File Reader.
Functions#
|
Parse a SRS table from NOAA SWPC. |
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.
Internal API#
These are readers and other utilities that are used internally by sunpy
to read files.
They are not intended to be used directly by users and we do not guarantee that they will
work for all files of a given type nor will the API be stable.
sunpy.io._fits Module#
This module provides a FITS file reader for internal use.
We instead recommend users use the astropy.io.fits
module,
which provides more generic functionality to read FITS files.
Notes
FITS files allow comments to be attached to every value in the header. This is implemented in this module as a KEYCOMMENTS dictionary in the sunpy header. To add a comment to the file on write, add a comment to this dictionary with the same name as a key in the header (upcased).
Due to the way
fits
works with images, the header dictionary may differ depending on whether is accessed before or after the fits[0].data is requested. If the header is read before the data then the original header will be returned. If the header is read after the data has been accessed then the data will have been scaled and a modified header reflecting these changes will be returned: BITPIX may differ and BSCALE and B_ZERO may be dropped in the modified version.The verify(‘silentfix+warn’) call attempts to handle violations of the FITS standard. For example,
nan
values will be converted to “nan” strings. Attempting to cast aastropy.io.fits.Header
to a dictionary while it contains invalid header tags will result in an error so verifying it early on makes the header easier to work with later.
Functions#
|
Convert a header dict to a |
|
Read a fits file. |
|
Read a fits file and return just the headers for all HDU's. |
|
Take a data header pair and write a FITS file. |
|
Attempt to read the wavelength unit from a given FITS header. |
|
Combine |
sunpy.io.header Module#
This module provides a generic FileHeader object for the readers.
Classes#
|
FileHeader is designed to provide a consistent interface to all other sunpy classes that expect a generic file. |
Class Inheritance Diagram#
sunpy.io._jp2 Module#
This module provides a JPEG 2000 file reader for internal use.
Warning
sunpy.io.jp2
is deprecated, and will be removed in sunpy 4.1. This is
because it was designed for internal use only.
Functions#
|
Reads a JPEG2000 file. |
|
Reads the header from the file. |
|
Take a data header pair and write a JP2 file. |
sunpy.io._file_tools Module#
This module provides a generic file reader for internal use.
Warning
sunpy.io.file_tools
is deprecated, and will be removed in sunpy 4.1. This is
because it was designed for internal use only.
Functions#
|
Automatically determine the filetype and read the file. |
|
Reads the header from a given file. |
|
Write a file from a data & header pair using one of the defined file types. |
|
Attempts to determine the type of file a given filepath is. |
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#
This module provides a CDF file reader for internal use.
Warning
sunpy.io.cdf
is deprecated, and will be removed in sunpy 5.1. This is
because it was designed for internal use only.
Functions#
|
Read a CDF file that follows the ISTP/IACG guidelines. |