Package: faster-filereader
A library to read Faster files with pythonThe faster acquisiton system comes with it's own C++ code for data unpacking and analysis:fasteracHowever, if you use a Windows system, work on different systems, ... writing, compiling and deploying an analysis code can be tedious.With Python, you can focus on writing the analysis code, without worrying about the dependencies, system paths, compilation, ...That's why thisfasterpython module was developped.The project can be live tested onBinder:Getting StartedThe following instructions will get you a copy of the project up and running on your local machine.InstallingThe module comes with no external dependency, and can easily be installed with thedistul=tilstools of Python (pip  packaging will come soon).Get thefaster-202003.tar.gzfile. Thencdto the directory where the file was download and execute the following commands:tarxvvzffaster-202003.tar.gzcdfaster-202003
python3setup.pyinstallcd..
python3.7-mfastertestThis will unpack, build, install and test thefastermodule.Running the testsThe package comes with built-in test. To run the test, just run the following command in the directory containning the module.$python3-mfastertestThe output should be looking like# Starting test ...
# Module's path is '/the/path/to/faster/'
# Elasped time: 0.601 seconds
# Read 60211 of 60211 events from the test file
#...doneYou can test the library online with Binder:DependenciesThe module is built with no dependencies apart from the python standard library.UsageModule level commandsThe module provide some direct commands that can be called using$python3-mfastercommandUsepython3.7 -m faster -hfor a short inline documentation.testAs mentionned above, callingpython3 -m faster testwill perform a simple test: open a small file and iterate over it until the end.moreCalling$python3-mfastermorepath/to/faster/file.fastwill display the content of the file by group of 10 events until you type 'q' at the prompt after each 10 event groups, or the end of the file, or you send a KeyboardInterrupt signal (i.e. Ctrl-C).statsCalling$python3-mfasterstats[--nmax=N]path/to/faster/file.fastwill read the files until the end or N events from the file and display statitics about the types and labels of events that were red.
The outuput format is python like with a tuple containing dictionnaries..File ReaderTheFileReaderclass defines an iterator object that can be used to obtain the vents one by one.The simplest way to create a FileReader object isFileReader('./path/to/file.fast').
A second agrgument can be added to define the maximum number of events to read. By default, the reader will read 180000000 events, which is equivalent to 2GB of 12 bytes events and should cover all the data file cases.The best way to explore the file is to use aforloop:forfasterventinFileReader('./path/to/file.fast'):# actions on `fasterevent` hereWherefastereventwill be anEventobject.UsingwithFileReadersupports the python context manager:withFileReader('./path/to/file.fast')asffreader:forevtinffreader:# event processing loopnextSinceFileReaderobjects are iterators, the user can pull the events manually one by one by using the builtinnextcommand:next_event=next(ffreader)EventTheEventclass defines the event data.AnEventobject is normally instantiated by the FileReader. Its attributes aretype_alias: a number indicating the type aliasclock: an array of integer containning the clock information (timestamp)label: an integer containing the event labelload_size: the size in bytes of the raw dataraw data: the raw (i.e.byte) data3 more attributes are accessibles and interpreted "just-in-time" for better perfomance:type: a string representing the even type, the correspondance with a type_alias is defined within the dataunpacker filetime: the computed timestamp (without the tick interval multiplier)data: adictcontainning the unpacked data (by the unpackers).Just in TimeattributesSome attributes of the Event object are intrepreted "Just-in-Time" as needed. This is intended to save time and ressources as not all events, labels or types will need to be fully inspected in data analaysis. Thanks to specific inner mechanics ofpythonobjects, the JIT attributes are computed once and are not re-interpreted when called multiple times for the same event.The JIT attributes are :type: a string description of the event type. For example, an event withtype_alias==10will havetype=="group".time: the computed timestamp.data: a dictionnary containning the interpreted data. Seedata unpackersdocumentation for the different types.Data unpackersThe data unpackers are the submodules doing the data unpacking work.To make the python faster package easy to extend, creating a new unpacker is simple.To create a new unpacker, just create a filetype_XX.pyin the dataunpackers folder where X is the type_alias of the type of data the upacker will deal with.In this file, you have to definealias: the number corresponding to the type (i.e. XX)type_: a string (prefereably no space) describing the typea functionunpack(data)that takes the rawdata as argument and returns a dictionnary with the interpreted data.If you write an unpacker for a type not yet supported by the package, you are invited to submit it to the project so that it gets integrated with the module.SpeedSeeperformances.mdfor a discussion about speed and memory.AuthorsGreg Henning- ghenning​.at.​iphc․cnrs․frLicenseThis project is licensed under the CeCILL FREE SOFTWARE LICENSE AGREEMENT.SeeLICENSEfor more.AcknowledgmentsThanks to D. Etasse (LPC Caen / CNRS) for support while coding the unpackers.