firefly.data_reader.Reader

class firefly.data_reader.Reader(datadir=None, file_prefix='Data', clean_datadir=True, max_npart_per_file=100000, write_startup='append', write_only_data=False, settings: Optional[firefly.data_reader.settings.Settings] = None, tweenParams: Optional[firefly.data_reader.tween.TweenParams] = None, **kwargs)[source]

Bases: object

This class provides a framework to unify the Settings and ParticleGroup classes to make sure that the user can easily produce firefly compatible files. You should use this Reader as a base class for any custom readers you may build (see firefly.data_reader.SimpleReader or firefly.data_reader.FIREreader for example).

__init__(datadir=None, file_prefix='Data', clean_datadir=True, max_npart_per_file=100000, write_startup='append', write_only_data=False, settings: Optional[firefly.data_reader.settings.Settings] = None, tweenParams: Optional[firefly.data_reader.tween.TweenParams] = None, **kwargs)[source]
Base initialization method for Reader instances. A Reader will read data and produce

firefly compatible .json files.

Parameters

  • datadir (str, optional) – the sub-directory that will contain your JSON files, relative to your $HOME directory. , defaults to $HOME/<file_prefix>

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

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

  • 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

  • write_startup (str/bool, optional) – flag for how to treat the startup.json file. Takes three values: 'append': appends datadir to startup.json, True: overwrites startup.json with a single entry, datadir, False: does not alter startup.json, , defaults to ‘append’

  • write_only_data (bool, optional) – flag for whether writeToDisk should exclude Settings and tweenParams instances as well as the filenames.json and startup.json files. If True, then the reader will only export the raw data files (useful for not overwriting things or only loading single files at a time to append onto an existing dataset), defaults to False

  • settings (firefly.data_reader.Settings, optional) – a firefly.data_reader.Settings instance, defaults to a new default firefly.data_reader.Settings instance.

  • tweenParams (firefly.data_reader.TweenParams, optional) – firefly.data_reader.TweenParams instance, defaults to None

Raises
__repr__()[source]

Implementation of builtin function __repr__

Returns

mystr, the pretty rendering of a reader

Return type

str

__weakref__

list of weak references to the object (if defined)

addParticleGroup(particleGroup)[source]
Track a new ParticleGroup instance in

this firefly.data_reader.Reader instance’s particleGroups array and to the attached firefly.data_reader.Settings instance.

Parameters

particleGroup (firefly.data_reader.ParticleGroup) – a ParticleGroup instance that contains particle data for an individual UI element.

copyFireflySourceToTarget(target=None, flask_templates=False, dump_data=True, overwrite=True, init_gh_pages=False, GHREPONAME=None, GHUSER=None, GHOAUTHTOKENPATH=None, **kwargs)[source]
Copies the necessary source files to run a stand-alone instance of firefly

on the web. Optionally, will also initialize a new GitHub repository with GitHub pages, a free web-hosting service, so that this stand-alone instance can be accessed by anyone over the internet.

Parameters

  • target (str, optional) – target directory to save firefly source files to, defaults to $HOME/my_Firefly

  • flask_templates (bool, optional) – flag for whether the flask template files should also be copied. In general, these files are not required to run firefly over the internet but may be useful if one intends to run firefly locally in this new directory, defaults to False

  • dump_data (bool, optional) – flag for whether the data stored in this reader should also be saved to this new stand-alone firefly directory (vs. only the firefly source files), defaults to True

  • overwrite (bool, optional) – flag for whether the existing target static directory should be purged before anything is copied over or written to disk, defaults to True

  • init_gh_pages (bool, optional) – flag to run firefly/bin/make_new_repo.sh in an attempt to initialize a new github repository with GitHub Pages, a free web-hosting service provided by GitHub, enabled, defaults to False

  • GHREPONAME (str, optional) – repository name that we should attempt to create (note that a non-critical error will be raised if the repo already exists), defaults to the last sub-directory of target

  • GHUSER (str, optional) – GitHub username, defaults to $USER

  • GHOAUTHTOKENPATH (str, optional) – filepath to a file containing only the OAUTH token generated at: https://github.com/settings/tokens, defaults to $HOME/.github.token

Raises

  • FileNotFoundError – if GHOAUTHTOKENPATH cannot be resolved

  • FileNotFoundError – if firefly/bin/make_new_repo.sh cannot be found.

Returns

returns a list of strings, [target] if init_git_pages=False otherwise the output of running firefly/bin/make_new_repo.sh.

Return type

list of str

outputToDict()[source]
Formats the data in the reader to a python dictionary using

the attached firefly.data_reader.Settings.outputToDict() and firefly.data_reader.ParticleGroup.outputToDict() methods (and firefly.data_reader.TweenParams.outputToDict() if one is attached).

Returns

outputDict, a dictionary structured like the javascript object in the firefly webapp. Can be sent to the js interpreter via Flask using the firefly.data_reader.Reader.sendDataViaFlask() method.

Return type

dict

sendDataViaFlask(port=5500, room=None)[source]
Exports the data as if it were being dumped to disk

but instead stores it as a string. Then feeds this string to the js interpreter via Flask.

Parameters

  • port (int, optional) – port that the firefly Flask server is being hosted on, defaults to 5500

  • room (str, optional) – the name of the flask session to send data to on the specified port. defaults to None

Raises

ValueError – if room is not specified.

writeToDisk(loud=False, write_to_disk=True, symlink=True, file_extension='.ffly', **kwargs)[source]

Creates all the necessary JSON files to run firefly and ensures they are properly linked and cross-referenced correctly using the firefly.data_reader.Settings.outputToJSON() and firefly.data_reader.ParticleGroup.outputToJSON() methods (and firefly.data_reader.TweenParams.outputToJSON() if one is attached). :param loud: flag to print status information to the console, defaults to False :type loud: bool, optional :param write_to_disk: flag that controls whether data is saved to disk (True)

or only converted to a string and stored in self.JSON (False), defaults to True

Parameters

  • symlink (bool, optional) – flag for whether a soft link should be created between where the data is stored on disk and the self.static_data_dir directory (True) or whether it should be saved directly to self.static_data_dir directory (False). Note that symlink=False will not _also_ save results in self.datadir, defaults to True

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

Returns

self.JSON or "" according to write_to_disk

Return type

str