Cicada Use and API Documentation¶
Contents:
Introduction¶
Cicada contains the libraries describing the objects generated by the Katydid processing. These objects should be contained in ROOT files: as such they inherit from the TObject class (the “mother of all ROOT objects”). Their nature should be very close to TTree objects.
Getting started¶
Installation¶
The following steps will build Cicada from scratch. Starting with a terminal window …
1. Clone the repository and make a build directory as recommended above. You will also have to initialize the submodules.
git clone "https://github.com/project8/cicada"
cd cicada
git submodule update --init --recursive
mkdir build
2. To configure the installation you can use cmake, ccmake, or cmake-gui. For a first configuration, using either ccmake or cmake-gui is highly recommended. The following instructions are for ccmake, but the steps with cmake-gui would be approximately the same.
cd build
ccmake ..
You will be prompted to press [c] to configure, and the window will fill up with several options. You should set the CMake variable CMAKE_BUILD_TYPE to either RELEASE, STANDARD, or DEBUG (default), in order of how much text output you would like (from least to most) and how much compiler optimization should be performed (from most to least). The install prefix is specified by the CMake variable CMAKE_INSTALL_PREFIX. The library, binaries, and header files will be installed in the lib, bin, and include subdirectories. The default install prefix is the build directory. After you’ve finished, if you’ve changed anything press [c] again to configure. Then [g] to generate and exit.
3. Build and install.
make install
Or if you want to take advantage of parallel building to get things done faster:
make -j install
If the compiler runs into errors during the build, first check that you’ve updated the submodules and that you have all of the required dependencies installed (many are called “optional” on this page, but if you want to build without them you must also specify this in the cmake window). If you made a change to the dependencies or submodules, you may have to wipe the build directory and start again from step 1; simply writing make install again will not always work.
4. Use this_cicada.sh to set your PYTHONPATH and ROOT_INCLUDE_PATH:
source /path/to/cicada/install/bin/this_cicada.sh
This will allow you to access the Python and ROOT interfaces and the python example scripts coming with cicada.
5. Developpers: Add the installation folder (where the bin and lib have been installed) path to your paths.
export PATH=/path/to/cicada/install/bin:$PATH
export LD_LIBRARY_PATH=/path/to/cicada/install/lib:$LD_LIBRARY_PATH
How to use¶
Cicada does not do anything per se, but is a library retaining the structure of some objects generated by Katydid (see Objects’ structure and description section for more details). An example on how to read a Katydid object is present in Library/python. The core of this scripts is:
import CicadaPy
CicadaPy.loadLibraries()
import ROOT.Katydid as KT
from ROOT import TFile, TTreeReader, TTreeReaderValue
def ReadKTOutputFile(filename,var):
# Change to point to the ROOT file you want
# filename = "../../scripts/PhaseI_analysis_roofit/events_000001097_katydid_v2.7.0_concat.root"
file = TFile.Open(filename)
if not file:
raise FileNotFoundError("File {} does not exist".format(filename))
# Extract tree from file
tree = file.Get("multiTrackEvents")
# Create TTreeReader
treeReader = TTreeReader(tree)
# Create object TMultiTrackEventData to "point" to the object "Event" in the tree
multiTrackEventObject = TTreeReaderValue(KT.TMultiTrackEventData)(treeReader, "Event")
resultList = []
# Go through the events
while treeReader.Next():
exec("resultList.append(multiTrackEvents.Get{}())\n".format(var))
print(resultList[-1])
return resultList
1. The first two lines add the Cicada libraries into the ROOT module, so they can be imported by the second import. Note that here we call ROOT.Katydid and not ROOT.Cicada: we are using the Katydid namespace that was added to ROOT. One day once the Cicada library will be used as a dependency of Katydid, we will use ROOT.Cicada.
2. The function ReadKTOutputFile takes a file name and a variable of interest and it will print the value of this variable. To do this, it extracts the tree called multiTrackEvents containing the TMultiTrackEventData object and makes use of the ROOT TTreeReader to get each value of this object. The iterator of the tree reader is then used to append to a list and print the value of the parameters var of the event object using a GetX method (defined by the class). The list is then returned.
Objects’ structure and description¶
Here is described the content and associated description of the Cicada objects.
Version 1.2.0¶
TMultiTrackEventData¶
- Component – UInt_t:
- AcquisitionID – UInt_t:
- EventID – UInt_t: number of the event in the katydid instance
- TotalEventSequences – UInt_t: number of sequences in the event
- StartTimeInRunC – Double_t: start time of the event in the Katydid instance
- StartTimeInAcq – Double_t: start time of the event within the chunk of data
- EndTimeInRunC – Double_t: end time of the event in the Katydid instance
- TimeLength – Double_t: duration of the event
- StartFrequency – Double_t: start frequency of the event
- EndFrequency – Double_t: end frequency of the event
- MinimumFrequency – Double_t: minimum frequency reached by the event
- MaximumFrequency – Double_t: maximum frequency reached by the event
- FrequencyWidth – Double_t: range of frequencies covered by the event tracks
- StartTimeInRunCSigma – Double_t: error on the start time of the event in the Katydid instance
- EndTimeInRunCSigma – Double_t: error on the end time of the event in the Katydid instance
- StartFrequencySigma – Double_t: error on the start frequency of the event
- EndFrequencySigma – Double_t: error on the end frequency of the event
- FrequencyWidthSigma – Double_t: error on the range of frequencies covered by the event tracks
- FirstTrackID – UInt_t: ID number of the first track in the event
- FirstTrackTimeLength – Double_t: length of the first track
- FirstTrackFrequencyWidth – Double_t: range of frequencies covered by the first track
- FirstTrackSlope – Double_t: slope of the first track
- FirstTrackIntercept – Double_t: intercept at t=0 of the first track
- FirstTrackTotalPower – Double_t: sum of the power of the bins composing the first track
- FirstTrackNTrackBins – UInt_t: number of bins in the first track
- FirstTrackTotalTrackSNR – Double_t: Sum of the first track bins SNR
- FirstTrackMaxTrackSNR – Double_t: Max of the first track bins SNR
- FirstTrackTotalTrackNUP – Double_t: Sum of the first track bins Normalized Unitless Power (NUP)
- FirstTrackMaxTrackNUP – Double_t: Max of the first track bins Normalized Unitless Power (NUP)
- FirstTrackTotalWideTrackSNR – Double_t: Sum of the first track extended bins SNR
- FirstTrackTotalWideTrackNUP – Double_t: Sum of the first track extended bins Normalized Unitless Power (NUP)
- UnknownEventTopology – Double_t: boolean describing if a track has some weird topology
TProcessedTrackData¶
- Component – UInt_t:
- AcquisitionID – UInt_t:
- TrackID – UInt_t: number of the track in the event
- EventID – UInt_t: number of the event in the katydid instance
- EventSequenceID – UInt_t: number of the sequence in the event reconstruction
- IsCut – Bool_t: should this line be cut when calculating the start frequency…?
- StartTimeInRunC – Double_t: start time of the track in the Katydid instance
- StartTimeInAcq – Double_t: start time of the track within the chunk of data
- EndTimeInRunC – Double_t: end time of the track in the Katydid instance
- TimeLength – Double_t: track length
- StartFrequency – Double_t: start frequency of the track
- EndFrequency – Double_t: end frequency of the track
- FrequencyWidth – Double_t: range of frequencies covered by the track
- Slope – Double_t: slope of the track
- Intercept – Double_t: intercept at t=0 of the track
- TotalPower – Double_t: sum of the power of the bins composing the track
- NTrackBins – UInt_t: number of bins in the track
- TotalTrackSNR – Double_t: Sum of the track bins SNR
- MaxTrackSNR – Double_t: Max of the track bins SNR
- TotalTrackNUP – Double_t: Sum of the track bins Normalized Unitless Power (NUP)
- MaxTrackNUP – Double_t: Max of the track bins Normalized Unitless Power (NUP)
- TotalWideTrackSNR – Double_t: Sum of the track extended bins SNR
- TotalWideTrackNUP – Double_t: Sum of the track extended bins Normalized Unitless Power (NUP)
- StartTimeInRunCSigma – Double_t: error on the start time of the track in the Katydid instance
- EndTimeInRunCSigma – Double_t: error on the end time of the track in the Katydid instance
- TimeLengthSigma – Double_t: error on the track length
- StartFrequencySigma – Double_t: error on the track start frequency
- EndFrequencySigma – Double_t: error on the track end frequency
- FrequencyWidthSigma – Double_t: error on the range of frequencies covered by the track
- SlopeSigma – Double_t: error on the slope track
- InterceptSigma – Double_t: error on the track intercept
- TotalPowerSigma – Double_t: error on the sum of the power of the bins composing the track
Version 1.1.0¶
TMultiTrackEventData¶
- Component – UInt_t:
- AcquisitionID – UInt_t:
- EventID – UInt_t: number of the event in the katydid instance
- TotalEventSequences – UInt_t: number of sequences in the event
- StartTimeInRunC – Double_t: start time of the event in the Katydid instance
- StartTimeInAcq – Double_t: start time of the event within the chunk of data
- EndTimeInRunC – Double_t: end time of the event in the Katydid instance
- TimeLength – Double_t: duration of the event
- StartFrequency – Double_t: start frequency of the event
- EndFrequency – Double_t: end frequency of the event
- MinimumFrequency – Double_t: minimum frequency reached by the event
- MaximumFrequency – Double_t: maximum frequency reached by the event
- FrequencyWidth – Double_t: range of frequencies covered by the event tracks
- NTrackBins – UInt_t: number of bins in the track
- TotalTrackSNR – Double_t: Sum of the track bins SNR
- MaxTrackSNR – Double_t: Max of the track bins SNR
- TotalTrackNUP – Double_t: Sum of the track bins Normalized Unitless Power (NUP)
- MaxTrackNUP – Double_t: Max of the track bins Normalized Unitless Power (NUP)
- TotalWideTrackSNR – Double_t: Sum of the track extended bins SNR
- TotalWideTrackNUP – Double_t: Sum of the track extended bins Normalized Unitless Power (NUP)
- StartTimeInRunCSigma – Double_t: error on the start time of the event in the Katydid instance
- EndTimeInRunCSigma – Double_t: error on the end time of the event in the Katydid instance
- StartFrequencySigma – Double_t: error on the start frequency of the event
- EndFrequencySigma – Double_t: error on the end frequency of the event
- FrequencyWidthSigma – Double_t: error on the range of frequencies covered by the event tracks
- FirstTrackID – UInt_t: ID number of the first track in the event
- FirstTrackTimeLength – Double_t: length of the first track
- FirstTrackFrequencyWidth – Double_t: range of frequencies covered by the first track
- FirstTrackSlope – Double_t: slope of the first track
- FirstTrackIntercept – Double_t: intercept at t=0 of the first track
- FirstTrackTotalPower – Double_t: sum of the power of the bins composing the first track
- UnknownEventTopology – Double_t: boolean describing if a track has some weird topology
TProcessedTrackData¶
- Component – UInt_t:
- AcquisitionID – UInt_t:
- TrackID – UInt_t: number of the track in the event
- EventID – UInt_t: number of the event in the katydid instance
- EventSequenceID – UInt_t: number of the sequence in the event reconstruction
- IsCut – Bool_t: should this line be cut when calculating the start frequency…?
- StartTimeInRunC – Double_t: start time of the track in the Katydid instance
- StartTimeInAcq – Double_t: start time of the track within the chunk of data
- EndTimeInRunC – Double_t: end time of the track in the Katydid instance
- TimeLength – Double_t: track length
- StartFrequency – Double_t: start frequency of the track
- EndFrequency – Double_t: end frequency of the track
- FrequencyWidth – Double_t: range of frequencies covered by the track
- Slope – Double_t: slope of the track
- Intercept – Double_t: intercept at t=0 of the track
- TotalPower – Double_t: sum of the power of the bins composing the track
- StartTimeInRunCSigma – Double_t: error on the start time of the track in the Katydid instance
- EndTimeInRunCSigma – Double_t: error on the end time of the track in the Katydid instance
- TimeLengthSigma – Double_t: error on the track length
- StartFrequencySigma – Double_t: error on the track start frequency
- EndFrequencySigma – Double_t: error on the track end frequency
- FrequencyWidthSigma – Double_t: error on the range of frequencies covered by the track
- SlopeSigma – Double_t: error on the slope track
- InterceptSigma – Double_t: error on the track intercept
- TotalPowerSigma – Double_t: error on the sum of the power of the bins composing the track
Version 0.4.2¶
TMultiTrackEventData¶
- Component – UInt_t:
- AcquisitionID – UInt_t:
- EventID – UInt_t: number of the event in the katydid instance
- TotalEventSequences – UInt_t: number of sequences in the event
- StartTimeInRunC – Double_t: start time of the event in the Katydid instance
- StartTimeInAcq – Double_t: start time of the event within the chunk of data
- EndTimeInRunC – Double_t: end time of the event in the Katydid instance
- TimeLength – Double_t: duration of the event
- StartFrequency – Double_t: start frequency of the event
- EndFrequency – Double_t: end frequency of the event
- MinimumFrequency – Double_t: minimum frequency reached by the event
- MaximumFrequency – Double_t: maximum frequency reached by the event
- FrequencyWidth – Double_t: range of frequencies covered by the event tracks
- StartTimeInRunCSigma – Double_t: error on the start time of the event in the Katydid instance
- EndTimeInRunCSigma – Double_t: error on the end time of the event in the Katydid instance
- StartFrequencySigma – Double_t: error on the start frequency of the event
- EndFrequencySigma – Double_t: error on the end frequency of the event
- FrequencyWidthSigma – Double_t: error on the range of frequencies covered by the event tracks
- FirstTrackID – UInt_t: ID number of the first track in the event
- FirstTrackTimeLength – Double_t: length of the first track
- FirstTrackFrequencyWidth – Double_t: range of frequencies covered by the first track
- FirstTrackSlope – Double_t: slope of the first track
- FirstTrackIntercept – Double_t: intercept at t=0 of the first track
- FirstTrackTotalPower – Double_t: sum of the power of the bins composing the first track
- UnknownEventTopology – Double_t: boolean describing if a track has some weird topology
TProcessedTrackData¶
- Component – UInt_t:
- AcquisitionID – UInt_t:
- TrackID – UInt_t: number of the track in the event
- EventID – UInt_t: number of the event in the katydid instance
- EventSequenceID – UInt_t: number of the sequence in the event reconstruction
- IsCut – Bool_t: should this line be cut when calculating the start frequency…?
- StartTimeInRunC – Double_t: start time of the track in the Katydid instance
- StartTimeInAcq – Double_t: start time of the track within the chunk of data
- EndTimeInRunC – Double_t: end time of the track in the Katydid instance
- TimeLength – Double_t: track length
- StartFrequency – Double_t: start frequency of the track
- EndFrequency – Double_t: end frequency of the track
- FrequencyWidth – Double_t: range of frequencies covered by the track
- Slope – Double_t: slope of the track
- Intercept – Double_t: intercept at t=0 of the track
- TotalPower – Double_t: sum of the power of the bins composing the track
- StartTimeInRunCSigma – Double_t: error on the start time of the track in the Katydid instance
- EndTimeInRunCSigma – Double_t: error on the end time of the track in the Katydid instance
- TimeLengthSigma – Double_t: error on the track length
- StartFrequencySigma – Double_t: error on the track start frequency
- EndFrequencySigma – Double_t: error on the track end frequency
- FrequencyWidthSigma – Double_t: error on the range of frequencies covered by the track
- SlopeSigma – Double_t: error on the slope track
- InterceptSigma – Double_t: error on the track intercept
- TotalPowerSigma – Double_t: error on the sum of the power of the bins composing the track
Versions¶
As Katydid expands, the content of the Cicada might change: the table below summarizes the compatibility between Cicada and Katydid versions.
Cicada version | Katydid files version |
---|---|
0.1.0+ | 2.7.0+ |
0.4.2+ | 2.10.0+ |
1.0.0+ | 2.10.1+ |
1.1.0+ | 2.1X.Y+ |
1.4.0+ | ? |
Contributions¶
Reporting bugs¶
You can report bugs using the Cicada issue tracker. When doing so, please provide your configuration (gcc, cmake and ROOT versions, virtual environment) and a detailed description of the steps to reproduce the bug.
Development scheme, code testing et release procedure¶
Development scheme¶
The Project 8 collaboration has adopted the Git flow development scheme: you can find details and the correct git commands about how to use it on this page. For a more visual way of developing code, the use of the SourceTree application is recommended as it natively integrates the Git flow scheme.
Code testing with Docker¶
If you would like to modify your local installation of Cicada (to add features or resolve any bugs), we recommend you use a Docker container as a uniform test bench. To do so: * Install Docker: https://docs.docker.com/engine/installation/ * Clone and pull the latest master version of Cicada * Inside the cicada folder, execute
docker build -t cicada .
docker run -it cicada bash
A new terminal prompter (for example, root@413ab10d7a8f:) should appear. Then you have to load the environment:
source /setup.sh
You may make changes to Cicada either inside or outside of the Docker container. If you wish to work outside of the container, you will need to mount a local folder in the container (see Docker documentation).
You can remove the container image using
docker rmi Cicada_Cicada
Release procedure¶
When making a release or a hotfix, several steps shall be done:
- update the documentation (see Documentation section)
- update the project number in the top CMakeLists.txt file
- update the authors lists (if applicable)
- update the Documentation/ValidationLog.rst file
After making the release:
- create a release entry on Github and add the corresponding entry from the ValidationLog.rst file
Contributing to the code¶
If you are new to the code and are willing to contribute by developing new features or maintaining the code, please refer to the issue tracker. There are issues you can look at and decide on solving. When you have found your ideal issue, please comment in the issue tracker, so the main developers are aware you are working on this.
If you wish to contribute to maintaining a proper documentation, please refer to the Documentation section.
Documentation¶
The documentation of Cicada happens at several levels:
- in the repository, we maintain README.md files describing the content of each folder.
- in the Documentation folder, we maintain RST files. With each release of the code, ReadTheDocs reads these files and produces pages (such as this one).
- inside the code, documentation is provided as comments and Doxygen headers. Once compiled by ReadTheDocs, it produces a proper Doxygen documentation of the code.
- a ValidationLog.rst file keeps track of the new features or fixes added to the code. For each Github issue solved, a entry describing the solved issue (and its Github number) should be added in the upcoming release subsection.
This documentation must be updated at any release/hotfix/pull-request to keep the repository as up-to-date as possible.
Validation Log¶
Guidelines¶
- All new features incorporated into a tagged release should have their validation documented. * Document the new feature. * Perform tests to validate the new feature. * If the feature is slated for incorporation into an official analysis, perform tests to show that the overall analysis works and benefits from this feature. * Indicate in this log where to find documentation of the new feature. * Indicate in this log what tests were performed, and where to find a writeup of the results.
- Fixes to existing features should also be validated. * Perform tests to show that the fix solves the problem that had been indicated. * Perform tests to show that the fix does not cause other problems. * Indicate in this log what tests were performed and how you know the problem was fixed.
Log¶
Version: v1.4.0¶
Release Date: July 21, 2021¶
New Features:¶
- Updated Scarab to v3.6.1
- Modernized CMake build
- Removed Katydid namespace classes
Version: v1.3.3¶
Release Date: March 28th 2019¶
Fixes:¶
- ReadKTOutput: Avoid crash when object doesn’t exist in file
Version: 1.3.1¶
Release Date: Dec 5, 2018¶
Fixes:¶
- Removing unused libraries (yaml, json, param) from build
- Switched docker build to use COPY instead of git clone
Version: 1.3.0¶
Release Date: Nov 29, 2018¶
New Features:¶
- New Dockerfile based on the p8compute-dependencies container
- Added this_cicada.sh script to properly set ROOT include path and python path
- Fixed the ROOT dictionary build so that it doesn’t hard-code source-tree paths
Version: 1.2.0¶
Release Date: June 15th, 2018¶
New Features:¶
- TMultiTrackEventData: adding SNR and NUP based quantities for the first track:
- FirstTrackNTrackBins
- FirstTrackTotalSNR
- FirstTrackMaxSNR
- FirstTrackTotalNUP
- FirstTrackMaxNUP
- FirstTrackTotalWideSNR
- FirstTrackTotalWideNUP
Version: 1.1.1¶
Release Date: June 7th, 2018¶
Fixes:¶
- Bumping ClassDef version for TProcessedTrackData
Version: 1.1.0¶
Release Date: June 1st, 2018¶
New Features:¶
- TProcessedTrackData: adding SNR and NUP based quantities:
- NTrackBins
- TotalTrackSNR
- MaxTrackSNR
- TotalTrackNUP
- MaxTrackNUP
- TotalWideTrackSNR
- TotalWideTrackNUP
- Moving the default object name from the Katydid Writer into Cicada:
- TMultiTrackEventData
- TProcessedTrackData
- TProcessedMPTData (not done as inherits from TMultiTrackEventData)
- TClassifierResultsData
- ReadKTOutputFile:
- Extraction of tracks information from TMultiTrackEventData.
- Extraction of multiple branches without one execution.
Version: 1.0.2¶
Release Date: April 12, 2018¶
New Features:¶
- ReadKTOutputFile: Support of Cicada and Katydid namespaces and access to TMultiTrackEventData members.
Fixes:¶
- Documentation update about the python libraries.
Version: 1.0.1¶
Release Date: April 10, 2018¶
Fixes:¶
- Docker: Sleep time after chmod of installation script.
Version: 1.0.0¶
Release Date: March 29, 2018¶
New Features:¶
- Classification related objects; added CMTEWithClassifierResultsData, CClassifierResultsData, and CProcessedMPTData.
- Definition of a Cicada-specific prefixes for Set, Get and variables; added CMemberVariables.hh.
Fixes:¶
- Docker: correction of the installation location (from /cicada/build to /build).
- Documentation/Doxygen updates.
Version: 0.4.2¶
Release Date: March 14, 2018¶
New Features:¶
Fixes:¶
- Fixed the namespace in the constructor for the Tracks TClonesArray in TMultiTrackEventData.
Version: 0.4.1¶
Release Date: February 22, 2018¶
New Features:¶
Fixes:¶
- Add const return of the Tracks TClonesArray in TMultiTrackEventData.