# trace_analyzer

**Reliability status**: `development`

*Read a trace table and derive several different analysis, including the distribution of number barcodes per trace: total, duplicated, and non-duplicated. It also exports the Rg distribution.*


```{eval-rst}
.. argparse::
   :ref: traceratops.trace_analyzer.parse_arguments
   :prog: trace_analyzer
```

## Description
A Python script for analyzing chromatin trace files. The script loads trace files and generates statistical analysis and visualizations of various properties:
- Number of barcodes detected per trace
- Number of duplicated barcodes
- Distribution of localizations in X, Y, Z coordinates
- Distances between consecutive neighboring barcodes
- Visual representations of traces
- Barcode detection efficiency analysis with bootstrapped error estimates

## Usage

```bash
# Analyze a single trace file
trace_analyzer --input path/to/your/trace_file.ecsv

# Analyze multiple trace files using pipe
find /path/to/traces -name "*.ecsv" | trace_analyzer --pipe

# Specify a different root folder
trace_analyzer --rootFolder /custom/data/folder --input trace_file.ecsv

# Generate SVG output instead of PNG
trace_analyzer --input trace_file.ecsv --format svg

# Generate XYZ plots in addition to statistics
trace_analyzer --input trace_file.ecsv --plotXYZ
```

## Output Files

For each trace file analyzed, the script generates:

1. `[tracefile]_relative_barcode_frequencies`: Number of barcodes per trace, for each separate barcode. If only the top row is occupied, barcodes are present only once per trace. The second row represents the number of times barcodes are present twice in the trace, and so on.
[](../../_static/merged_traces_relative_barcode_frequencies.png)

3. `[tracefile]_barcode_detection.[format]`: Plot of barcode detection efficiency. Errorbars are obtained by bootstrapping.
![](../../_static/merged_traces_barcode_detection.png)

1. `[tracefile]_trace_statistics.[format]`: Histograms of number of barcodes per trace.
!![](../../_static/merged_traces_trace_statistics.png)

5. `[tracefile]_kde_projections.[format]`: Traces are translated to their center of mass and reprojected along XY, XZ and YZ.
![](../../_static/merged_traces_filtered_split_kde_projections.png)

2. `[tracefile]_first_neighbor_distances.[format]`: Top plots represent the histogram of distances between next and previous neighbour for each barcode in the trace, for all traces, in XY and in XYZ. Bottom plots show histograms of distances between consecutive genomic barcodes in X, Y and Z.

![](../../_static/merged_traces_filtered_split_first_neighbor_distances.png)