Python Data Converter

We provide a Python based frontend to Firefly that will process your data and create Firefly-compliant JSON files. You are welcome to look at the description of Firefly's input requirements and create your own utility if you'd like.

If you do not have Python already installed, please do so. We recommend installing Anaconda Python version 3.x .

Python frontend

The frontend contains the Options,ParticleGroup,Reader, and FIREreader classes that do all the heavy lifting. There are many options that you can set. Perhaps the best way to view all of the available options is to print the docstring :

$ python
>>> from firefly_api.options import Options
>>> from firefly_api.reader import Reader
>>> from firefly_api.particlegroup import ParticleGroup
>>> from firefly_api.FIREreader import FIREreader
>>> print(Options.__doc__)
>>> print(Reader.__doc__)
>>> print(ParticleGroup.__doc__)
>>> print(FIREreader.__doc__)

In practice, you should not edit this python code directly. Instead you can import this into an iPython notebook (or a stand-alone Python code), and set the options in the notebook or create your own ___reader class inspired by FIREreader.

Using FIREreader to open Gizmo datasets

In general, the FIREreader class will do the following:

• Read in the hdf5 files within the FIREreader.directory and FIREreader.snapnum location into a python dictionary to be converted with .json format for Firefly.
• Create a directory within your data directory (FIREreader.dataDir : either user-defined, or generated automatically based on the snapshot number) that will contain all the necessary .json files.
• Save the keys from the dictionary that you define within the "returnKeys" parameter for use by Firefly.
• Set options that will be used to display the data (e.g., the default particle sizes, colors, names, which data to include as filters, etc.)
• Create the following .json files within the FIREreader.dataDir:
  • multiple data files (e.g., FIREdataGas*.json) containing chunks of the full data set,
  • one options file (e.g., FIREdataOptions.json) that stores the options you defined to customize the Firefly interface, and defaults.
  • Create a .json file (filenames.json) that points Firefly to the rest of the data files.
• Create a final .json file called startup.json within the data directory that points to the FIREreader.dataDir (used by Firefly at startup, though not technically required for Firefly to run).

Using the python frontend

We provide a number of example iPython notebooks in the data directory that show how to use the FIREreader.py code to convert your data. The simplest example shows how one can load arbitrary arrays into Firefly using a cube of points as an example. We also show how one can customize the view settings with an options instance.

The simplest example that uses FIRE simulation data is here. It uses the default settings, of the FIREreader class while only defining the directory, particle names, and decimation. Also note that with the Options class, you can create different preset files to define different configurations you want to load into Firefly (without recreating the entire data set). This is demonstrated at the bottom of the example with customization linked above.

We also provide an example with customization that opens a cosmological zoom-in simulation and adds a number of filters. Before writing out, we also convert some of the units in the snapshot and compute the galactocentric radii and the center of mass velocity.

Our most prolific power-user has also shared their workflow for visualizing "worldlines" of particles using the particle tracking code linefinder. At the very least, it shows the extent of how you can extend the basic functionality of Firefly to create your own unique visualizations.

These examples can also be found in .py format here.