firefly.data_reader.ParticleGroup

class firefly.data_reader.ParticleGroup(UIname, coordinates, tracked_arrays=None, tracked_names=None, tracked_filter_flags=None, tracked_colormap_flags=None, decimation_factor=1, filenames_and_nparts=None, attached_settings=None, doSPHrad=False, loud=True, **settings_kwargs)[source]

Bases: object

This is a class for organizing data that you want to interface with a Reader instance. This class provides rudimentary data validation and settings defaults specific to this data class. If you do not intend to attach it to a Reader instance using that reader’s addParticleGroup method please be careful!!

__getitem__(key)[source]

Implementation of builtin function __getitem__ to retreive tracked field data.

Parameters

key (str) – field array to extract

Raises

KeyError – if field is not one of the tracked fields

Returns

field

Return type

np.ndarray

__init__(UIname, coordinates, tracked_arrays=None, tracked_names=None, tracked_filter_flags=None, tracked_colormap_flags=None, decimation_factor=1, filenames_and_nparts=None, attached_settings=None, doSPHrad=False, loud=True, **settings_kwargs)[source]
Accepts pass-through kwargs for firefly.data_reader.Settings whether one is attached

at initialization or not.

Parameters

  • UIname (str) – Name of the particle group that shows up in the UI, 4-5 characters is best so that it doesn’t spill out of the GUI.

  • coordinates (np.ndarray) – The coordinates of the points in 3d space, should have a shape of (nparts,3)

  • tracked_arrays ((nfields,nparts) np.ndarray, optional) – The field data arrays to associate with each coordinate in space, each array should be one-dimensional and have nparts entries., defaults to None

  • tracked_names (list of str with len = nfields, optional) – Should be the same length as tracked_arrays, and gives a name to each of the arrays when they show up in the UI dropdowns., defaults to None

  • tracked_filter_flags (list of bool with len = nfields, optional) – Should be the same length as tracked_arrays, and gives a flag for whether that array should be available as an interactive filter within the webapp, defaults to None

  • tracked_colormap_flags (list of bool with len = nfields, optional) – Should be the same length as tracked_arrays, and gives a flag for whether that field should be “colormappable” within the webapp, defaults to None

  • decimation_factor (int, optional) – factor by which to reduce the data randomly i.e. data=data[::decimation_factor], defaults to 1

  • filenames_and_nparts (list of tuple of (str,int), optional) –

    Allows you to manually control how the particles are distributed among the sub-JSON files, it is highly recommended that you leave this to None such that particles are equally distributed among the .jsons but if for whatever reason you need fine-tuning you should pass a list of tuples in the form

    [("json_name0.json",nparts_this_file0),("json_name1.json",nparts_this_file1) ... ]

    where where the sum of nparts_this_file%d is exactly nparts. These files will automatically be added to filenames.json if you use an attached firefly.data_reader.Reader and its dumpToJSON method, defaults to None

  • attached_settings (firefly.data_reader.Settings, optional) – Settings instance that should be linked to this particle group such that GUI elements are connected correctly. If not provided here can be attached after-the-fact using the firefly.data-reader.Settings.attachSettings() method, defaults to None

  • doSPHrad (bool, optional) – flag to vary the opacity across a particle by a cubic spline (as commonly done in SPH). Must then also provide SmoothingLength as a tracked_array., defaults to False EXPERIMENTAL FEATURE

  • loud (bool, optional) – flag to print status information to the console, defaults to False

Raises

  • ValueError – if len(tracked_names) != len(tracked arrays)

  • ValueError – if a tracked_array has length other than len(coordinates)

  • ValueError – if filenames_and_nparts is not a list of tuples and strs

  • ValueError – if color is passed as an option kwarg but the value is not an RGBA iterable

  • KeyError – if passed an invalid option_kwarg

__repr__()[source]

Implementation of builtin function __repr__

Returns

mystr, the pretty rendering of a particle group

Return type

str

