sunpy documentation › pdf › sunpy › 0.2.0 › sunpy.pdf · 2019-04-02 · sunpy...

SunPy DocumentationRelease 0.1

SunPy Community

February 14, 2014

Contents

i

CHAPTER 1

Documentation

1.1 SunPy User Guide

Welcome to the SunPy User Guide!

1.1.1 Installation

Below are instructions for installation SunPy and its prerequisites on different platforms.

Installing Scientific Python

For instructions on setting up the scientific Python environment which is required by SunPy, choose your OS from thelist below. When you are done come back here and follow the instructions below to install SunPy and its requirements.

Mac OS X

Overview Because of the wide variety of methods for setting up a Python environment on Mac OS X, users havea number of options with how to install SunPy and its dependencies. We have a number of solutions listed below.Choose the solution which best suits you.

Installation using EPD One simplest method is to install the Enthought Python Distribution (EPD), which includesboth Python and many of dependencies needed by SunPy. The Enthought Python Distribution (EPD) is a metapackagewhich handles the installation of everything for you.

Install EPD There are a number versions of EPD available, many of which are not free. For our purposes, however,either of the free versions below will work:

‘EPD Free ‘_‘EPD Academic ‘_

Download whichever of the above versions of EPD is appropriate, and follow the instructions provided on the EPDwebsite to install EPD on your system. You can now continue the installation process and install SunPy itself .

1

http://www.enthought.com/products/epd_free.php/http://www.enthought.com/products/epdgetstart.php?platform=machttp://www.enthought.com/products/epdgetstart.php?platform=mac

SunPy Documentation, Release 0.1

Installation using Virtual Box Virtual box is a free virtual environment that allows you to run linux or other oper-ating systems concurrently with OS X. Since it is very easy to install and maintain SunPy under linux, the idea hereis to have your own linux environment on your mac and use it for SunPy. We recommend you use Ubuntu linux inyour virtual box. You can download an install disk for Ubuntu at their website. Directions on how to install your firstvirtual machine on Virtual Box are also available. After your have Ubuntu installed just follow the instructions forlinux! Simple.

Other installation methods For users who wish to have more control over the installation of Python, several alter-native installation methods are provided below, including instructions for Macports and Homebrew. The followinginstructions are not recommended for beginners. OS X comes pre-loaded with Python but each versions of OS X(Mountain Lion, Snow Leopard, etc.) ships with a different version of Python. In the instructions below, we thereforerecommend that you install your own version of Python. You will then have two versions of Python living on yoursystem at the same time. It can be confusing to make sure that when you install packages they are installed for thecorrect Python so beware.

Python 2.7.3+ Download and install the latest version of 32 bit Python 2.7.3 using their DMG installer. Next, chooseyour package installer of choice (either Macports or Homebrew) and follow the instructions below. If you do not haveeither go to their respective websites and install one of the other as needed.

Compiler Download and install XCode from the App Store. Install the compiler by installing the optional “Com-mand Line Tools” as part of XCode. In the latest version of Xcode, this can be found in the preferences under theDownloads tab.

Macports Macports is a useful To install everything that you need using Macports. First install Macports. You’llneed Xcode and the command line tools. First update the package index:

sudo port selfupdate

To install the basic Python packages, run:

sudo port install py27-matplotlib py27-numpy py27-scipy

To install Qt (this will take a while!), run:

sudo port install qt4-mac

This will install python 2.7 at the same time. To make the macports version of Python the default type the followinginto a terminal:

sudo port select --set python python27

For more information on using MacPorts to manage your Python installation, see the following page.

Homebrew Homebrew is a tool for helping to automate the installation of a number of useful tools and libraries onMac OS X. It is similar to Macports, but attempts to improve on some of the pitfalls of Macports.

Note that if you have already installed either fink or Macports on your system, it is recommended that you uninstallthem before using Homebrew.

Next, install and update homebrew:

/usr/bin/ruby -e "$(/usr/bin/curl -fsSL https://raw.github.com/mxcl/homebrew/master/Library/Contributions/install_homebrew.rb)"brew doctor

Using homebrew, install Qt and some of the other dependencies needed for compilation later on by pip:

2 Chapter 1. Documentation

http://www.macports.org/http://mxcl.github.com/homebrew/http://astrofrog.github.com/macports-python/http://mxcl.github.com/homebrew/


brew -v install gfortran pkgconfig git openjpeg readline pyqt

Now on to the next steps.

Git Head over and download and install git.

Pip Most Python distributions ship with a tool called easy_install which assists with installing Python packages.

Although easy_install is capable of installing most of the dependencies needed for SunPy itself, a more powerful toolcalled pip which provides a more flexible installation (including support for uninstalling, upgrading, and installingfrom remote sources such as GitHub) and should be used instead.

Use easy_install to install pip:

sudo easy_install pip

You are now ready to install scipy, numpy, and matplotlib.

Scientific Libraries If pip installed properly, then you can install NumPy simply with:

pip install numpy

Now under Lion, install the stable version of SciPy (0.10) by running:

pip install scipy

Mountain Lion users will need to install the development version of SciPy (0.11) by executing the following line:

pip install -e git+https://github.com/scipy/scipy#egg=scipy-dev

Now on to matplotlib

On Lion, install matplotlib like any other package:

pip install matplotlib

Mountain Lion users will have to use the development version as of this writing:

pip install git+https://github.com/matplotlib/matplotlib.git#egg=matplotlib-dev

Done! You are now ready to install SunPy itself .

Linux

Overview Almost all versions of Linux ship with a recent enough version of Python, so it is unlikely that you willneed to install Python yourself.

Ubuntu On Ubuntu, most of the pre-reqs are available in the Ubuntu software repos and can be installed usingapt-get:

sudo apt-get install python-qt4sudo apt-get install git-coresudo apt-get python-numpysudo apt-get python-scipysudo apt-get python-matplotlibsudo apt-get update

1.1. SunPy User Guide 3

http://pypi.python.org/pypi/setuptoolshttp://pypi.python.org/pypi/setuptoolshttp://pypi.python.org/pypi/piphttp://pypi.python.org/pypi/setuptools


Now we shall install pip.

Pip Most Python distributions ship with a tool called easy_install which assists with installing Python packages.

Although easy_install is capable of installing most of the dependencies needed for SunPy itself, a more powerfultool called pip provides a more flexible installation (including support for uninstalling, upgrading, and installing fromremote sources such as GitHub) and should be used instead.

Use easy_install to install pip:

sudo easy_install pip

You are now ready to install SunPy and its dependencies.

Windows

Overview There are many ways to get the necessary environment up and running for SunPy on Windows, and wedescribe the recommended method and an alternate method below.

Python(x,y) 1. Install Python(x,y)

Download and install Python(x,y). Python(x,y) is a distribution that include not only Python, but also a large varietyof Python modules and development tools. Please note that this installer is rather large (~500 MB) and thus may take awhile to download. The following required modules are included in Python(x,y): NumPy, SciPy, Matplotlib, PyFITS,pandas, distribute, and Qt.

2. Set up the Python build environment

Create a file in C:\Python27\lib\distutils\ called distutils.cfg that contains the following lines:

[build]compiler=mingw32[build_ext]compiler=mingw32

There is currently a bug in the Python 2.7 code, so you will also need to edit cygwincompiler.py in the samedirectory. Remove all five instances of the character string “-mno-cygwin”.

3. Install Git

Download and install Git. Git is used to retrieve the SunPy code.

4. Install Pip

Download and install pip. (Note: this installer is built by the Python(x,y) team.) You are now ready to continue withthe rest of the installation.

Alternate method If Python(x,y) is unavailable, or if it is critical for you to have the most up-to-date version ofmodules, then this alternate method eschews installers as much as possible and emphasizes building from source. Thismethod is not for the faint of heart! Please use this method only if you are experienced with computers and Python.

1. Install Python

Download and install Python 2.7 (32-bit). Note that even if you are on a 64-bit system, you are installing a 32-bitversion of Python to be able to use precompiled binaries where still needed.

You should update the PATH environment variable so that Python executables and associated scripts can be found:


http://pypi.python.org/pypi/setuptoolshttp://pypi.python.org/pypi/setuptoolshttp://pypi.python.org/pypi/piphttp://pypi.python.org/pypi/setuptoolshttps://code.google.com/p/pythonxy/wiki/Downloadshttps://code.google.com/p/msysgit/downloads/list?can=3&q=Full+installer+for+official+Git+for+Windowshttp://code.google.com/p/pythonxy/downloads/list?q=piphttp://www.python.org/ftp/python/2.7.3/python-2.7.3.msi


1. Go to Start-> Control Panel -> System -> Advanced system settings -> Environmentvariables

2. Find the PATH environment variable, under either user or system variables, and append C:\Python27 andC:\Python27\Scripts, separated by semicolons.

2. Install compilers

Download and install MinGW, specifically the C, C++, and Fortran compilers. Make sure that the binaries can befound in your path (e.g., by adding C:\MinGW\bin to your path).

3. Set up the Python build environment

Create a file in C:\Python27\lib\distutils\ called distutils.cfg that contains the following lines:

[build]compiler=mingw32[build_ext]compiler=mingw32

There is currently a bug in the Python 2.7 code, so you will also need to edit cygwincompiler.py in the samedirectory. Remove all five instances of the character string “-mno-cygwin”.

4. Install pip

Download distribute_setup.py to be able to install distribute:

