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
orfirefly.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 thedatadir
. Strictly not necessary (sincefilenames.json
will be updated) but it is good to clean up after yourself., defaults to Falsemax_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**4write_startup (str/bool, optional) – flag for how to treat the
startup.json
file. Takes three values:'append'
: appendsdatadir
tostartup.json
,True
: overwritesstartup.json
with a single entry,datadir
,False
: does not alterstartup.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) – afirefly.data_reader.Settings
instance, defaults to a new defaultfirefly.data_reader.Settings
instance.tweenParams (
firefly.data_reader.TweenParams
, optional) –firefly.data_reader.TweenParams
instance, defaults to None
- Raises
TypeError – raised if anything other than a
firefly.data_reader.Settings
instance is passed tosettings
TypeError – raised if anything other than a
firefly.data_reader.TweenParams
instance is passed totweenParams
- __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’sparticleGroups
array and to the attachedfirefly.data_reader.Settings
instance.
- Parameters
particleGroup (
firefly.data_reader.ParticleGroup
) – aParticleGroup
instance that contains particle data for an individual UI element.
- Track a new
- 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 FalseGHREPONAME (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 resolvedFileNotFoundError – if
firefly/bin/make_new_repo.sh
cannot be found.
- Returns
returns a list of strings,
[target]
ifinit_git_pages=False
otherwise the output of runningfirefly/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()
andfirefly.data_reader.ParticleGroup.outputToDict()
methods (andfirefly.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 thefirefly.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()
andfirefly.data_reader.ParticleGroup.outputToJSON()
methods (andfirefly.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 toself.static_data_dir
directory (False
). Note thatsymlink=False
will not _also_ save results inself.datadir
, defaults to Truefile_extension (str, optional) – File extension for data files created, one of .ffly (binary) or .json (ASCII).
- Returns
self.JSON
or""
according towrite_to_disk
- Return type
str