# AnalysisTimingATLASpix
**Maintainer**: Jens Kroeger ()
**Module Type**: *DUT*
**Detector Type**: *ATLASpix*
**Status**: Functional
### Description
This module can be used for an in-depth timing analysis of the ATLASpix, including row and timewalk corrections.
The ATLASpix shows a row-dependent shift of the time residuals which can be corrected for.
Timewalk describes a shift of the time residual depending on the signal strength which can be deduced from the time-over-threshold in the ATLASpix.
Also this can be corrected for for an improved time resolution.
Before being able to apply the row and timewalk correction, correction files need to be provided.
These can be generated by setting `calc_corrections=true`.
The calculation of the timewalk correction is based on a row-corrected histogram such that this procedure needs to be performed in two steps.
The row correction should be generally valid whereas the timewalk correction is threshold dependent and thus needs to be repeated each time the threshold is changed.
1. Calculate row correction.
2. Use row correction file and calculate timewalk correction.
After this both corrections can be applied consecutively.
### Parameters
* `time_cut_rel`: Number of standard deviations the `time_resolution` of the detector plane will be multiplied by. This value then defines the range of the track time correlation histograms and should be set according to the value chosen for the `[DUTAssociation]`. By default, a relative time cut is applied. Absolute and relative time cuts are mutually exclusive. Defaults to `3.0`.
* `time_cut_abs`: Specifies an absolute value for the range of the track time correlation histograms and should be set according to the value chosen for the `[DUTAssociation]`. Absolute and relative time cuts are mutually exclusive. No default value.
* `chi2ndof_cut`: Acceptance criterion for telescope tracks, defaults to a value of `3`.
* `time_cut_frameedge`: Parameter to discard telescope tracks at the frame edges (start and end of the current frame). Defaults to `20ns`.
* `cluster_charge_cut`: Parameter to discard clusters with a charge larger than the cut. No default, not used if not set.
* `cluster_size_cut`: Parameter to discard clusters with a size too large, only for debugging purposes. No default, not used if not set.
* `high_tot_cut`: Cut dividing 'low' and 'high' ToT events (based on seed pixel ToT). Defaults to `40`.
* `high_charge_cut`: Cut dividing 'low' and 'high' charge events (based on cluster charge in electrons). Defaults to `high_tot_cut` (modify when calibration is available).
* `left_tail_cut`: Cut to divide into left tail and main peak of time correlation histogram. Only used to investigate characteristics of left tail. Defaults to `-10ns`.
* `calc_corrections`: If `true`, TGraphErrors for row and timewalk corrections are produced.
* `correction_file_row`, `correction_file_timewalk`. Defaults to `false`.
* `correction_file_row`: Path to file which contains TGraphErrors for row correction. If this parameter is set, also `correction_graph_row` needs to be set. No default.
* `correction_file_timewalk`: Path to file which contains TGraphErrors for timewalk correction. If this parameter is set, also `correction_graph_timewalk` needs to be set. No default.
* `correction_graph_row`: Name of the TGraphErrors including its path in the root file used for row correction. E.g. "AnalysisTimingATLASpix/apx_0/gTimeCorrelationVsRow". No default.
* `correction_graph_timewalk`: Name of the TGraphErrors including its path in the root file used for row correction. E.g. "AnalysisTimingATLASpix/apx_0/gTimeCorrelationVsTot". No default.
### Plots produced
For the DUT, the following plots are produced:
* 1D histograms
* Track time correlations for all clusters, track-associated clusters, after row correction, after row and timewalk correction ( all, for clusterToT < 25 lsb, for clusterToT < 40 lsb, for clusterToT > 40 lsb)
* Track time correlation example slice of 2D plot to investigate quality of Gaussian fit
* Cluster time minus pixel time (for all pixels in cluster) to confirm that cluster time = time of earliest pixel
* Pixel ToT for main peak and left tail events in time correlation (track timestamp - cluster timestamp < left_tail_cut), (track timestamp - cluster timestamp > left_tail_cut)
* Pixel timestamp for main peak and left tail events in time correlation (track timestamp - cluster timestamp < left_tail_cut), (track timestamp - cluster timestamp > left_tail_cut)
* Cluster size for main peak and left tail events in time correlation (track timestamp - cluster timestamp < left_tail_cut), (track timestamp - cluster timestamp > left_tail_cut)
* 2D histograms
* Track time correlation vs. time (track-associated clusters), column (only control plot), cluster row (for row correction), cluster row (only single pixel clusters, only multi-pixel clusters, after row correction), seed pixel ToT (for timewalk correction, only single pixel clusters, only multi-pixel clusters)
* Track time correlation vs. cluster row (after row correction), (after row correction, only single pixel clusters), (after row correction, only multi-pixel clusters), (after row and timewalk correction), (after row and timewalk correction)
* Cluster size vs. cluster ToT (only associated clusters)
* Hit map of all pixels from associated clusters with/without high ToT
* In-pixel distribution of tracks for clysters with/without high ToT
* Map of associated clusters
* Pixel ToT vs. time for all clusters and for high ToT clusters
* Cluster map for main peak and left tail events in time correlation (track timestamp - cluster timestamp < left_tail_cut), (track timestamp - cluster timestamp > left_tail_cut)
* TGraphErrors
* Peak of time correlation vs. row
* Peak of time correlation vs. ToT (after row correction)
* Peak of time correlation vs. row (after row correction, only single pixel clusters), (after row correction, only multi-pixel clusters)
### Usage
```toml
[AnalysisTimingATLASpix]
calc_corrections = false
correction_file_row = "correction_files/row_correction_file.root"
correction_graph_row = "AnalysisTimingATLASpix/apx0/gRTimeCorrelationVsRow"
correction_file_timewalk = "correction_files/timewalk_correction_file.root"
correction_graph_timewalk = "AnalysisTimingATLASpix/apx0/gTimeCorrelationVsTot"
```