python distribute_setup.py

Download get-pip.py to be able to install pip:

python get-pip.py

5. Install required modules

You can use pip to download and build modules from source:

pip install numpypip install scipypip install matplotlib

Unfortunately, the compilations of SciPy and Matplotlib will likely fail due to missing libraries. Until there is aworkable solution, you should download the latest installers: SciPy and Matplotlib. You are now ready to continuewith the rest of the installation.

Installing Python Modules

You should now have the following on your system; Python, Numpy, Scipy, Matplotlib, git, pip and Qt. You can nowinstall some final remaining dependencies using pip. Depending on which system you are using some of these mayalready be installed but it does not hurt to upgrade:

pip install --upgrade distributepip install --upgrade pyfitspip install --upgrade sudspip install --upgrade pandaspip install --upgrade beautifulsoup4

We also recommend you use ipython (a great python enviromnent). This can also be installed using pip:

pip install --upgrade ipython


http://mingw.org/http://python-distribute.org/distribute_setup.pyhttps://raw.github.com/pypa/pip/master/contrib/get-pip.pyhttp://sourceforge.net/projects/scipy/files/scipy/0.11.0/scipy-0.11.0-win32-superpack-python2.7.exe/downloadhttp://sourceforge.net/projects/matplotlib/files/matplotlib/matplotlib-1.1.1/matplotlib-1.1.1.win32-py2.7.exe/download


Additionally, if you plan to help with SunPy development, some additional dependencies are required:

pip install --upgrade pytest pylint paver tox sphinx numpydoc

All done with the SunPy Python prerequisites. You are now ready to install SunPy itself.

Installing SunPy

There are a number of ways of installing SunPy. We currently recommend you use the latest (development) version ofSunPy as we are developing quickly. To do this you’ll use git and pip to grab the latest code from github. If you wouldrather have a more stable version of SunPy then check out the section below on grabbing the stable SunPy.

Grabbing the latest SunPy

There are two ways to install the latest version SunPy, including a quick method and a developer method. Dependingon your setup, you may need to preface each of the pip ... commands with sudo pip ....

Quick installation The easiest way to install SunPy is to use pip (combined with git):

pip install git+https://github.com/sunpy/sunpy.git

This will download and install the latest version of SunPy. To upgrade SunPy at a later date, you can run:

pip install --upgrade --no-deps git+https://github.com/sunpy/sunpy.git

Please make sure to include the --no-deps option because otherwise pip may try to upgrade dependencies such asSciPy and Matplotlib that are difficult to build from source and the likely errors will abort the upgrade. That’s it!

Developer installation If you are considering contributing to the development of SunPy, you will likely want tokeep the SunPy code tree in a convenient location.

Open a terminal and cd to a directory where you wish to download SunPy, and run:

git clone https://github.com/sunpy/sunpy.git

This will download the latest version of SunPy. Finally, from inside the new SunPy directory run:

pip install -e .

This will make it make possible to import and use SunPy regardless of your working directory. To upgrade SunPy ata later date, go into the SunPy directory and run:

git pull upstream master

That’s it!

Grabbing the stable SunPy

If you’d like to use a more stable version of SunPy and only upgrade at milestones then head over to github anddownload the latest stable release. After extracting the download you can install SunPy by using pip like so :

pip install ./downloads/SunPyPackage-1.0.4.tar.gz

This will add it to your existing Python modules. To upgrade to the next version, just head back to the github page andgrab the next version and repeat the process above.



Testing your installation

Now you can test your installation. Open a new Python shell and type these commands:

>>> import sunpy>>> sunpy.make_map(sunpy.AIA_171_IMAGE).peek()

If all goes well you should see an AIA 171 image on your screen.

1.1.2 A brief tour of SunPy

Welcome to the SunPy tutorial! This brief tutorial will walk you through some of the functionality currently offeredby SunPy. Start by reading this tutorial and trying out some of the examples demonstrated. Once you’ve completedthe tutorial check out the code reference for a more thorough look at the functionality available.

1. Maps

Maps are the primary data type in SunPy they are spatially and / or temporally aware data arrays. There are types ofmaps for a 2D image, a time series of 2D images or 1D spectra or 2D spectrograms. Making a map of your data is thenormally the first step in using SunPy to work with your data.

Creating a Map

SunPy supports many different data products from various sources ‘out of the box’ we shall use SDO’s AIA instrumentas an example in this tutorial. The general way to create a map from one of the supported data products is with thesunpy.make_map() command.

sunpy.make_map() takes either a filename, list of filenames data array and header. We can test map with:

import sunpyaia = sunpy.make_map(sunpy.AIA_171_IMAGE)

This returns a map named aia which can be maniputated with standard SunPy map commands. For more informationabout maps checkout the map guide.

2. Plotting

Let’s begin by creating a simple plot of an AIA image. To make things easy, SunPy includes several ex-ample files which are used throughout the docs. These files have names like sunpy.AIA_171_IMAGE andsunpy.RHESSI_IMAGE.

Try typing the below example into your interactive Python shell:

import sunpyaia = sunpy.make_map(sunpy.AIA_171_IMAGE)aia.peek()

If everything has been configured properly you should see an AIA image with a red colormap, a colorbar on theright-hand side and a title and some labels.



There is lot going on here, but we will walk you through the example. Briefly, the first line is just importing SunPy.On the second line we create a SunPy Map object which is basically just a spatially-aware image or data array. On thelast line we then plot the map object, using the built in ‘quick plot’ function peek().

SunPy uses a matplotlib like interface to it’s plotting so more complex plots can be built by combining SunPy withmatplotlib:

import sunpyimport matplotlib.pyplot as plt

aia = sunpy.make_map(sunpy.AIA_171_IMAGE)

fig = plt.figure()ax = plt.subplot(111)

aia.plot()plt.colorbar()aia.draw_limb()

plt.show()

This should output something like the image below:



3. Solar Physical Constants

SunPy contains a convienient list of solar-related physical constants. Here is a short bit of code to get you started:

from sunpy.sun import constants as con

# one astronomical unit (the average distance between the Sun and Earth)print(con.au)

# the solar radiusprint(con.radius)

Not all constants have a shortcut assigned to them (as above). The rest of the constants are stored in a dictionary. Thefollowing code grabs the dictionary and gets all of the keys.:

solar_constants = con.physical_constantssolar_constants.keys()

You can also use the following function to print out a table of all of the values available.

con.print_all()

These constants are provided as a convenience so that everyone is using the same (accepted values). More will beadded over time.



4. Working with Times

SunPy also contains a number of convenience functions for working with dates and times. Here is a short example:

from sunpy.time import *

# parsing a standard time stringsparse_time(’2004/02/05 12:00’)

# This returns a datetime object. All SunPy functions which require# time as an input sanitize the input using parse_time.day_of_year(’2004-Jul-05 12:00:02’)

# the julian dayjulian_day((2010,4,30))

# TimeRange objects are useful for representing ranges of timetime_range = TimeRange(’2010/03/04 00:10’, ’2010/03/04 00:20’)time_range.center()

For more information about working with time in SunPy checkout the time guide.

5. Querying the VSO

There are a couple different ways to query and download data from the VSO using SunPy. The method you shoulduse depends first on your preference with respect to query style: the main method of querying uses a syntax that isunique to SunPy and may require some getting used to, but is extremely flexible and powerful. To make it easy forpeople coming from SSW to get started, a second “legacy” API also exists which works is very much the same way asVSO_GET in IDL.

Further, for each of the two query APIs there are interactive and non-interactive versions available, depending on thetype of work you are doing.

The below example demonstrates a simple query for SOHO EIT data using the non-interactive version of the mainAPI:

from sunpy.net import vso

# create a new VSOClient instanceclient = vso.VSOClient()

# build our queryresult = client.query(

vso.attrs.Time((2011, 9, 20, 1), (2011, 9, 20, 2)),vso.attrs.Instrument(’eit’)

)

# print the number of matchesprint("Number of records found: %d " % result.num_records())

# download matches to /download/pathres = client.get(result, path="/download/path/{file}").wait()

Note that specifying a path is optional and if you do not specify one the files will simply be downloaded into atemporary directory (e.g. /tmp/xyz). For more information about vso client checkout the vso guide.



6. Querying Helioviewer.org

SunPy can be used to make several basic requests using the The Helioviewer.org API including generating a PNG anddownloading a JPEG 2000 image and loading it into a SunPy Map.

A simple example of a helioviewer quiery is:

from sunpy.net.helioviewer import HelioviewerClient

hv = HelioviewerClient()hv.download_png(’2099/01/01’, 4.8, "[SDO,AIA,AIA,304,1,100]", x0=0, y0=0, width=512, height=512)

This downloads a PNG image of the latest AIA 304 image available on Helioviewer.org in the download_png command4.8 refers to the image resolution in arcseconds per pixel (larger values mean lower resolution), the “1” and “100” inthe layer string refer to the visibility (visible/hidden) and opacity, x0 and y0 are the center points about which to focusand the width and height are the pixel values for the image dimensions.

The result is:


http://helioviewer.org/api/http://wiki.helioviewer.org/wiki/JPEG_2000


For more information checkout the helioviewer guide.

1.1.3 Plotting in SunPy

SunPy makes use of matplotlib for all of its plotting needs as such tries to follow the matplotlib plotting philosophy. Itis therefore useful to go over how matplotlib works as background.

1. Matplotlib Tutorial

