Skip to content

Review of cubes #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dpshelio wants to merge 1 commit into
base: cubes
Choose a base branch
from
Open

Review of cubes #1

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 37 additions & 12 deletions doc/source/guide/data_types/cubes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,16 @@ Cubes
=====

SunPy Cubes are 3- or 4-dimensional arrays of continuous data with an associated coordinate system.
There are four possible cube types:: time and two solar dimensions (i.e. a time-series of maps); energy and two solar dimensions (i.e. a series of maps ordered by wavelength); time, energy and a single solar dimension (i.e. a timeseries cube); or a time, energy and two solar dimensions hypercube.
It is important to note that regardless of the data source used, the data held in the cube is ordered by the present dimension type:: the highest priority is assigned to time, then energy, and solar coordinates at the bottom. This means that if, for example, a cube is given solar-x, energy and solar-y as its dimensions, it will rearrange the axes and data to make it an energy-x-y cube. When more than one spatial dimansion is present, the oriiginal order is preserved.
There are four possible cube types:: time and two solar dimensions (i.e. a time-series of maps);
energy and two solar dimensions (i.e. a series of maps ordered by wavelength);
time, energy and a single solar dimension (i.e. a timeseries cube);
or a time, energy and two solar dimensions hypercube.
It is important to note that regardless of the data source used,
the data held in the cube is ordered by the present dimension type:: the highest priority
is assigned to time, then energy, and solar coordinates at the bottom.
This means that if, for example, a cube is given solar-x, energy and solar-y as its dimensions,
it will rearrange the axes and data to make it an energy-x-y cube.
When more than one spatial dimension is present, the original order is preserved.
This document is meant merely as an introduction; for the full documentation consult the API Reference.

------------
Expand All @@ -21,7 +29,10 @@ First of all, we need to initialize the current interactive python shell::
from sunpy.cube.sources.eis import EISSpectralCube as eis
my_cubes = eis.read("/directory/file.fits")

This is assuming your FITS file's address is /directory/file.fits. EIS convention is to include several cubes in a single file, ordered by their principal wavelength. Therefore, my_cubes is a variable containing a python dictionary of cubes ordered by their principal wavelength.
This is assuming your FITS file's address is /directory/file.fits.
EIS convention is to include several cubes in a single file, ordered by their principal wavelength.
Therefore, my_cubes is a variable containing a python dictionary of cubes ordered by their
principal wavelength.
Let's see a typical example::

In [5]: my_cubes.keys()
Expand All @@ -41,24 +52,36 @@ The variable my_cube is now an EIS Spectral Cube.

2. Creating a Generic Cube
--------------------------
If you have your data and an associated WCS object, you can call the Cube constructor by doing::
If you have your data and an associated WCS object, you can call the Cube
constructor by doing::

my_generic_cube = Cube(data=my_data, wcs=my_wcs)

The internal rearrangement of data and coordinate system is done independently of the variables you put in, so they are not changed.
Note that, due to the way in which WCS objects are handled, wcs cannot be an astropy wcs object; it must be a SunPy WCS one.
The internal rearrangement of data and coordinate system is done independently
of the variables you put in, so they are not changed.
Note that, due to the way in which WCS objects are handled, wcs cannot be an
astropy wcs object; it must be a SunPy WCS one.

3. Converting to other SunPy Datatypes
--------------------------------------
Cubes can be automatically converted to all other SunPy datatypes either pixel-wise or by using world coordinates.
There are two ways of achieving this:: Using the dedicated methods or by slicing the cube as if it were a numpy array. The dedicated methods, which are all called some variation of slice_to_map, slice_to_lightcurve, etc., are more flexible and powerful but at the same time more verbose. Consult the documentation for specifics.
Continuing from the example above, my_cube is a wavelength-solar y-solar x cube. This means that a slice along the energy axis yields an x-y slice - that's a map! Here's an example of one::
Cubes can be automatically converted to all other SunPy datatypes either pixel-wise
or by using world coordinates.
There are two ways of achieving this::
Using the dedicated methods or by slicing the cube as if it were a numpy array.
The dedicated methods, which are all called some variation of slice_to_map,
slice_to_lightcurve, etc., are more flexible and powerful but at the same time more verbose.
Consult the documentation for specifics.
Continuing from the example above, my_cube is a wavelength x-solar y-solar cube.
This means that a slice along the energy axis yields an x-y slice - that's a map!
Here's an example of one::

from astropy import units as u
my_map = my_cube[184.552 * u.Angstrom]
my_map.peek()

Numpy-style slicing supports almost the same syntax that numpy does, except using None as an index to create another axis. Ranges and increments are fully supported.
Numpy-style slicing supports almost the same syntax that numpy does,
except using None as an index to create another axis.
Ranges and increments are fully supported.
Note that you only have to provide the unit once per axis. That is::

my_cube[184.540 * u.Angstrom:184.550:0.05]
Expand All @@ -67,7 +90,8 @@ is just as valid as::

my_cube[184.540 * u.Angstrom:184.550 * u.Angstrom:0.05 * u.Angstrom]

However, you should keep in mind that units cannot be mixed, even between units that represent the same dimension.
However, you should keep in mind that units cannot be mixed,
even between units that represent the same dimension.
The following table shows how slices are interpreted.

+------------+-----------------------------------+
Expand All @@ -94,4 +118,5 @@ You can view a cube like this::

my_cube.animate()

This creates a new window with a slider that you can adjust to travel between the different 2D slices.
This creates a new window with a slider that you can adjust to travel between
the different 2D slices.