Understanding Firefly’s input requirements

Firefly uses custom binary .ffly files to load data into a web browser’s javascript interpreter. The files required to run an individual instance of Firefly are expected to be compiled into a JSONdir.

There are four kinds of file that Firefly requires:

The startup file, startup.json

This is a configuration file that specifies which JSONdir Firefly should attempt to open at startup. It should be formatted as a dictionary mapping between strings of integers sequential integers mapped to the location of the JSONdir relative to the firefly/static directory.

For example, the default startup.json that ships with Firefly looks like:

{"0":"data\/FIRESampleData"}

If it contains multiple entries, Firefly will allow the user to select the dataset from a dropdown when the webapp is initialized.

{"0":"data\/FIRESampleData","1":"data/tutorial"}

Note

startup.json must reside within firefly/static/data.

The settings file, <settings>.json

This is a .json file that contains the default settings for various aspects of Firefly’s UI.

as well as default filter settings for each of the particle groups. It should be created using a firefly.data_reader.Settings instance and its corresponding outputToJSON() method. This lives in the JSONdir sub-directory described above. It can be named whatever you’d like as long as it is linked to correctly within filenames.json, described below.

The particle group files, <prefix><particleGroup><fileNumber>.ffly

These are the main data files, and contain the particle coordinates and their corresponding scalar field values. They should exclusively be created using a firefly.data_reader.ParticleGroup instance’s outputToFFLY() method. These files live in the JSONdir sub-directory described above. They can be named whatever you’d like as long as they are linked to correctly within filenames.json, described below.

Warning

Datasets are chunked into multiple files to improve performance at startup and to enable a loading bar to give feedback to you, the user! You should not purposefully circumvent this feature by setting the nparts_per_file keyword argument of firefly.data_reader.ParticleGroup.outputToFFLY() to a very large value.

The manifest file, filenames.json

This is a .json file that identifies the different files within the selected dataset Firefly needs to open.

It should map particle group names to lists of files and the number of particles in each file along with the default settings file to use.

{"<particleGroup1>" : [[<this_filename>,<npart_this_file>] for file in particleGroup1Files],
"<particleGroup2>" : [[<this_filename>,<npart_this_file>] for file in particleGroup2Files],
"options" : [["<JSONdir>/<settings_filename>.json",0]]}

The easiest way to create this file is to use the firefly.data_reader.Reader.writeToDisk() method of a firefly.data_reader.Reader instance linked to firefly.data_reader.Options and firefly.data_reader.ParticleGroup instances.