# Tutorial of regions versus regions

In this tutorial, we will demonstrate how we can use RGT-Viz to visualize association among different region sets.

## Download the data

We will use the epigenetic data from dendritic cell development study as example. There, we have ChIP-Seq data from the transcription factor **PU.1** and **IRF8**, and histone modifications **H3K4me1**, **H3K4me3**, **H3K9me3**, **H3K27me3**, and **H3K27ac** on four cellular states: multipotent progenitors (MPP), dendritic cell progenitors (CDP), common dendritic cells (cDC) and plamatocyte dendritic cells (pDC). The functional annotation of these histone markers are showed as follows:

* H3K4me1 is enriched at active and primed enhancers;
* H3K4me3 is highly enriched at active promoters near Transcription start site (TSS);
* H3K9me3 is a marker of heterochromatin which has pivotal role during lineage commitement;
* H3K27me3 is associated with the downregulation of nearby genes via the formation of heterochromatic regions;
* H3K27ac is accociated with the higher activation of transcription and defined as an active enhancer marker.

The peaks of **PU.1** and **IRF8** are further processed into 3 groups: overlapping peaks of PU.1 and IRF8, PU.1 peaks (no IRF8), and IRF8 peaks (no PU.1). Those files are listed below:
* PU1_IRF8_pDC_overlap_peaks.bed
* PU1_pDC_noIRF8_peaks.bed
* IRF8_pDC_noPU1_peaks.bed
* PU1_IRF8_cDC_overlap_peaks.bed
* PU1_cDC_noIRF8_peaks.bed
* IRF8_cDC_noPU1_peaks.bed

