firefly.data_reader.ParticleGroup

class firefly.data_reader.ParticleGroup(UIname, coordinates, velocities=None, rgba_colors=None, field_arrays=None, field_names=None, field_filter_flags=None, field_colormap_flags=None, field_radius_flags=None, decimation_factor=1, attached_settings=None, 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, velocities=None, rgba_colors=None, field_arrays=None, field_names=None, field_filter_flags=None, field_colormap_flags=None, field_radius_flags=None, decimation_factor=1, attached_settings=None, 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)

  • velocities (np.ndarray) – The velocities associated with each coordinate, should have a shape of (nparts,3) allows vectors to be plotted at the coordinate location

  • rgba_colors (np.ndarray) – The RGBA tuples associated with each coordinate, should have a shape of (nparts,4)

  • field_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

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

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

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

  • field_radius_flags (list of bool with len = nfields, optional) – Should be the same length as field_arrays, and gives a flag for whether that field should be allowed to scale particle radii 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

  • 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

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

Raises

  • ValueError – if len(field_names) != len(field arrays)

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

  • 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, colormap, and radius 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

spawn_octree_pg(datadir: str, max_npart_per_node: int, **kwargs)[source]
Creates a new firefly.data_reader.particlegroup.OctreeParticleGroup instance

that references the data contained by the firefly.data_reader.particlegroup.ParticleGroup instance that calls this method.

Parameters

  • datadir (str) – directory to output self.UIname/octree.json (and corresponding files) to.

  • max_npart_per_node (int) – maximum number of particles a node can contain before it should be refined.

Returns

octree_pg

Return type

OctreeParticleGroup

trackArray(field_name, arr, filter_flag=True, colormap_flag=True, radius_flag=False, 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

  • radius_flag (bool, optional) – flag to allow field to be used as a radius scale 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

untrackArray(field_name)[source]

remove a field array that was previously added/tracked

Parameters

field_name (str) – name of the field to remove

writeToDisk(target_directory, file_prefix='', file_extension='.ffly', loud=True, max_npart_per_file=100000, clean_datadir=False, not_reader=True, write_to_disk=True)[source]
Outputs this ParticleGroup instance’s data to a compatible Firefly format,

either .ffly or .json. Data is partitioned into multiple sub-files. This is best used when coupled with a firefly.data_reader.Reader’s writeToDisk() method.

Parameters

  • target_directory (str) – the path to the directory where data should be saved

  • file_extension (str, optional) – File extension for data files created, one of .ffly (binary) or .json (ASCII).

  • file_prefix (str, optional) – Prefix for any files created, filenames will look like: f”{file_prefix}{self.UIname}{i_file:03d}{file_extension}”

  • 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_datadir (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_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 (bool, optional) – flag for whether to print the Reader filenames.json warning, defaults to True

Returns

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

Return type

str, list of str