Python Tools

Overview

The python tools is a small library of tools and classes useful for handling sedona in- and output. So far it consists of the following classes:

• ModelFile class (h5 files MODEL.h5 and ASCII files MODEL.mod)
• SliceFile class (1d Castro output of the form NAME.slice)
• PltFile class (h5 files pltXXXXX.h5)
• SpectrumFile class (h5 files SPECTRUM.h5, produced by sedona if output_write_radiation = 1 is set in the param.lua.)
• PlotterClass (Visualising DataFiles of all kind either in a set of plots, one combined plot or an animation of the time evolution)

There are also a number of scripts

• lightcurve_tools.py (An useful tool to create lightcurves from spectrum.h5 files. See section on lightcurve_tools. for more information eg. how to use it)
• test_\*.py (test scripts, all available in the python_tools/tests/ folder. They show the basic utilisation of the Datafile/Plotter classes with the example data found in the python_tools/data/ directory).

To use any of the test_*.py files just type:

python test_REST_OF_NAME.py

in the python_tools/tests/ folder.

Installation

To be able to use the tools, make sure, that you have downloaded the python_tools directory to your machine and add the following lines to the start of your python script:

import sys
path_to_tools = '../Classes/'
sys.path.append(path_to_tools)

import DataFile as DF
import Plotter as P

path_to_tools can either be a relative path to the python_tools/Classes/ directory or its absolute path (ie. /usr/path/to/the/folder/python_tools/Classes/).

File Handling

Generally speaking, Spectrum, Model, Plt and Slice files all have something in common: They consist of a large set of data table and a set of column names - they are some sort of data file. Examples on how to use them can be found in the python_tools/tests/ directory. There we can see, how to use the classes:

import DataFile as DF

MyFile = DF.ModelFile(NAME_OF_THE_FILE, PATH_TO_THE_FILE, autoload = False)
MyFile.load_data()

The load_data() is not necessary, if autoload is set to True, which is its default. MyFile is now a DataFile object (also named DFO). It comes with a list of capabilities, for example, once we have a file initialised, we can take a quick look at it:

MyFile.plot_data_1D()

This will open up a standard matplotib window. The console and the labels on the plot tell, what is plotted, if the arguments in plot_data_1D are empty, the program will look for the default keys:

Default x and y keys

File Type	default_x_key	default_y_key
ModelFile	'r'	'rho'
SliceFile	'x'	'density'
PltFile	'r'	'rho'
SpectrumFile	'nu'	Lnu_averaged', which is the automatically angle and time averaged Lnu

The following functions are defined for all data file types:

• set_keyword: Set a value in the data dictionary.

  MyFile.set_keyword('numbers',             np.array([1,2,3,4,5]))
  MyFile.set_keyword('other numbers',       np.array([5,4,3,2,1]))
  MyFile.set_keyword('2D array of numbers', np.array([  [1,2,3,4,5],
                                                        [6,7,8,9,10],
                                                        [11,12,13,14,15],
                                                        [16,17,18,19,20],
                                                        [21,22,23,24,25]] ))
  

set_keyword

Argument	Type	Description
key	arbitrary, string recommended	key, at which the value is written
value	arbitrary, numpy array recommended	dictionary entry

• get_value: Return the set value in the data dictionary.:

  numbers = Myfile.get_value('numbers')
  

get_value

Argument	Type	Description
key	arbitrary, string recommended	key, at which the value is written

• plot_data_1D: Creates a 1D matplotlib plot of two 1D arrays MyFile.data[x] vs. MyFile.data[y]

  MyFile.plot_data_1D(x = 'numbers', y = 'other numbers')
  

• plot_data_2D: Visualises a 2D array vs. two 1D arrays, ie. MyFile.data[x], MyFile.data[y] vs. MyFile.data[z]

  MyFile.plot_data_2D(x = 'numbers', y = 'other numbers', z = '2D array of numbers')
  

plot_data_1D and plot_data_2D

Argument	Type	Description
x, y, z (for 2D only)	arbitrary, string recommended	key of the x/y/z data in the data dictionary, if no set it will default to the default_x/y/z_key
plot_type	string either 'std', 'logx', 'logy' or 'loglog'	Describes the axis scaling, standard (linear on both axes), semilogarithmic plot with logarithmic x/y axis or loglog plot
plot_title, plot_xlabel, plot_ylabel	string	Set these by hand to manually write title and labels of the plot. They do not affect the data plotted!
plot_fmt	string	format string used by matplotib.pyplot.plot(), eg. 'co' for cyan dots or 'r--' for a dashed red line.
plot_save	boolean	whether to save the plot or not. Default is False
plot_save_type	string	What file the plot is to be saved to, eg. 'pdf' or 'JPG'. Default is 'png'
interactive	boolean	Whether or not to open up an interface, where two sets of buttons allow to change x and y. See Plotting for more information.