The tutorial provided here is a summary of one that can be found in the matplotlib usage documentation.

Matplotlib provides two main pathways for plotting. One is meant for interactive use (e.g. command-line) and the otherfor non-interactive use (e.g. modules). It is important to recognize though that the interactive-use pathway (referred



to as pyplot) just provides shortcuts doing many of the more advanced non-interactive functions in the background.It is therefore possible to switch between the two as necessary and convenient and it is possible to use pyplot in non-interactive way. In this manner pyplot is just a shortcut making it quicker to set up plot axes and figures. In order to getaccess to the full interactive capabilities of pyplot it is necessary to turn this feature on. This will be discussed below.Pylab is another matplotlib usage scenario but it is essentially just pyplot with the interactive capabilities turned onand numpy and matplotlib imported into the main namespace.

2. Pyplot

Here is an example of pyplot usage

import matplotlib.pyplot as plt

plt.plot(range(10), range(10))plt.title("A simple Plot")plt.show()

The show() command open a plot on the screen and blocks execution (meaning you can’t do anything with the promptor your script freezes) until the plot window is closed. For reasons that are not very clear, the creators of matplotlibdesigned the show() command so that it would only work once. If you were to call show() on the plt object againafter the above code is executed nothing happens. Apparently, this confusing behavior is something that the matplotlibdevs get complaints about often and so this may change in the future (or may already have changed depending on yourchoice of backend). A discussion about this can be found here. Don’t be confused by another command called draw().This is only used while in interactive mode.

To turn on interactivity for pyplot use the command

plt.ion()

In interactive mode, the plot will appear at the first plot() command and most commands will update the plot as youcall them. Here is an example

plt.plot(range(10), range(10))plt.title("Simple Plot")

In this example, you’ll see that the title appears right on the plot when you call it. Note that in this case the show com-mand is useless as the plot shows up right when you create it. Also note that some commands will not automaticallyupdate the plot and you have to use the draw() command. The following command

plt.ioff()

turns off interactivity.

3. Advanced Pyplot

If you need more fine-grained control over plots the recommended path is to use pyplot and access the figures and axesobjects. Here is an example

import matplotlib.pyplot as pltimport numpy as np

x = np.arange(0, 10, 0.2)y = np.sin(x)

fig = plt.figure()ax = fig.add_subplot(111)ax.plot(x, y)



plt.show()

Figure is the top-level container for all plot elements and axes is the top-level container for a particular plot. So theabove example, creates a figure then creates an axes and then uses the pyplot plot() method to populate the plot inax. You generally don’t need to mess with the figure object but with this method you now have your hands on the axobject so you can do this like change the labels on the x and y axes or add a legend, etc. do whatever you want to it. Inthe previous section, pyplot took care of creating these objects for you so you don’t have to worry about creating themyourself.

4. SunPy Plotting Standards

To be consistent with matplotlib, SunPy has developed a standard plotting policy which supports both simple andadvanced matplotlib usage.

5. peek()

For quick and easy access to a plot all sunpy base objects (e.g. map, spectra, lightcurve) define their own peek()command. For example you can do the following

import sunpy

smap = sunpy.make_map(sunpy.EIT_195_IMAGE)smap.peek(draw_limb=True)

This creates a plot window with all axes defined, a plot title, and the image of the map data all defined by the contentsof the map. As this is command makes use of show(), in non-interactive mode the plot window blocks and must beclosed before doing anything else. This is meant as a quick way to visualize the contents of a sunpy object you’vecreated.

6. plot()

For more advanced plotting the base sunpy objects also provide a plot() command. This command is similar to thepyplot plot() command in that it will create a figure and axes object for you if you haven’t already. It returns a figureobject and does not create a plot window. With the figure object in your hands you can reach in and grab the axes andtherefore manipulate the plot as you see fit. Here is an example of this at work

import sunpyimport matplotlib.pyplot as plt

smap = sunpy.make_map(sunpy.EIT_195_IMAGE)smap.plot()smap.draw_limb()

plt.show()

This output of this example is equivalent to one in the previous section. The map.plot() command is equivalent toax.plot(x,y) command which we introduced in section 3. Similar to that command it will create a figure for you if youhaven’t created on yourself. For advanced plotting you’ll want to create it yourself.

fig = plt.figure()ax = plt.subplot(1,1,1)

smap.plot()plt.colorbar()



ax.plot([-1000,1000], [0,0], color="white")

plt.show()

The above a plot of line across the map. Using the fig.gca() command to get access to the axes object most anythingcan be done to the plot and the plot can be displayed as usual using the show() command. Here is another example

from matplotlib import patchesfig = plt.figure()ax = plt.subplot(1,1,1)

smap.plot()rect = patches.Rectangle([-350, -650], 500, 500, color = ’white’, fill=False)ax.add_artist(rect)

plt.show()

Finally, here is a more complex example, starting from the beginning:

from matplotlib import patchesimport sunpyimport matplotlib.pyplot as pltsmap = sunpy.make_map(sunpy.AIA_171_IMAGE)submap = map.submap([-100-250, -100+250], [-400-250, -400+250])rect = patches.Rectangle([-100-250, -400-250], 500, 500, color = ’white’, fill=False)

fig = plt.figure()ax1 = fig.add_subplot(2,1,1)smap.plot()ax1.add_artist(rect)

ax2 = fig.add_subplot(2,1,2)submap.plot()submap.draw_grid(grid_spacing=10)ax2.set_title(’submap’)fig.subplots_adjust(hspace=0.4)

plt.show()

The above example creates two side by side plots one with the overall view of the Sun with a small area marked witha white box. That smaller view is then shown in the plot below it. The spacing between the two plots is controlled byfig.subplots_adjust().

7. Specifying a Colormap

There are a number of color maps defined in SunPy which are used for data from particular missions (e.g. SDO/AIA).A simple example on how to use the color maps provided by SunPy:

from sunpy.cm import cm

# cmlist is a dictionary with all of the color tables# to list all of the keys of the dictionarycm.cmlist.keys()

# to grab a particular colortable thencmap = cm.cmlist.get(’sdoaia94’)



# you can also get a visual representation of all of the color tablescm.show_colormaps()

These can be used with the standard commands to change the colormap:

import sunpyfrom sunpy.cm import cm

cmap = cm.cmlist.get(’sdoaia94’)smap = sunpy.make_map(sunpy.AIA_171_IMAGE)



fig = plt.figure()ax = plt.subplot(1,1,1)smap.plot(cmap=cmap)plt.show()

1.1.4 Time in SunPy

Working with times and time ranges is a standard task in solar data analysis as such SunPy strives to provide convenientand easy methods to do the simple stuff. Python already provides an object for a time or date through the datetimeobject. SunPy builds upon its functionality.

1. Parsing Times

Solar data is associated with a number of different time formats. SunPy provides a simple parsing function which candeal with most every format that a user may encounter. Called parse_time(), this function takes a string as input andreturns a datetime object. Here are few examples of formats which parse_time() accepts:

from sunpy.time import *parse_time(’2007-05-04T21:08:12’)parse_time(’2007/05/04T21:08:12’)parse_time(’20070504T210812’)parse_time(’2007-May-04 21:08:12’)parse_time(’20070504_210812’)

Each of the above returns the same datetime object. All SunPy functions which require time as an input sanitize theinput using parse_time. You can also pass it a datetime object directly and it will simply hand it right back to you. Forusers of IDL, this function is meant to the be the equivalent to SSW’s anytim().

2. Time Ranges

A very standard task in data analysis is to have to deal with pairs of times or time ranges. This occurs very often withplotting or when searching for data. To deal with time ranges SunPy provides the TimeRange object. A time rangeobject can be created very easily by providing it with two time strings, a start time and an end time:

time_range = TimeRange(’2010/03/04 00:10’, ’2010/03/04 00:20’)

You can also pass the start and end times as a tuple:

time_range = TimeRange((’2010/03/04 00:10’, ’2010/03/04 00:20’))

This object makes use of parse_time() so it can accept a wide variety of time formats. A time range object can also becreated by providing a start time and a duration. The duration must be provided as a timedelta object or as a numberof seconds so for example:

time_range = TimeRange(’2010/03/04 00:10’, 400)

or:

from datetime import timedeltatime_range = TimeRange(’2010/03/04 00:10’, timedelta(0,400))

The time range objects provides a number of useful functions. For example, you can easily get the time at the centerof your interval or the length of your interval in minutes or days or seconds:


http://docs.python.org/2/library/datetime.htmlhttp://docs.python.org/2/library/datetime.htmlhttp://docs.python.org/2/library/datetime.html#datetime.timedelta


time_range.center()time_range.minutes()time_range.days()time_range.seconds()

It also makes it easy to create new time ranges. The functions next() and previous() do an inplace update to the objectby either adding or subtracting the same time interval . This could be useful if you need to step through a number oftime ranges. For example, if you needed time ranges that spanned 30 minutes over a period of 4 hours you could do:

for a in range(8): print(time_range.next())

Check out the code reference for the time range object for more information.

1.1.5 Using SunPy’s VSO module

The Virtual Solar Observatory (VSO) is a service which presents a homogenoeous interface to heterogeneous data-setsand services. Using the VSO, a user can query multiple data providers simultaneously, and then download the relevantdata. SunPy uses the VSO through the ‘vso’ module, which was developed through support from the European SpaceAgency Summer of Code in Space (ESA-SOCIS) 2011.

