.. _configuration:

Configuration files
===================

Detector configuration
----------------------

:name:          Name of the detector.

:data_type:     Defines the raw data loader. Built-in options are:

                :standard:      The data mode native to Listmode. All other data is converted to native
                                format before parsing

                :caen:          The data file saved by Caen MC2 program with extra data set on.

                :panda:         For PANDA data files.

                :ortec:         For data files saved with Ortec Maestro program.

:extension:     The extension of the raw data files. Extension can include wildcard characters.

:daq_type:      Might be redundant.

:coinc_win:     Coincidence window length in nanoseconds. This is the max time interval between two
                counts so that they will be built into a single event.

:sample_ns:     Size of the time tick of the detector in ns.

:readout_cfg:   Optional, will probably be moved to another config file. Defines readout electronics
                specific configuration file used for daq.

:cal_name:      Name of the energy calibration file for the detector. Located in config/ecal directory.

:effcal:        Name of the gamma efficiency calibration file. Located in config/effcal directory.

:ch_cfg:        List of ch_config dictionaries. One per channel.

:events:        Definition of energy information. A data_info dictionary.

:extras:        Definition of any extra data. A list of data_info dictionaries.

:latency:       Latency values in ns. A list of values, one per channel, which are added to channel
                timestamps before searching for coincidences.

:histo_size:    Optional, will probably be moved to another config file. Defines the number of bins in
                the histogram returned by daq.

:ch_list:       List of channels with indices to 'ch_cfg' list. Defines the order (and number) of
                channels in the output. Functionality of this may be changed in the future.


ch_config
^^^^^^^^^

:name:          Name of the channel. Will appear in title and legend of plots.

:cfg_file:      Optional, will probably be moved to another config file. Defines readout channel
                specific configuration file used for daq.

:pdeadtime:     Dead time of a single pulse in the channel. This value will be used to calculate
                estimated dead time in data formats where hardware calculated dead time does not
                exist (Caen) or where it cannot be fully trusted (Caen). This value includes the
                rise time, flat top and any trigger holdoff values and needs to be corrected whenever
                configuration is changed.

data_info
^^^^^^^^^

:name:          the name of the data. Energy information is always 'energy' and value in this field is
                ignored.

:type:          Numpy type string describing the data format in the binary file. For energy the default
                is 'i2' for signed 16-bit integer. Extras don't have defaults and type must be defined.

:ch_mask:       Defines which energy channels have this extra associated with. Given as a list of zeros
                and ones. Energy data is always one column per channel and this key is ignored. Default
                is all channels.

:aggregate:     Defines how the data is combined or created in the event parser. Normally extras are just
                read from channel files and combined as events in the event construction. Some builtin
                extra data types are created while the events are built and exist only as final data.

                :col:           Data is saved as columns in a matrix with number of columns defined by 'ch_mask'.

                :bit:           Bit mask with a single bit ber channel.

                :latency:       *Builtin extra.* The time difference between counts in different channels. Needs
                                additional key 'main' to define the channel that is compared against the others.
                                Output is always (number of channels - 1) columns.

                :multihit:      *Builtin extra.* A bit mask with bit set on a channel that received multiple
                                hits per event.

:multi:         Defines what happens if two or more hits are detected in a single channel within a single
                event (inside the coincidence window). Valid values are:

                :sum:           Sum of the values

                :max:           Maximum of the values

                :min:           Minimum of the values

                :mean:          Mean of the values

                :kill:          The event is discarded

                :max_e:         Value in the hit where energy is largest

:raw unit:      String that is used as unit for uncalibrated data. Default is 'ch'.

:unit:          String that is used for calibrated data. Default for energy is 'KeV'.

:empty_val:     Value given to channels that don't have information. Default for energy is -1, for all
                other extras the default is 0. Latency extra has this set to smallest value of the datatype
                and ignores this parameter.

:num_col:       Number of columns in the parsed data matrix. It is automatically calculated. For energy it is the number
                of channels, for extras this value is calculated based on 'ch_mask' or defined by the type of inbuilt
                extra. It is used by the data loader.

:main:          'main' is used by the 'latency' aggregate to single out which channel time is compared against
                the others.

Plot configuration
------------------
Plot configuration defines the data in the plot as well as the plotting parameters, such as labels, scales etc.
Only one plot can be defined per Plot object. However multiple plots can be stacked into the plot_cfg list of the plot
configuration. If all of the plots are 1d and have same axes they can be plotted into a single figure. Creating figures
and handling how to stack plots into figures should be done explicitly by the user. Two Plot instances can be compared
for equality. The result is True only if they can be shown in the same axes. The Plot class uses only the information
in plot_cfg and the name.

:name:          Name of the canvas. Will be visible in the title of the plot.

:plot_cfg:      List defining all plots in the configuration file. If multi plot configuration is given the index of the
                plot has to be set by plot_idx keyword on initialization of the Plot object. First plot in this list is
                configured if index is not given. A plot is defined by its name, axes and gates:

                :plot_name:     Name for the individual plot that helps to understand the content of the plot. Will be
                                visible in the legend of 1d plots and as the label of the colorbar in 2d plots.

                :axes:          An axis info dictionary defining the x-axis of the plot or a list defining two
                                axis_infos for a 2d plot.

                :gates:         A list of gate_info dictionaries. All gates in this list are applied in AND mode.

The rest of the plot configuration is not used by listmode library at all.

:xscale:        Defines whether x axis of a plot is logarithmic ("log") or linear ("linear",
                default).

:yscale:        Defines whether x axis of a plot is logarithmic ("log") or linear ("linear",
                default).

:zscale:        Defines whether z axis (colorbar) of a 2d-plot is logarithmic ("log") or linear
                ("linear", default)

:reverse_x_axis: Optional string that defines whether x-axis is reversed in a plot.

:reverse_y_axis: Optional string that defines whether y-axis is reversed in a plot.


axis_info
^^^^^^^^^
A dictionary defining each data axis of the plot:
:channel:       The channel to plot. Note that some extra data have different number of channels. Note also that this
                defines the name printed to legend for 1d plots, also for time axes. It should match the gate used
                for selecting the data (if applicable) for time plots.

:data:          A string defining the name of the data to be plotted on this axis. This can be "time", "energy" or any of
                the extras.

:bin_width:     For normal data this is an integer width of bin in raw units. Note, for time axis this is in timebase
                units instead and fractional bin widths can be used.

:range:         A two item list defining lower and upper limits in calibrated units. Ignored with time axes.

:timebase:      Only relevant for time axes. A string defining the base unit for time axes.
                ("ns", "us", "ms", "s", "m", "h" and "d").

gate_info
^^^^^^^^^
A dictionary defining a gate
:channel:       The channel to gate with.

:data:          A string defining the name of the data to be gated with. This can be "time", "energy" or any of the extras.

:range:         A nested list defining the ranges that are used for the gate. Each range is a list of start and stop values.
                The ranges are defined in calibrated units. Bitmask type data ignores range. An event is in range if
                True and not if False.

:coinc:         An integer defining whether the gate is anticoincident (negative integer), coincident (positive
                integer) or null (zero). Coincident gate only passes events with data value in that channel contained
                within the gate range, anticoincident passes if not. A zero defines a null gate. It will not cause
                filtering of the data - it is not processed at all. Use null gates to switch off gates quickly.