But there are also file type specific functions, which are

Tools

In the python_tools/tools directory there is a script called lightcurve_tools.py. It can be used to create the light curve in a given band. A list of all available bands can be found in the FILTER_LIST file in python_tools/data/. They can also be accessed by typing

python lightcurve_tools.py --bands

To produce a light curve just use:

python lightcurve_tools.py -s <path_to_spectrum_file> -b <space separated list of bands>

The resulting lighcurve can be found in the file ./lightcurve.out. It has 3 columns called Time (Days), Lbol (erg/s), Mbol and one for every band For example the lightcurve.out created by running

python lightcurve_tools.py -s ../data/spectrum_1D_TypeIa.h5 -b U B V

in the python_tools/tools/ directory produces a lightcurve.out (in python_tools/tools/) with 6 data columns for time, bolometric luminosity, bolometric magnitude and the magnitude in the U, B and V band. All magnitudes are given in the AB Magnitude System.

Warning: Invalid elements are assigned a value of 0, the script also floors the magnitudes to 0 if <0

Plotting

There are also possibilities to compare single or multiple data files. The important basic examples can be found in /tests/test_plotter.py and tests/test_datafilelasses.py. The different types of plots available are:

For a single DataFile

• plot X vs. Y, where X and Y are two arrays found in the data
• plot X vs. Y, where two row of buttons let you switch between all available X and Y arrays
• plot X and Y vs. Z

For multiple DataFiles

• making subplots for a set of files (plotting their respective default X vs. default Y)
• combining a set of files into one single plot (again, plotting their respective default X vs. default Y)
• timeseries of a set of files, ie. plotting time dependent data into a short repeating movie. This works for single DataFiles, that have a time axis (ie SpectrumFiles) or a set of files, that have a time associated to them (so far only SliceFiles have been implemented)

A single DataFile plot can be opened without explicitly calling the plotter, for example by:

path = "python_tools/data/"
name = "plt19400.slice"

S = DF.SliceFile(name, path)
S.plot_data_1D()

The function DATAFILE.plot_data_1D() takes the arguments described in the FileHandling section. If a 2D plot is needed, use DATAFILE.plot_data_2D(), which can be used to visualise a 2D array of shape (A x B), using two 1D arrays of length A and B as x and y-axis. For an interactive plotting interface (for 1D plots), set interactive = True for the DATAFILE.plot_data_1D() function, ie.:

S.plot_data_1D(interactive = True)

The same plot will be opened, if

Plot = P.Plotter(DataFileObjects = [S])
Plot.start_1D_UI(mode = "interactiveplot")

is called. The first line initialises the Plotter object called Plot, the second starts the interface. Note, that P.Plotter takes a list of DFOs to initialise! The reason is, that normally one would want to compare a set of DFOs. Generally speaking, the Plotter class comes (aside from some convenience methods) with a one-for-all-function ``start_1D_UI()``. Its most important argument is mode. mode can be one of the following options:

• mode = 'interativeplot': Opens the same plot, as if DATAFILE.plot_data_1D(interactive) were called. Window consists of one plot and two columns of (radio) buttons, that can be used to select the data on the x and y axis.
• mode = 'subplots': Open a window with N = (number of DFOs in the DataFileObjects list) subplots, one for every DFO. Plots default x vs. default y for every file. There is a button to en- and disable log scaling for the axes.
• mode = 'onewindow': Open a window with one plot. As for mode = 'subplots' default x vs. default y is plotted for every file, but now in one combined plot. There is a button to en- and disable log scaling for the axes. Warning: The Plotter doesn’t check the dimensions and units of the data, it assumes, that it makes sense, that all the data can be put into one plot window!
• mode = 'timeseries': Open a window with one plot, a progress bar above it, and two buttons for the log scaling. If the Plotter object has been initialised with DataFileObjects = [ONEFILE], then this file needs to have a time axis. So far, only SPECTRUM.h5 files do. If the DataFileObjects list consists of more than one element, then it uses DFO.find_time() to see, if a time can be found. Once the data is loaded, the movie is created using the given fps number and film_duration and interpolating between snapshots created from the DFO(s).