1. Setting up the VSO interaction

SunPy’s VSO module is in sunpy.net. It can be imported into your IPython session as follows:

>>> from sunpy.net import vso

2. A simple query - using the legacy query

Obtaining data via the VSO is essentially a two-stage process. In the first stage, you ask the VSO to find the data youwant. The VSO queries various data-providers looking for your data. In the second stage, you download the data,if there is any data that matches your request. The VSO client handles the particulars of how the data from the dataprovider is downloaded to your computer.

Let’s start with a very simple query. To search the VSO, you need a start time, an end time, and an instrument. Wehave provided two different syntaxes for doing this search. The first query syntax basically copies what you alreadymay be used to from Solarsoft/IDL’s VSO query client, VSO_SEARCH.pro. This is known as a ‘legacy’ query, purelybecause the syntax is based on the legacy of Solarsoft/IDL’s VSO query client. The second query syntax is much morepowerful, but slightly less familiar to Solarsoft/IDL users (which is why we have two different syntaxes).

Let’s say I want all the EIT data between 2001/01/01 and 2001/01/02 (note that you can use any format understood bythe parse_time function to specify the date and times you want). Using the legacy query syntax, this is simply

>>> client=vso.VSOClient()>>> qr=client.query_legacy(tstart=’2001/01/01’, tend=’2001/01/02’, instrument=’EIT’)

which is almost identical to what you would type in a Solarsoft/IDL session. So, what’s happening with this command?The client is going out to the web to query the VSO to ask how many files EIT images are in the archive between thestart of 2001/01/01 and the start of 2001/01/02. The same query can also be performed using a slightly differentsyntax. For example

>>> qr=client.query_legacy(’2001/1/1’, ’2001/1/2’, instrument=’EIT’)

both gives the same result. The variable “qr” is a Python list of response objects, each one of which is a record foundby the VSO. How many records have been found? You can find that out be typing



>>> qr.num_records()122

To get a little bit more information, try

>>> qr.show()

The Solarsoft legacy query has more keywords available: to find out more about the legacy query, type:

>>> help(client.query_legacy)

As an example, let’s say you just want the EIT 171 Angstrom files for that data. These files can be found by

>>> qr=client.query_legacy(tstart=’2001/01/01’, tend=’2001/01/02’, instrument=’EIT’, min_wave=’171’, max_wave=’171’, unit_wave=’Angstrom’)

which yields four results, the same as the VSO IDL client.

3. Downloading the data

Having located the data you want, you can download it using the following command:

>>> res=client.get(qr, path=’/Users/ireland/Desktop/Data/{file}.fits’)

This downloads the query results into the directory /Users/ireland/Dekstop/Data naming each downloaded file with thefilename ‘{file}’ obtained from the VSO , and appended with the suffix ‘.fits’. The ‘{file}’ option uses the file nameobtained by the VSO for each file. You can also use other properties of the query return to define the path where thedata is saved. For example, to save the data to a subdirectory named after the instrument, use

>>> res=client.get(qr, path=’/Users/ireland/Desktop/Data/{instrument}/{file}.fits’)

Note that the download process is spawned in parallel to your existing Python session. This means that the remainderof your Python script will continue as the download proceeds. This may cause a problem if the remainder of yourscript relies on the presence of the downloaded data. If you want to resume your script after all the data has beendownloaded then append ‘.wait()’ to the ‘get’ command above, i.e.,

>>> res=client.get(qr, path=’/Users/ireland/Desktop/Data/{instrument}/{file}.fits’).wait()

More information on the options available can be found through the standard Python ‘help’ command.

Using the legacy query keywords it is very easy to translate a Solarsoft/IDL VSO command into the equivalent SunPyVSO legacy query. However, more powerful queries are possible with the new query style, which is described below.

4. The new query style

The new query style makes more complex queries possible. Let’s start with translating the above legacy query into thesyntax of the new query:

>>> qr=client.query(vso.attrs.Time(’2001/1/1’, ’2001/1/2’), vso.attrs.Instrument(’eit’))

Let’s break down the arguments of client.query. The first argument:

vso.attrs.Time(‘2001/1/1’, ‘2001/1/2’)

sets the start and end times for the query (as with the legacy query, any date/time format understood by SunPy’s‘parse_time’ function can be used to specify dates and time). The second argument:

vso.attrs.Instrument(‘eit’)



sets the instrument we are looking for. So what is going on here? The notion is that a VSO query has a set of attributeobjects - described in ‘vso.attrs’ - that are specifed to construct the query. For the full list of vso attributes, use

>>> help(vso.attrs)

Note that due to quirks at the VSO, we do not recommend that the extent object ‘vso.attrs.Extent’ be in your query.Instead, we recommend that any extent filtering you need to do be done on the queries made without setting a valueto the vso.attrs.Extent object. As we will see, the new-style query can take more than two arguments, each argumentseparated from the other by a comma. Each of those arguments are chained together using a logical “AND”.

The new-style query allows you to combine these VSO attribute objects in complex ways that are not possible withthe legacy query style.

So, let’s look for the EIT and MDI data on the same day:

>>> qr=client.query(vso.attrs.Time(’2001/1/1’, ’2001/1/2’), vso.attrs.Instrument(’eit’) | vso.attrs.Instrument(’mdi’))>>> qr.num_records()233>>> qr.show()

The two instrument types are joined together by the operator ‘|’. This is the ‘or’ operator. Think of the above query assetting a set of conditions which get passed to the VSO. Let’s say you want all the EIT data from two separate days:

>>> qr=client.query(vso.attrs.Time(’2001/1/1’, ’2001/1/2’) | vso.attrs.Time(’2007/8/9’, ’2007/8/10’), vso.attrs.Instrument(’eit’) )>>> qr.num_records()227

Each of the arguments in the new-style query can be thought of as setting conditions that the returned records mustsatisfy. You can set the wavelength; for example, to return the 171 Angstrom EIT results

>>> qr=client.query(vso.attrs.Time(’2001/1/1’, ’2001/1/2’), vso.attrs.Instrument(’eit’), vso.attrs.Wave(171,171) )>>> qr.num_records()4

The new-style query returns the same type of response as the legacy query. This means you can use the same commandand syntax as shown above to download your data.

Finally, please let us know if you encounter a bug while using the VSO capabilities of SunPy. Bugs are best reportedvia the issue tracking system on GitHub - go to https://github.com/sunpy/sunpy/issues and click on the “New Issue”button.

1.1.6 Querying Helioviewer.org with SunPy

SunPy can be used to make several basic requests using the The Helioviewer.org API including generating a PNG anddownloading a JPEG 2000 image and loading it into a SunPy Map.

To interact with the Helioviewer API, users first create a “HelioviewerClient” instance. The client instance can then beused to make various queries against the API using the same parameters one would use when making a web request.

Nearly all requests require the user to specify the data they are interested in and this can be done using one of twomethods:

1. Call “get_data_sources()” to get a list of the data that is available, and use the source id numbers referenced inthe result to refer to a particular dataset, or,

2. Specify the four components of a Helioviewer.org data source or layer: observatory, instrument, detector andmeasurement.

Let’s begin by getting a list of data sources available on the server using the get_datasources method:


https://github.com/sunpy/sunpy/issueshttp://helioviewer.org/api/http://wiki.helioviewer.org/wiki/JPEG_2000


from sunpy.net.helioviewer import HelioviewerClient

hv = HelioviewerClient()datasources = hv.get_data_sources()

# print a list of datasources and their associated idsfor observatory, instruments in datasources.items():

for inst, detectors in instruments.items():for det, measurements in detectors.items():

for meas, params in measurements.items():print("%s %s: %d" % (observatory, params[’nickname’], params[’sourceId’]))

Suppose we next want to download a PNG image of the latest AIA 304 image available on Helioviewer.org. We coulduse the explicit approach:

hv.download_png(’2099/01/01’, 4.8, "[SDO,AIA,AIA,304,1,100]", x0=0, y0=0, width=512, height=512)

Where 4.8 refers to the image resolution in arcseconds per pixel (larger values mean lower resolution), the “1” and“100” in the layer string refer to the visibility (visible/hidden) and opacity, x0 and y0 are the center points about whichto focus and the width and height are the pixel values for the image dimensions.

The result is:



If we find that the source id for AIA 304 is is 13, we could make the same request using:

hv.download_png(’2099/01/01’, 4.8, "[13,1,100]", x0=0, y0=0, width=512, height=512)

Now suppose we wanted to create a composite PNG image using data from two different AIA wavelengths and LASCOC2 coronagraph data. The layer string is extended to include the additional data sources, and opacity is throttled downfor the second AIA layer so that it does not completely block out the lower layer:

hv.download_png(’2099/01/01’, 6, "[SDO,AIA,AIA,304,1,100],[SDO,AIA,AIA,193,1,50],[SOHO,LASCO,C2,white-light,1,100]", x0=0, y0=0, width=768, height=768)

The result looks like:



Next, let’s see how we can download a JPEG 2000 image and load it into a SunPy Map object.

The overall syntax is similar to the download_png request, expect instead of specifying a single string to indicatewhich layers to use, here we can specify the values as separate keyword arguments:

filepath = hv.download_jp2(’2012/07/05 00:30:00’, observatory=’SDO’, instrument=’HMI’, detector=’HMI’, measurement=’continuum’)hmi = sunpy.make_map(filepath)hmi.submap([200,550],[-400,-200]).show()