__setitem__(key, value)[source]
Implementation of builtin function __setitem__ to replace

field data or track new fields. Filter flag and colormap flags will be set to true, call firefly.data_reader.ParticleGroup.trackArray() directly if this is undesired.

Parameters

  • key (str) – name of field to alter or start tracking

  • value (np.ndarray) – field data to replace current field data with or initially track

__weakref__

list of weak references to the object (if defined)

getDecimationIndexArray()[source]

Creates a numpy index array to handle decimation (sub-sampling) of your data. Chooses nparts/decimation_factor many particles randomly without replacement. Binds it to self.dec_inds. :return: dec_inds, indices corresponding to randomly chosen particles :rtype: np.ndarray

outputToDict(dec_inds=None, store_extra_keys=False, loud=False)[source]
Outputs a subset of this ParticleGroup instance’s

data to a dictionary. The subset is determined by the dec_inds input which should be an array of indices matching the tracked field arrays.

Parameters

  • dec_inds (np.ndarray, optional) – the decimation indices to use, defining a subset of the ParticleGroup data to output, defaults to np.arange(self.nparts)

  • store_extra_keys (bool, optional) – flag to store filter and colormap flags, defaults to True

  • loud (bool, optional) – flag to print status information to the console, defaults to False

Returns

outDict of particle data

Return type

dict

outputToJSON(short_data_path, hard_data_path, JSON_prefix='', loud=True, nparts_per_file=10000, clean_JSONdir=False, write_jsons_to_disk=True, not_reader=True)[source]
Outputs this ParticleGroup instance’s data to JSON format, splitting it up into

multiple sub-JSON files. Best used when coupled with a firefly.data_reader.Reader’s dumpToJSON() method.

Parameters

  • short_data_path (str) – the sub-directory you want to put these files into

  • hard_data_path (str) – the path to the directory containing different datasets’ JSON sub-directories (often /path/to/firefly/static/data)

  • JSON_prefix (str, optional) – Prefix for any .json files created, .json files will be of the format: <JSON_prefix><parttype>_%d.json, defaults to ‘’

  • loud (bool, optional) – flag to print status information to the console, defaults to True

  • max_npart_per_file (int, optional) – the maximum number of particles saved per .json file, don’t use too large a number or you will have trouble loading the individual files in., defaults to 10**4

  • clean_JSONdir (bool, optional) – flag to delete all .json files in the JSONdir. Strictly not necessary (since filenames.json will be updated) but it is good to clean up after yourself., defaults to False

  • write_jsons_to_disk (bool, optional) – flag that controls whether data is saved to disk (True) or only converted to a string and returned (False), defaults to True

  • not_reader – flag for whether to print the Reader filenames.json warning, defaults to True

Returns

filename, JSON_array (either a list full of filenames if written to disk or a list of JSON strs)

Return type

str, list of str

trackArray(field_name, arr, filter_flag=True, colormap_flag=True, filterLims=None, filterVals=None, colormapLims=None, colormapVals=None)[source]

Adds an additional data field to the ParticleGroup’s tracked fields arrays.

Parameters

  • field_name (str) – name to show in the GUI for this field

  • arr (np.ndarray) – data array for this field, should be self.nparts long

  • filter_flag (bool, optional) – flag to make field filterable in the GUI, defaults to True

  • colormap_flag (bool, optional) – flag to make field colormappable in the GUI, defaults to True

  • filterLims (list of float, optional) – initial [min, max] limits to the filters. defaults to None and is set in the web app to [min, max] of the field

  • filterVals (list of float, optional) – initial location of the filter slider handles. defaults to None and is set in the web app to [min, max] of the field

  • colormapLims (list of float, optional) – initial [min, max] limits to the colormaps. defaults to None and is set in the web app to [min, max] of the field

  • colormapVals (list of float, optional) – initial location of the colormap slider handles. defaults to None and is set in the web app to [min, max] of the field

Raises

ValueError – if the length of the field array is not self.nparts