Next, please download the folder “rgt_viz_example” from [here](https://costalab.ukaachen.de/open_data/RGT/rgt_viz_example.zip).

```shell
unzip rgt_viz_example
cd rgt_viz_example
```

Now you have the files as described below:

```shell
data/
├── bw
│   ├── H3K27ac_cDC.bw
│   ├── H3K27ac_CDP.bw
│   ├── H3K27ac_MPP.bw
│   ├── H3K27ac_pDC.bw
│   ├── H3K27me3_cDC.bw
│   ├── H3K27me3_CDP.bw
│   ├── H3K27me3_MPP.bw
│   ├── H3K27me3_pDC.bw
│   ├── H3K4me1_cDC.bw
│   ├── H3K4me1_CDP.bw
│   ├── H3K4me1_MPP.bw
│   ├── H3K4me1_pDC.bw
│   ├── H3K4me3_cDC.bw
│   ├── H3K4me3_CDP.bw
│   ├── H3K4me3_MPP.bw
│   ├── H3K4me3_pDC.bw
│   ├── H3K9me3_cDC.bw
│   ├── H3K9me3_CDP.bw
│   ├── H3K9me3_MPP.bw
│   ├── H3K9me3_pDC.bw
│   ├── IRF8_cDC.bw
│   ├── IRF8_pDC.bw
│   ├── PU1_cDC.bw
│   ├── PU1_CDP.bw
│   ├── PU1_MPP.bw
│   └── PU1_pDC.bw
└── peaks
    ├── H3K4me3_cDC_WT_peaks.bed
    ├── H3K4me3_CDP_WT_peaks.bed
    ├── H3K4me3_MPP_WT_peaks.bed
    ├── H3K4me3_pDC_WT_peaks.bed
    ├── PU1_IRF8_cDC_overlap_peaks.bed
    ├── IRF8_cDC_noPU1_peaks.bed
    ├── PU1_cDC_noIRF8_peaks.bed
    ├── PU1_IRF8_pDC_overlap_peaks.bed
    ├── IRF8_pDC_noPU1_peaks.bed
    └── PU1_pDC_noIRF8_peaks.bed
```

These directories include the genomic signals of histone modifications (files with a .bw ending as generated by [bamCoverage](https://deeptools.readthedocs.io/en/develop/content/tools/bamCoverage.html)) and the genomic regions of PU.1 and IRF8 peaks (files with .narrowPeak endings as generated by [MACS2](https://genomebiology.biomedcentral.com/articles/10.1186/gb-2008-9-9-r137)) in different DC cells.

With these data, the first question we would like to ask is: are PU.1 and IRF8 co-binders in DC differentiation? If so, in which cells?

## Intersection test
For evaluating the association between PU.1 and IRF8, the [intersection test](https://reg-gen.readthedocs.io/en/latest/rgt-viz/method.html#intersection-test) is applied on the ChIP-seq binding regions of PU.1 on all cell types to compare with the ChIP-seq binding regions of IRF8 on cDC and pDC (the ChIP-seq binding regions of IRF8 in CDP and MPP are not available).

```shell
rgt-viz intersect -r Matrix_PU1.txt -q Matrix_IRF8.txt -o results -t PU1_IRF8_intersection -organism mm9 -stest 30
```
- -r is reference region set as the base for statistics;
- -q is query region set for testing its association with the reference regions;
- -o indicates the output directory;
- -t defines the title of this experiment;
- -c defines the color tag for cloring the test;
- -organism defines the genome assembly used here;
- -stest defines the repitition times of random subregion test between reference and query. The more repitition times are, the more reliable the result is. However, it take time to run.

This command will generate a directory “<em>results/PU1_IRF8_intersection</em>” with figures and html pages.

<p align="center">
<img src="../_static/rgt-viz/intersection_bar.png" width=500 align="center">
</p>

The exact numbers of intersected regions between PU.1 and IRF8, and p-values are shown in below table:

<p align="center" style="margin-left: 50">
<table border="1" id="sortable" class="tablesorter">
	<thead>
		<tr>
    		<th scope="col" width="10" align="center">Reference<br>name</th>
    		<th scope="col" width="10" align="center">Query<br>name</th>
    		<th scope="col" width="10" align="center">Reference<br>number</th>
    		<th scope="col" width="10" align="center">Query<br>number</th>
    		<th scope="col" width="10" align="center">Intersect.</th>
    		<th scope="col" width="10" align="center">Average<br>intersect.</th>
    		<th scope="col" width="10" align="center">Chi-square<br>statistic</th>
    		<th scope="col" width="10" align="center">Positive<br>Association<br>p-value</th>
    		<th scope="col" width="10" align="center">Negative<br>Association<br>p-value</th>
		</tr>
	</thead>
	<tbody>
		<tr>
			<td align="center" >MPP_PU1_peaks</td>
			<td align="center" >cDC_IRF8_peaks</td>
			<td align="center" >6212</td>
			<td align="center" >34003</td>
			<td align="center" >4412</td>
			<td align="center" >1163</td>
			<td align="center" >3359</td>
			<td align="center" ><font color="red">0</font></td>
			<td align="center" >1.00</td>
		</tr>
		<tr>
			<td align="center" >MPP_PU1_peaks</td>
			<td align="center" >pDC_IRF8_peaks</td>
			<td align="center" >6212</td>
			<td align="center" >6467</td>
			<td align="center" >1745</td>
			<td align="center" >848.5</td>
			<td align="center" >351.3</td>
			<td align="center" ><font color="red">5.1e-77</font></td>
			<td align="center" >1.00</td>
		</tr>
		<tr>
			<td align="center" >CDP_PU1_peaks</td>
			<td align="center" >cDC_IRF8_peaks</td>
			<td align="center" >20237</td>
			<td align="center" >34003</td>
			<td align="center" >14003</td>
			<td align="center" >6574</td>
			<td align="center" >4438</td>
			<td align="center" ><font color="red">0</font></td>
			<td align="center" >1.00</td>
		</tr>
		<tr>
			<td align="center" >CDP_PU1_peaks</td>
			<td align="center" >pDC_IRF8_peaks</td>
			<td align="center" >20237</td>
			<td align="center" >6467</td>
			<td align="center" >4078</td>
			<td align="center" >1494</td>
			<td align="center" >1979</td>
			<td align="center" ><font color="red">0</font></td>
			<td align="center" >1.00</td>
		</tr>
		<tr>
			<td align="center" >cDC_PU1_peaks</td>
			<td align="center" >cDC_IRF8_peaks</td>
			<td align="center" >20054</td>
			<td align="center" >34003</td>
			<td align="center" >13973</td>
			<td align="center" >6538</td>
			<td align="center" >4489</td>
			<td align="center" ><font color="red">0</font></td>
			<td align="center" >1.00</td>
		</tr>
		<tr>
			<td align="center" >cDC_PU1_peaks</td>
			<td align="center" >pDC_IRF8_peaks</td>
			<td align="center" >20054</td>
			<td align="center" >6467</td>
			<td align="center" >4066</td>
			<td align="center" >1497</td>
			<td align="center" >1955</td>
			<td align="center" ><font color="red">0</font></td>
			<td align="center" >1.00</td>
		</tr>
		<tr>
			<td align="center" >pDC_PU1_peaks</td>
			<td align="center" >cDC_IRF8_peaks</td>
			<td align="center" >21050</td>
			<td align="center" >34003</td>
			<td align="center" >14307</td>
			<td align="center" >6757</td>
			<td align="center" >4367</td>
			<td align="center" ><font color="red">0</font></td>
			<td align="center" >1.00</td>
		</tr>
		<tr>
			<td align="center" >pDC_PU1_peaks</td>
			<td align="center" >pDC_IRF8_peaks</td>
			<td align="center" >21050</td>
			<td align="center" >6467</td>
			<td align="center" >4137</td>
			<td align="center" >1478</td>
			<td align="center" >2100</td>
			<td align="center" ><font color="red">0</font></td>
			<td align="center" >1.00</td>
		</tr>
</tbody>
</table>
</p>

The intersection test reveals that PU.1 and IRF8 are associated significantly in all cell types as shown in the 8th column. Though there are many overlaps between IRF8 and PU.1 in all cell types, the table shows that the highest number of overlaps appears between PU.1 and IRF8 in cDC.

## Jaccard test
Alternatively, we can use [Jaccard test](https://reg-gen.readthedocs.io/en/latest/rgt-viz/method.html#jaccard-test) to evaluate the association level between PU.1 and IRF8 by comparing with jaccard index from repeating randomization.

Run the command:
```shell
rgt-viz jaccard -r Matrix_PU1.txt -q Matrix_IRF8.txt -o results -t PU1_IRF8_jaccard -organism mm9
```

This command will generate a directory “<em>results/PU1_IRF8_jaccard</em>” with figures and html pages.

<p align="center">
<img src="../_static/rgt-viz/jaccard_test.png" width=500 align="center">
</p>

We can also look at the statistic numbers and p-values as shown below:
<p style="margin-left: 50">
<table border="1" id="hor-zebra">
	<thead>
		<tr>
    		<th scope="col" width="10" align="center">Reference<br>name</th>
    		<th scope="col" width="10" align="center">Query<br>name</th>
    		<th scope="col" width="10" align="center">Reference<br>number</th>
    		<th scope="col" width="10" align="center">Query<br>number</th>
    		<th scope="col" width="10" align="center">True<br>Jaccard<br>index</th>
    		<th scope="col" width="10" align="center">Average<br>random<br>Jaccard</th>
    		<th scope="col" width="10" align="center">Positive<br>Association<br>p-value</th>
    		<th scope="col" width="10" align="center">Negative<br>Association<br>p-value</th>
		</tr>
	</thead>
	<tbody>
		<tr class="odd">
			<td align="center" >MPP_PU1_peaks</td>
			<td align="center" >cDC_IRF8_peaks</td>
			<td align="center" >6212</td>
			<td align="center" >34003</td>
			<td align="center" >0.1101</td>
			<td align="center" >0.0007</td>
			<td align="center" ><font color="red">0</font></td>
			<td align="center" >1.00</td>
		</tr>
		<tr>
			<td align="center" >MPP_PU1_peaks</td>
			<td align="center" >pDC_IRF8_peaks</td>
			<td align="center" >6212</td>
			<td align="center" >6467</td>
			<td align="center" >0.1387</td>
			<td align="center" >0.0004</td>
			<td align="center" ><font color="red">0</font></td>
			<td align="center" >1.00</td>
		</tr>
		<tr class="odd">
			<td align="center" >CDP_PU1_peaks</td>
			<td align="center" >cDC_IRF8_peaks</td>
			<td align="center" >20237</td>
			<td align="center" >34003</td>
			<td align="center" >0.3125</td>
			<td align="center" >0.0019</td>
			<td align="center" ><font color="red">0</font></td>
			<td align="center" >1.00</td>
		</tr>
		<tr>
			<td align="center" >CDP_PU1_peaks</td>
			<td align="center" >pDC_IRF8_peaks</td>
			<td align="center" >20237</td>
			<td align="center" >6467</td>
			<td align="center" >0.1430</td>
			<td align="center" >0.0007</td>
			<td align="center" ><font color="red">0</font></td>
			<td align="center" >1.00</td>
		</tr>
		<tr class="odd">
			<td align="center" >cDC_PU1_peaks</td>
			<td align="center" >cDC_IRF8_peaks</td>
			<td align="center" >20054</td>
			<td align="center" >34003</td>
			<td align="center" >0.3140</td>
			<td align="center" >0.0019</td>
			<td align="center" ><font color="red">0</font></td>
			<td align="center" >1.00</td>
		</tr>
		<tr>
			<td align="center" >cDC_PU1_peaks</td>
			<td align="center" >pDC_IRF8_peaks</td>
			<td align="center" >20054</td>
			<td align="center" >6467</td>
			<td align="center" >0.1437</td>
			<td align="center" >0.0007</td>
			<td align="center" ><font color="red">0</font></td>
			<td align="center" >1.00</td>
		</tr>
		<tr class="odd">
			<td align="center" >pDC_PU1_peaks</td>
			<td align="center" >cDC_IRF8_peaks</td>
			<td align="center" >21050</td>
			<td align="center" >34003</td>
			<td align="center" >0.3147</td>
			<td align="center" >0.0020</td>
			<td align="center" ><font color="red">0</font></td>
			<td align="center" >1.00</td>
		</tr>
		<tr>
			<td align="center" >pDC_PU1_peaks</td>
			<td align="center" >pDC_IRF8_peaks</td>
			<td align="center" >21050</td>
			<td align="center" >6467</td>
			<td align="center" >0.1402</td>
			<td align="center" >0.0007</td>
			<td align="center" ><font color="red">0</font></td>
			<td align="center" >1.00</td>
		</tr>
</tbody></table></p>

## Projection test
We next evaluate the association between IRF8 and PU.1 binding sites and histone modification markers. For this, we can use [projection test](https://reg-gen.readthedocs.io/en/latest/rgt-viz/method.html#projection-test). It evaluates the association between a set of region sets (peaks of Irf8, PU1 and Irf8/PU1) vs. a background regions (H3K4me1 peaks in cDC cells) by evaluating intersection counts with a random binomial model.

```shell
rgt-viz projection -r Matrix_H3K4me1.txt -q Matrix_cDC_pDC.txt -o results -t projection -c factor -organism mm9 -g cell
```

- -r is reference region set as the base for statistics;
- -q is query region set for testing its association with the reference regions;
- -o indicates the output directory;
- -t defines the title of this experiment;
- -c defines the color tag for cloring the test;
- -organism defines the genome assembly used here;
- -g defines the group tag for grouping the test.

This command will generate a directory “<em>results/projection</em>” with figures and html pages.

<p align="center">
<img src="../_static/rgt-viz/projection_test.png" height=500 align="center">
</p>

These results indicates the majority of peaks associated with H3K4me3 in cDC are of PU.1 and Irf8 co-binding, while H34me3 pekas are associated with Irf8 peaks.

## Combinatorial test
We next ask if co-binding of PU.1 and IRF8 relates to different histone modifications. For this, we use [combinatorial test](https://reg-gen.readthedocs.io/en/latest/rgt-viz/method.html#combinatorial-test). This is another variant of intersection test that checks all the combinations of the given query regions and calcuate their intersections to the reference. This test is useful in exploring the unknown association between region sets.


```shell
rgt-viz combinatorial -o results -q Matrix_H3K4me1_cDC_pDC.txt -r Matrix_PU1_IRF8_peaks.txt -t combinatorial -organism mm9 -g cell -c factor
```

<p align="center">
<img src="../_static/rgt-viz/intersection_stackedbar.png" width=500 align="center">
</p>