For more information about using querying Helioviewer.org, see the Helioviewer.org API documentation at:http://helioviewer.org/api/.

1.1.7 Maps

Maps in SunPy are spatially-aware data arrays. In other words, they are 2-dimensional data associated with a coordi-nate system. In this guide, we will cover some of the basic functionality of maps. Once you’ve read through this guidecheck out the code reference for a more thorough look at SunPy maps.

Data Support

The map object currently supports the following data sources

• SDO/AIA

• STEREO/EUVI, STEREO/COR

• Hinode/XRT

• SOHO/EIT, SOHO/LASCO, SOHO/MDI

• PROBA2/SWAP

• Yohkoh/SXT

1. Creating maps

SunPy contains a number of example fits files. To make things easy, SunPy includes several example files which areused throughout the docs. These files have names like sunpy.AIA_171_IMAGE and sunpy.RHESSI_IMAGE.To create the sample AIA map type the following into your interactive Python shell:

import sunpymy_map = sunpy.make_map(sunpy.AIA_171_IMAGE)


http://helioviewer.org/api/


The variable my_map is a SunPy map. To create a map from a local fits file try something like the following

my_map = sunpy.make_map(’/mydirectory/mymap.fits’)

SunPy should automatically detect the type of file (e.g. fits), what instrument it is associated with (e.g. AIA, EIT,LASCO) and will automatically look in the appropriate places for the fits keywords it needs to interpret the coordinatesystem. If the type of fits file is not recognized then SunPy will try some default fits keywords but results may vary. Thelist of files which are currently supported by SunPy can be found by looking at the documentation for make_map().SunPy can also create maps from the jpg2000 files from helioviewer.org.

2. Creating Custom Maps

It is also possible to create maps using custom data from a simulation for example. To do this you need to providemake_map() with both the data array as well as some basic header information. If no header is given then some defaultvalues as assumed. Here is a simple example:

import numpy as npdata = np.arange(0,100).reshape(10,10)header = {’cdelt1’: 10, ’cdelt2’: 10, ’telescop’:’sunpy’}my_map = sunpy.make_map(data, header)

The format of the header follows the fits standard.

2. Inspecting maps

A map contains a number of data-associated attributes. To get a quick look at your map simply type:

my_map = sunpy.make_map(sunpy.AIA_171_IMAGE)my_map

This will show a representation of the data as well as some of its associated attributes. A number of other attributesare also available, for example the date, exposure time, map center, xrange, yrange other:

map_date = my_map.datemap_exptime = my_map.exposure_timemap_center = my_map.centermap_xrange = my_map.xrangemap_yrange = my_map.yrange

To get a list of all of the attributes check the documentation by typing:

help(my_map)

The header of the map can be accessed by using the following method:

header = my_map.get_header()

This returns a dictionary with the header information as read from the source file.

3. Getting at the data

As a SunPy map inherits from the NumPy ndarray it can be accessed in the same way, through indexing. For example,to get the 0th element in the array

my_map[0,0]my_map[0][0]



One important fact to remember which is intially confusing is that the first index is for the y direction while the secondindex is for the x direction! For more information about indexing please refer to the Numpy documentation. You canalso check on the shape of the array with

my_map.shape

If you’d like to rip the data out of the SunPy map to use elsewhere you can use:

import numpy as npvar = np.array(aia_map)

The variable var is now simply a Numpy ndarray. Fortunately this is not generally necessary as the SunPy map inheritsdirectly from the NumPy ndarray and therefore applying NumPy methods directly on the SunPy map is generally safe.So one could, for example, apply the following code:

import numpy as nplog_map = np.log(my_map)

The np.log() function will be applied on each element in the map data array as expected. A few NumPy ndarraymethods are also directly available such as, for example, to find the maximum and mean in the map data just use:

my_map.min()my_map.mean()

This is the advantage of inheritance!

4. Creating a plot of your map

The SunPy map object has its own built-in plot methods so that it is easy to quickly view your map on the screen. Tocreate a plot just type:

my_map.peek()

This will open a matplotlib plot right on your screen. In addition, to enable users to modify the plot it is possible tograb the matplotlib figure object by using the plot() command instead of the show() command. This makes it possibleto use the SunPy plot as the foundation for a more complicated figure.

5. Overlaying Maps

The make_map() method described above can also handle a list of maps. If the maps are of a different type (e.g.different instruments) than the result of make_map is what we call a Composite Map. So for example to create asimple composite map:

my_maps = sunpy.make_map([sunpy.EIT_195_IMAGE, sunpy.RHESSI_IMAGE])

A Composite map is different from a regular map and therefore different associated methods. To list which maps arepart of your composite map use:

my_maps.list_maps()

Similar to all SunPy data objects, the composite map also has an associated show() method and a number of associatedmethods to customize your plot. For example, the following code turns adds a new map, sets its transparency to 25%,turns on contours from 50% to 90% for the second map, and then plots the result:

my_maps.add_map(sunpy.AIA_171_IMAGE)my_maps.set_alpha(2,0.5)



my_maps.set_levels(1,[50,60,70,80,90], percent = True)my_maps.peek()

This is not a particularly pretty plot but it shows what SunPy can do!

5. Working with your map

Part of the philosophy of the map object is to provide most of the basic functionality that a scientist would wanttherefore a map also contains a number of map-specific methods such as resizing a map or grabbing a subview. To geta list of the methods available for a map type:

help(my_map)

and check out the methods section!

1.1.8 Using SunPy’s HEK module

The Heliophysics Event Knowledgebase (HEK) is a repository of feature and event information concerning the Sun.Entries are generated both by automated algorithms and human observers. SunPy accesses this information throughthe ‘hek’ module, which was developed through support from the European Space Agency Summer of Code in Space(ESA-SOCIS) 2011.

1. Setting up the client

SunPy’s HEK module is in sunpy.net. It can be imported into your IPython session as follows:

>>> from sunpy.net import hek>>> client = hek.HEKClient()

This creates a client that we will use to interact with the HEK.

2. A simple query

To search the HEK, you need a start time, an end time, and an event type. Times are specified as Python datetimeobjects. Event types are specified as upper case, two letter strings, and are identical to the two letter abbreviationsfound at the HEK website, http://www.lmsal.com/hek/VOEvent_Spec.html.

>>> tstart = ’2011/08/09 07:23:56’>>> tend = ’2011/08/09 12:40:29’>>> event_type = ’FL’>>> result = client.query(hek.attrs.Time(tstart,tend),hek.attrs.EventType(event_type))

The first line in the block of code above imports the datetime module. The second and third lines define the searchstart and end times. The fourth line specifies the event type, in this ‘FL’ or flare. Line 5 goes out to the web, contactsthe HEK, and queries it for the information you have requested. Event data for ALL flares available in the HEK withinthe time range 2011/08/09 07:23: 56 UT - 2011/08/09 12:40:20 UT will be returned, regardless of which featurerecognition method used to detect the flare.

Let’s break down the arguments of client.query. The first argument:

hek.attrs.Time(tstart,tend)

sets the start and end times for the query. The second argument:

hek.attrs.EventType(event_type)


http://www.lmsal.com/hek/VOEvent_Spec.html


sets the type of event to look for. Since we have defined event_type = ‘FL’, this sets the query to look for flares. Wecould have also set the flare event type using the syntax

hek.attrs.FL

There is more on the attributes of hek.attrs in section 4 of this guide.

3. The result

So, how many flare detections did the query turn up?

>>> len(result)19

The object returned by the above query is a list of Python dictionary objects. Each dictionary consists of key-valuepairs that exactly correspond to the parameters listed at http://www.lmsal.com/hek/VOEvent_Spec.html. You caninspect all the dictionary keys very simply:

>>> result[0].keys()[u’skel_startc1’,u’concept’,u’frm_versionnumber’,u’hrc_coord’,u’refs_orig’,....

and so on. Remember, the HEK query we made returns all the flares in the time-range stored in the HEK, regardlessof the feature recognition method. The HEK parameter which stores the the feature recognition method is called“frm_name”. Using list comprehensions (which are very cool), it is easy to get a list of the feature recognitionmethods used to find each of the flares in the result object, for example:

>>> [elem["frm_name"] for elem in result][u’asainz’,u’asainz’,u’asainz’,u’asainz’,u’asainz’,u’asainz’,u’asainz’,u’SSW Latest Events’,u’SEC standard’,u’Flare Detective - Trigger Module’,u’Flare Detective - Trigger Module’,u’SSW Latest Events’,u’SEC standard’,u’Flare Detective - Trigger Module’,u’Flare Detective - Trigger Module’,u’Flare Detective - Trigger Module’,u’Flare Detective - Trigger Module’,u’Flare Detective - Trigger Module’]

It is likely each flare on the Sun was actually detected multiple times by many different methods.

4. More complex queries

The HEK client allows you to make more complex queries. There are two key features you need to know in order tomake use of the full power of the HEK client. Firstly, the attribute module - hek.attrs - describes ALL the parame-ters stored by the HEK as listed in http://www.lmsal.com/hek/VOEvent_Spec.html, and the HEK client makes theseparameters searchable.


http://www.lmsal.com/hek/VOEvent_Spec.htmlhttp://www.lmsal.com/hek/VOEvent_Spec.html


To explain this, let’s have a closer look at hek.attrs. The help command is your friend here; scroll down to sectionDATA you will see:

>>> help(hek.attrs)AR = Area = Bound = BoundBox = CC = CD = CE = CH = CJ = CR = CW = EF = ER = Event = FA = FE = FI = FL = FRM = etc etc...

The object hek.attrs knows the attributes of the HEK. You’ll see that one of the attributes is a flare object

FL =

We can replace hek.attrs.EventType(‘FL’) with hek.attrs.FL - they do the same thing, setting the query to look for flareevents. Both methods of setting the event type are provided as a convenience

Let’s look further at the FRM attribute:

>>> help(hek.attrs.FRM)Help on FRM in module sunpy.net.hek.attrs object:class FRM(__builtin__.object)| Data descriptors defined here:|| __dict__| dictionary for instance variables (if defined)|| __weakref__| list of weak references to the object (if defined)|| ----------------------------------------------------------------------| Data and other attributes defined here:|| Contact = || HumanFlag = || Identifier = || Institute = || Name = || ParamSet = |



| SpecificID = || URL = || VersionNumber =

Let’s say I am only interested in those flares identified by the SSW Latest Events tool. I can retrieve those entries onlyfrom the HEK with the following command:

>>> result = client.query( hek.attrs.Time(tstart,tend), hek.attrs.EventType(event_type), hek.attrs.FRM.Name == ’SSW Latest Events’)>>> len(result)2

We can also retrieve all the entries in the time range which were not made by SSW Latest Events with the followingcommand:

>>> result = client.query( hek.attrs.Time(tstart,tend), hek.attrs.EventType(event_type),hek.attrs.FRM.Name != ’SSW Latest Events’)>>> len(result)17

We are using Python’s comparison operators to filter the returns from the HEK client. Other comparisons are possible.For example, let’s say I want all the flares that have a peak flux of over 4000.0:

>>> result = client.query(hek.attrs.Time(tstart,tend), hek.attrs.EventType(event_type), hek.attrs.FL.PeakFlux > 4000.0)>>> len(result)1

Multiple comparisons can be included. For example, let’s say I want all the flares with a peak flux above 1000 ANDwest of 800 arcseconds from disk center of the Sun

>>> result = client.query(hek.attrs.Time(tstart,tend), hek.attrs.EventType(event_type), hek.attrs.Event.Coord1 > 800, hek.attrs.FL.PeakFlux > 1000.0)

Multiple comparison operators can be used to filter the results back from the HEK.

The second important feature about the HEK client is that the comparisons we’ve made above can be combined usingPython’s logical operators. This makes complex queries easy to create. However, some caution is advisable. Let’s sayI want all the flares west of 50 arcseconds OR have a peak flux over 1000.0:

>>> result = client.query(hek.attrs.Time(tstart,tend), hek.attrs.EventType(event_type), (hek.attrs.Event.Coord1 > 50) or (hek.attrs.FL.PeakFlux > 1000.0) )

and as a check

>>> [elem["fl_peakflux"] for elem in result][None,None,None,None,None,None,None,2326.86,1698.83,None,None,2360.49,3242.64,1375.93,6275.98,923.984]



>>> [elem["event_coord1"] for elem in result][51,51,51,924,924,924,69,883.2,883.2,69,69,883.2,883.2,883.2,883.2,883.2]

Note that some of the fluxes are returned as “None”. This is because some feature recognition methods for flares donot report the peak flux. However, because the location of event_coord1 is greater than 50, the entry from the HEKfor that flare detection is returned.

Let’s say we want all the flares west of 50 arcseconds AND have a peak flux over 1000.0:

>>> result = client.query(hek.attrs.Time(tstart,tend), hek.attrs.EventType(event_type), (hek.attrs.Event.Coord1 > 50) and (hek.attrs.FL.PeakFlux > 1000.0) )

>>> [elem["fl_peakflux"] for elem in result][2326.86, 1698.83, 2360.49, 3242.64, 1375.93, 6275.98]>>> [elem["event_coord1"] for elem in result][883.2, 883.2, 883.2, 883.2, 883.2, 883.2]

In this case none of the peak fluxes are returned with the value “None”. Since we are using an “and” logical operatorwe need a result from the “(hek.attrs.FL.PeakFlux > 1000.0)” filter. Flares that have “None” for a peak flux cannotprovide this, and so are excluded. The “None” type in this context effectively means “Don’t know”; in such cases theclient returns only those results from the HEK that definitely satisfy the criteria passed to it.

1.1.9 Spectra

Warning: This module is under development! Use at your own risk.

Spectrograms

SunPy currently supports reading dynamic spectra from e-Callisto instruments. The main class that is used for this isCallistoSpectrogram. SunPy also comes with an example image that shows a radio burst observed at RosseObservatory (aka. BIR; Birr Castle, Co. Offaly, Ireland) that can be found in sunpy.CALLISTO_IMAGE:

from matplotlib import pyplot as pltimport sunpyfrom sunpy.spectra.sources.callisto import CallistoSpectrogramimage = CallistoSpectrogram.read(sunpy.CALLISTO_IMAGE)

You can now view the image by using the show() method.


http://www.e-callisto.org/http://rosseobservatory.ie/http://rosseobservatory.ie/


image.show()

We now notice that there seems to be something interesting that has been cut off at the corner of the image, so we usethe extend method to request more data from the server. It optionally takes the amount of minutes we want to requestfrom the server (negative values mean we want to add data that was registered before our existing local data), if noneare given it defaults to 15 minutes (the size of one e-Callisto file).:

more = image.extend()more.show()

We will, for the purposes of this demonstration, continue working with the original image, though.

You can then perform automatic constant background subtraction by using the subtract_bg() method. The re-sulting image will be clipped at 0 using the min_ parameter of show in order to avoid negative values.:

nobg = image.subtract_bg()nobg.show(min_=0)



If you want to see the background determined by the automatic subtraction, you can use the auto_const_bg()method and visualize the resulting data using pyplot.plot().:

plt.figure()bg = image.auto_const_bg()plt.plot(image.freq_axis, bg)xlabel("Frequency [MHz]")ylabel("Intensity")plt.show() # This might not be necessary if you are using pylab.

Now let us say we want to isolate the interesting bit (which starts around 10:38) from the boring background; thereis a method called in_interval() that allows us to take the part of an image that is within a specified interval.Leaving out the second argument it defaults to the end time of the file.:

interesting = nobg.in_interval("10:38")interesting.show(min_=0)

To get rid of the noise, we could also clip low intensities.:



interesting.show(min_=20)

If we want more context, we can also join together different images into a large one in time (note that this does morethan just concatenating the array and the axes – it also considers possible overlap or gaps).:

c1 = CallistoSpectrogram.read("BIR_20110922_101500_01.fit")c2 = CallistoSpectrogram.read("BIR_20110922_103000_01.fit")d = CallistoSpectrogram.join_many([c1, c2])d.show()

We could also get the from_range method to get data between those two points directly from the archive and joinedtogether (though that will fetch all frequencies of BIR).:

d = CallistoSpectrogram.from_range("BIR", "2011-09-22T10:15:00", "2011-09-22T10:45:00")d.show()



The plot() and show() methods return a special kind of figure that offers convenience features needed for an-alyzing spectrograms, a SpectroFigure. By using its time_freq(), we can select points on the figure andfrequency-time information of them will be returned as a TimeFreq. Time is stored as offsets in seconds fromTimeFreq.start.:

fig = image.show()time_freq = fig.time_freq()# Select points.time_freq.time#array([ 0. , 54.5 , 104. , 163.25])time_freq.freq#array([ 68.76923077, 59.29888786, 48.50092678, 36.46385542])

We can then quickly visualize this using the show() method:

time_freq.show(marker=’o’, linestyle=’--’)



1.1.10 Customizing sunpy

The sunpyrc file

Sunpy uses sunpyrc configuration files to customize certain properties. You can control a number of key features ofSunPy such as where your data will download to. SunPy looks for sunpyrc in two locations, in the following order:

1. .sunpy/sunpyrc, for the user’s default customizations.

2. INSTALL/sunpy/data/sunpyrc, where INSTALL is something like/usr/lib/python2.5/site-packages on Linux, and maybe C:\Python25\Lib\site-packageson Windows. Every time you install SunPy, this file will be overwritten, so if you want your customizations tobe saved, please move this file to your .sunpyrc directory.

To display where the currently active sunpyrc file was loaded from, one can do the following:

>>> import sunpy>>> sunpy.print_config()

The default sunpyrc file lives in sunpy/data/. We recommend that you make a copy of this file and put it where Sunpywill find it. See below for the example config file.

Dynamic settings

You can also dynamically change the default settings in a python script or interactively from the python shell. Allof the settings are stored in a Python ConfigParser instance called sunpy.config, which is global to the sunpypackage. Settings can be modified directly, for example:

import sunpysunpy.config.set(’downloads’, ’download_dir’, ’/home/user/Downloads’)

A sample sunpyrc file

;; SunPy Configuration;; This is a sample sunpy configuration file - you can find a copy; of it on your system in site-packages/sunpy/data/sunpyrc. If you edit it; there, please note that it will be overridden in your next install.; If you want to keep a permanent local copy that will not be; over-written, place it in HOME/.sunpy/sunpyrc (unix/linux; like systems) and C:\Documents and Settings\yourname\.sunpy; (win32 systems).;; Note that any relative filepaths specified in the SunPy configuration file; will be relative to SunPy’s working directory.;

;;;;;;;;;;;;;;;;;;;; General Options ;;;;;;;;;;;;;;;;;;;;[general]

; The SunPy working directory is the parent directory where all generated; and download files will be stored.; Default Value: /sunpy



; working_dir = /home/$USER/sunpy

;;;;;;;;;;;;;; Downloads ;;;;;;;;;;;;;;[downloads]

; Location to save download data to. Path should be specified relative to the; SunPy working directory.; Default value: data/;download_dir = /tmpdownload_dir = data

1.1.11 Troubleshooting

Contents

• Troubleshooting– Obtaining sunpy version– System Info– sunpy install location– .sunpy directory location– Report a problem

Obtaining sunpy version

To find out your sunpy version number, import it and print the __version__ attribute:

import sunpysunpy.__version__

System Info

To quickly collect information on your system, you can use our convienience function system_info which you canrun through:

import sunpysunpy.util.system_info()

The output should look something like:

==========================================================SunPy Installation Information

Sunday, 18. November 2012 11:06PM UT==========================================================

###########General

###########OS: Mac OS X 10.8.2 (i386)Python: 2.7.3 (64bit)



####################Required libraries

####################SunPy: 0.1NumPy: 1.6.2SciPy: 0.10.1Matplotlib: 1.2.xPyFITS: 3.0.8pandas: 0.8.1

#######################Recommended libraries

#######################beautifulsoup4: 4.1.1PIL: NOT INSTALLEDPyQt: 4.9.4SUDS: 0.4’

This information is especially useful if you are running into a bug and need help.

sunpy install location

You can find what directory sunpy is installed in by importing it and printing the __file__ attribute:

import sunpysunpy.__file__

.sunpy directory location

Each user should have a .sunpy/ directory which should contain a sunpyrc file. To locate your .sunpy/ directory,use sunpy.print_config():

import sunpy as sunsun.print_config()

The output should look something like:

FILES USED:sunpy/data/sunpyrc

CONFIGURATION:[general]working_dir = /Users/schriste/sunpy

[downloads]download_dir = /Users/schriste/sunpy/data

On unix-like systems, this directory is generally located in your HOME directory. On windows, it is in your documentsand settings directory by default.

If you would like to use a different configuration directory, you can do so by specifying the location in yourSUNPY_CONFIGDIR environment variable.



Report a problem

If you are having a problem with sunpy, search the mailing lists first: it is possible that someone else has already runinto your problem.

If not, please provide the following information in your e-mail to the mailing list:

• your operating system; (Linux/UNIX users: post the output of uname -a)

• sunpy version:

import sunpysunpy.util.system_info()

• how you obtained sunpy.

• any customizations to your sunpyrc file (see Customizing sunpy).

• Please try to provide a minimal, standalone Python script that demonstrates the problem. This is the criticalstep. If you can’t post a piece of code that we can run and reproduce your error, the chances of getting helpare significantly diminished. Very often, the mere act of trying to minimize your code to the smallest bit thatproduces the error will help you find a bug in your code that is causing the problem.

You will likely get a faster response writing to the mailing list than filing a bug in the bug tracker. If your problem hasbeen determined to be a bug and can not be quickly solved, the issues may be filed a bug in the tracker so the issuedoesn’t get lost.

1.2 SunPy Code Reference

1.2.1 CM

cm.get_cmap(name=’sdoaia94’)Get a colormap.

Parameters name : string

The name of a color map.

Returns value : matplotlib colormap

References

http://matplotlib.sourceforge.net/api/cm_api.html

Examples

>>> import sunpy.cm as cm>>> colormap = cm.get_cmap(name = ’sdoaia94’)

cm.show_colormaps()Displays a plot of the custom color maps supported in SunPy.

Parameters None : none

Returns None : none

1.2. SunPy Code Reference 39

http://groups.google.com/forum/#!forum/sunpyhttp://github.com/sunpy/sunpy/issueshttp://matplotlib.sourceforge.net/api/cm_api.html


Examples

>>> import sunpy.cm as cm>>> cm.show_colormaps()

1.2.2 Plotman

gui

1.2.3 HEK

Querying

The HEK can be queried in a similar fashion as the VSO. Queries are constructed from fundamental attributes usingbasic logic operations. What the user ends up specifying is a logic condition the data must match to be included in theresult.

The primary interface to the HEK is the HEKClient, of which an object must be created in order to use the HEK.

>>> from sunpy.net import hek>>> client = hek.HEKClient()

Now we can use the client’s query method in order to retrieve data from the HEK. This example retrieves all AR eventsbetween the two specified times. If query receives multiple arguments those are combined using AND.

>>> res = client.query(hek.attrs.Time(’2011-09-22T09:00:00’, ’2011-09-22T11:00:00’), hek.attrs.AR)

If we, for example, also wanted CMEs in this period.

>>> res = client.query(hek.attrs.Time(’2011-09-22T09:00:00’, ’2011-09-22T11:00:00’), hek.attrs.AR | hek.attrs.CE)

Which reads out as “find datasets that are within the given dataset AND are (an AR OR a CE)”.

Module documentation

Facilities to interface with the HEK.

class sunpy.net.hek.HEKClient(url=’http://www.lmsal.com/hek/her’)Client to interact with the HEK.

Methods

query(*query) Retrieve information about records matching the criteria given in the query expression.

query(*query)Retrieve information about records matching the criteria given in the query expression. If multiple argu-ments are passed, they are connected with AND.



1.2.4 Instr

This is where libraries for individual missions resides

rhessi Provides programs to process and analyze RHESSI data.

sunpy.instr.rhessi

Provides programs to process and analyze RHESSI data.

Warning: This module is still in development!

Functions

angular_size([t]) Return the angular size of the Sun as a function ofbackprojection(calibrated_event_list[, ...]) Given a stacked calibrated event list fits file create a back projection image.get_obssum_filename(time_range) Download the RHESSI observing summary data from one of the RHESSIget_obssumm_dbase_file(time_range) Download the RHESSI observing summary database file. This file lists theget_obssumm_file(time_range) Download the RHESSI observing summary data from one of the RHESSIparse_obssumm_dbase_file(filename) Parse the RHESSI observing summary database file. This file lists theparse_obssumm_file(filename) Parse a RHESSI observation summary file.show_obssumm(data_dict) show_obssumsunearth_distance([t]) Returns the Sun Earth distance. There are a set of higher accuracy terms not included here.

Classes

TimeRange(a, b) or Timerange((a, b)) An object to handle time ranges.datetime The year, month and day arguments are required.timedelta Difference between two datetime values.

1.2.5 Input/Output

io File input and output functionsio.fits FITS File Readerio.jp2 JPEG 2000 File Reader

sunpy.io

File input and output functions

Functions

detect_filetype(filepath) Attempts to determine the type of data contained in a fileread_file(filepath) Determines the filetype and reads in the fileread_file_header(filepath) Reads the header from a given file



Exceptions

InvalidJPEG2000FileExtension Exception to raise when JPEG 2000 is detected but contains an invalidUnrecognizedFileTypeError Exception to raise when an unknown file type is encountered

sunpy.io.fits

FITS File Reader

Notes

PyFITS [1] Due to the way PyFITS works with images the header dictionary may differ depending on whether isaccessed before or after the fits[0].data is requested. If the header is read before the data then the original headerwill be returned. If the header is read after the data has been accessed then the data will have been scaled and amodified header reflecting these changes will be returned: BITPIX may differ and BSCALE and B_ZERO maybe dropped in the modified version.

[2] The verify(‘fix’) call attempts to handle violations of the FITS standard. For example, nan values will beconverted to “nan” strings. Attempting to cast a pyfits header to a dictionary while it contains invalid headertags will result in an error so verifying it early on makes the header easier to work with later.

References

http://stackoverflow.com/questions/456672/class-factory-in-pythonhttp://stsdas.stsci.edu/download/wikidocs/The_PyFITS_Handbook.pdf

Functions

get_header(filepath) Returns the header for a given fileread(filepath) Reads in the file at the specified location

Classes

MapHeader(header) A dictionary-like class for working with FITS, etc headers

sunpy.io.jp2

JPEG 2000 File Reader

Functions

get_data(filepath[, j2k_to_image]) Extracts the data portion of a JPEG 2000 imageget_header(filepath) Reads the header in and saves it as a dictionaryis_float(s) Check to see if a string value is a valid float

Continued on next page


http://stackoverflow.com/questions/456672/class-factory-in-pythonhttp://stsdas.stsci.edu/download/wikidocs/The_PyFITS_Handbook.pdf


Table 1.11 – continued from previous pageread(filepath) Reads in the file at the specified locationread_xmlbox(filepath, root) Extracts the XML box from a JPEG 2000 image.which(program) Checks for existence of executablexml_to_dict(xmlstring) Converts an XML string to a Python dictionary

Classes

MapHeader(header) A dictionary-like class for working with FITS, etc headers

Exceptions

MissingOpenJPEGBinaryError Unable to find OpenJPEG. Please ensure that OpenJPEG binaries are installed in a

1.2.6 Light Curves

Overview

One of core classes in SunPy is a LightCurve...

Creating LightCurve Objects

SunPy LightCurve can be created either the generic LightCurve constructory, or any data-specific variant.

LightCurve Classes

In addition to the generic LightCurve class, there are also a number of instrument-specific subclasses. Each ofthese are described below.

LightCurve

class sunpy.lightcurve.LightCurve(filepath)A generic light curve object.

Parameters args : filepath, url, or start and end dates

The input for a LightCurve object should either be a filepath, a URL, or a date range tobe queried for the particular instrument.

References

http://pandas.pydata.org/pandas-docs/dev/dsintro.html


http://pandas.pydata.org/pandas-docs/dev/dsintro.html


Examples

import sunpy import datetime base = datetime.datetime.today() dates = [base - datetime.timedelta(minutes=x)for x in range(0, 24 * 60)] light_curve = sunpy.lightcurve.LightCurve.create( {“param1”: range(24 * 60)},index=dates) light_curve.show()

Attributes

Methods

create(*args, **kwargs)extract(a) Extract a set of particular columns from the DataFramefrom_data(data[, index, header])from_dataframe(dataframe[, header])from_file(filename)from_range(from_, to, **kwargs)from_time(time, **kwargs)from_timerange(timerange, **kwargs)from_url(url, **kwargs)from_yesterday()peek(**kwargs) Displays the light curve in a new figureplot([axes]) Plot a plot of the light curvetime_range() Returns the start and end times of the LightCurve as a TimeRangetruncate(a[, b]) Returns a truncated version of the timeseries object

LYRALightCurve

class sunpy.lightcurve.LYRALightCurve(data, header=None)LYRA light curve definition

References

http://proba2.sidc.be/data/LYRA

Examples

import sunpy lyra = sunpy.lightcurve.LYRALightCurve.create() lyra =sunpy.lightcurve.LYRALightCurve.create(‘~/Data/lyra/lyra_20110810-000000_lev2_std.fits’) lyra =sunpy.lightcurve.LYRALightCurve.create(‘2011/08/10’) lyra = sunpy.lightcurve.LYRALightCurve.create(“http://proba2.oma.be/lyra/data/bsd/2011/08/10/lyra_20110810-000000_lev2_std.fits”) lyra.peek()

Methods

create(*args, **kwargs)extract(a) Extract a set of particular columns from the DataFramefrom_data(data[, index, header])

Continued on next page


http://proba2.sidc.be/data/LYRAhttp://proba2.oma.be/lyra/data/bsd/2011/08/10/lyra_20110810-000000_lev2_std.fitshttp://proba2.oma.be/lyra/data/bsd/2011/08/10/lyra_20110810-000000_lev2_std.fits


Table 1.15 – continued from previous pagefrom_dataframe(dataframe[, header])from_file(filename)from_range(from_, to, **kwargs)from_time(time, **kwargs)from_timerange(timerange, **kwargs)from_url(url, **kwargs)from_yesterday()peek([names]) Plots the LYRA dataplot([axes]) Plot a plot of the light curvetime_range() Returns the start and end times of the LightCurve as a TimeRangetruncate(a[, b]) Returns a truncated version of the timeseries object

LogicalLightCurve

class sunpy.lightcurve.LogicalLightCurve(data, header=None)Logical light curve. Originated from a need to analyze the times of HEK results, where ‘True’ indicates an eventwas observed, and ‘False’ indicates an event was not observed.

Examples

import sunpy lyra = sunpy.lightcurve.LogicalLightCurve.create()

Methods

complement() Define the complement of the passed lightcurvecreate(*args, **kwargs)extract(a) Extract a set of particular columns from the DataFramefrom_data(data[, index, header])from_dataframe(dataframe[, header])from_file(filename)from_range(from_, to, **kwargs)from_time(time, **kwargs)from_timerange(timerange, **kwargs)from_url(url, **kwargs)from_yesterday()peek(**kwargs) Displays the light curve in a new figureplot([axes]) Plot a plot of the light curvetime_range() Returns the start and end times of the LightCurve as a TimeRangetimes() Label all the periods of time that have the value ‘True’. Returntruncate(a[, b]) Returns a truncated version of the timeseries object

GOESLightCurve

class sunpy.lightcurve.GOESLightCurve(data, header=None)GOES light curve definition



References

http://www.ngdc.noaa.gov/goes/semhttp://www.ngdc.noaa.gov/goes/sem/getData/goes15

Examples

import sunpy goes = sunpy.lightcurve.GOESLightCurve.create() goes =sunpy.lightcurve.GOESLightCurve.create(‘2012/06/01’, ‘2012/06/05’) goes.show()

Methods

create(*args, **kwargs)extract(a) Extract a set of particular columns from the DataFramefrom_data(data[, index, header])from_dataframe(dataframe[, header])from_file(filename)from_range(from_, to, **kwargs)from_time(time, **kwargs)from_timerange(timerange, **kwargs)from_url(url, **kwargs)from_yesterday()peek([title]) Plots GOES light curve is the usual mannerplot([axes]) Plot a plot of the light curvetime_range() Returns the start and end times of the LightCurve as a TimeRangetruncate(a[, b]) Returns a truncated version of the timeseries object

EVELightCurve

class sunpy.lightcurve.EVELightCurve(data, header=None)SDO EVE light curve definition

References

http://lasp.colorado.edu/home/eve/data/data-access/

Examples

import sunpy eve = sunpy.lightcurve.EVELightCurve.create() eve = sunpy.lightcurve.EVELightCurve.create(‘~/Downloads/EVE_Fe_IX_171_averages.csv’)eve = sunpy.lightcurve.EVELightCurve.create(‘2012/06/20’) eve = sunpy.lightcurve.EVELightCurve.create(“http://lasp.colorado.edu/eve/data_access/quicklook/quicklook_data/L0CS/LATEST_EVE_L0CS_DIODES_1m.txt”)eve.show()

Methods

create(*args, **kwargs)Continued on next page


http://www.ngdc.noaa.gov/goes/semhttp://www.ngdc.noaa.gov/goes/sem/getData/goes15http://lasp.colorado.edu/home/eve/data/data-access/http://lasp.colorado.edu/eve/data_access/quicklook/quicklook_data/L0CS/LATEST_EVE_L0CS_DIODES_1m.txt


Table 1.18 – continued from previous pageextract(a) Extract a set of particular columns from the DataFramefrom_data(data[, index, header])from_dataframe(dataframe[, header])from_file(filename)from_range(from_, to, **kwargs)from_time(time, **kwargs)from_timerange(timerange, **kwargs)from_url(url, **kwargs)from_yesterday()peek(**kwargs)plot([axes]) Plot a plot of the light curvetime_range() Returns the start and end times of the LightCurve as a TimeRangetruncate(a[, b]) Returns a truncated version of the timeseries object

1.2.7 SunPy Maps

Overview

One of core classes in SunPy is a Map. A SunPy Map object is simply a spatially-aware data array, often an image. Inorder to make it easy to work with image data in SunPy, the Map object provides a number of methods for commonlyperformed operations. Further, because SunPy Map objects are instances inherit from the NumPy ndarray datatype,they behave like ndarrays and support the same operations as ndarrays.

Creating Map Objects

SunPy Map objects are constructed using the special function make_map():

>>> x = sunpy.make_map(’file.fits’)

The result of a call to make_map will be either a generic Map object, or a subclass of Map which deals with a specifictype of data, e.g. AIAMap or LASCOMap.

sunpy.map.make_map(*args, **kwargs)Processes one or more inputs and returns a Map, MapCube, or CompositeMap instance.

Parameters args : filepath(s), data array

The data source used to create the map object. This can be either a filepath to an image,a 2d list, or an ndarray.

type : {‘composite’ | ‘cube’}

Type of multimap to construct when passed more than one input. The default choice isa CompositeMap which is more lenient with respect to how similar the input data is.

Returns out : Map, MapCube, CompositeMap

Returns a subclass instance

Examples

>>> import sunpy>>> sunpy.make_map("file.fts")>>> sunpy.make_map("file1.fts", "file2.fts",..)


http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html


>>> sunpy.make_map(["file1.fts", "file2.fts",..])>>> sunpy.make_map("path/to/files/*.fts")>>> sunpy.make_map(Map)>>> sunpy.make_map(Map1, Map2,..)>>> sunpy.make_map([[0, 1],[2, 3]], {’telescop’: ’sunpy’,..})

Map Classes

Map

The top-level class from which all other Maps inherit from.

class sunpy.map.Map(data, header)A spatially-aware data array based on the SolarSoft Map object

Parameters data : numpy.ndarray, list

A 2d list or ndarray containing the map data

header : dict

A dictionary of the original image header tags

See also:

numpy.ndarray

References

http://docs.scipy.org/doc/numpy/reference/arrays.classes.htmlhttp://docs.scipy.org/doc/numpy/user/basics.subclassing.htmlhttp://docs.scipy.org/doc/numpy/reference/ufuncs.htmlhttp://www.scipy.org/Subclasses

Examples

>>> aia = sunpy.make_map(sunpy.AIA_171_IMAGE)>>> aia.TAIAMap([[ 0.3125, 1. , -1.1875, ..., -0.625 , 0.5625, 0.5 ],[-0.0625, 0.1875, 0.375 , ..., 0.0625, 0.0625, -0.125 ],[-0.125 , -0.8125, -0.5 , ..., -0.3125, 0.5625, 0.4375],...,[ 0.625 , 0.625 , -0.125 , ..., 0.125 , -0.0625, 0.6875],[-0.625 , -0.625 , -0.625 , ..., 0.125 , -0.0625, 0.6875],[ 0. , 0. , -1.1875, ..., 0.125 , 0. , 0.6875]])>>> aia.units[’x’]’arcsec’