🌐 Project page  |  📝 Documentation  |  📚 Tutorials  |  🤗 Hugging Face  |  📦 Reproducibility

A Universal Framework for Chromatin Loop Annotation from Bulk and Single-cell Contact Maps

README (EN)                     README (CN)

   

🌟 Polaris is a versatile and efficient command line tool tailored for rapid and accurate chromatin loop detection from contact maps generated by various assays, including bulk Hi-C, scHi-C, Micro-C, and DNA SPRITE. Polaris is particularly well-suited for analyzing sparse scHi-C data and low-coverage datasets.

📚 Tutorials

Step-by-step walkthroughs with example data and expected outputs are provided in the example/ folder:

Tutorial	Content
Loop annotation	Annotate loops from a contact map: three equivalent workflows (loop pred; loop score + loop pool; loop scorelf for large maps), with example data and output format.
Aggregate peak analysis	Pile up the contact signal at annotated loops with polaris util pileup.
CLI walkthrough	Overview of all Polaris commands and options.

The scripts and data to reproduce the analyses in our paper are available at Polaris Reproducibility.

❗️NOTE❗️: We suggest users run Polaris on GPU. You can run Polaris on CPU for loop annotations, but it is much slower than on GPU. If you encounter a CUDA OUT OF MEMORY error, please:

• Check your GPU's status and available memory.
• Reduce the --batchsize parameter. (The default value of 128 requires approximately 36GB of CUDA memory. Setting it to 24 will reduce the requirement to less than 10GB.)

📝Documentation

Detailed documentation can be found at: Polaris Doc.

Installation

Polaris is developed and tested on Linux machines with python3.9 and relies on several libraries including pytorch, scipy, etc. We strongly recommend that you install Polaris in a virtual environment.

We suggest users using conda to create a virtual environment for it (It should also work without using conda, i.e. with pip). You can run the command snippets below to install Polaris:

git clone https://github.com/ai4nucleome/Polaris.git
cd Polaris
conda create -n polaris python=3.9
conda activate polaris

---

Package dependencies

Polaris relies on the following packages:

appdirs==1.4.4
click==8.0.1
cooler==0.8.11
matplotlib==3.8.0
numpy==1.22.4
pandas==1.3.0
scikit-learn==1.4.2
scipy==1.7.3
timm==0.6.12
tqdm==4.65.0

Please install PyTorch == 2.2.2 according to its official documentation. We recommend using PyTorch 2.2.2 for best compatibility.

Install Polaris:

./setup.sh

It will automatically download Polaris model's weights from Hugging Face and install Polaris.

You can also download model's weights file manually from there and put it in Polaris/polaris/model and change the file name to sft_loop.pt.

The installation requires network access to download libraries. Usually, the installation will finish within 3 minutes. The installation time is longer if network access is slow and/or unstable.

Quick Start for Loop Annotation

Detailed documentation can be found at 🛜 this link: Polaris Doc 🛜.

For detailed documentation or parameter setting, please run:

polaris --help

or check the instruction here.

---

To quick run Polaris at 5kb resolution with default parameters, you can use the command snippets below:

polaris loop pred -i [input contact map] -o [output path of annotated loops]

-i indicates the path of the input contact map (a multi-resolution cooler .mcool or band cooler .bcool file); -o indicates the path of the output file of detected loops in .bedpe format. With default parameters, Polaris detects loops from the input contact map at 5kb resolution for all autosomes.

Single-cell Hi-C

The command for scHi-C is identical to bulk: you only prepare the input differently. Aggregate contact maps from cells of the same type into a single pseudo-bulk .mcool (e.g. by summing per-cell .cool files with cooler merge, or from a .scool), then run the same command. Polaris annotates loops from as few as ~25 cells.

Subcommands

Command	Purpose
polaris loop pred	Annotate loops directly (scoring + clustering in one step).
polaris loop score	Output a per-pixel loop-score file.
polaris loop pool	Cluster a loop-score file into discrete loops.
polaris loop scorelf	Memory-efficient scoring for very large / high-coverage / high-resolution maps.
polaris util pileup	Aggregate peak analysis (APA) of a loop set.

The more detailed parameter instructions can be found at this link: 🛜 Polaris Doc at ReadTheBook 🛜

Clustering defaults by resolution

polaris loop pool measures --distance_cutoff and --mindelta in bins, so the stretch of genome they cover grows with the bin size. Their 5 kb values smooth the density field across loops that are genuinely separate once the bins get larger, so both fall as the resolution coarsens:

Resolution	--distance_cutoff	--mindelta	--radius
10 kb	3	3	2
25 kb	2	2	2
all others	5	5	2

On GM12878 Hi-C at 500M valid read pairs, comparing the same number of top-scoring calls, the lower values recovered 4 to 15 percent more loops supported by CTCF and RAD21 ChIA-PET and by SMC1, H3K27ac and RNAPII data. Pass the options explicitly to override the resolution-dependent choice.

---

output format

It contains tab separated fields as follows:

Chr1    Start1    End1    Chr2    Start2    End2    Score

Field	Detail
Chr1/Chr2	chromosome names
Start1/Start2	start genomic coordinates
End1/End2	end genomic coordinates (i.e. End1=Start1+resol)
Score	Polaris's loop score [0~1]

Citation:

Yusen Hou, Audrey Baguette, Mathieu Blanchette*, & Yanlin Zhang*. A versatile tool for chromatin loop annotation in bulk and single-cell Hi-C data. bioRxiv, 2024. Paper

@article {Hou2024Polaris,
	title = {A versatile tool for chromatin loop annotation in bulk and single-cell Hi-C data},
	author = {Yusen Hou, Audrey Baguette, Mathieu Blanchette, and Yanlin Zhang},
	journal = {bioRxiv}
	year = {2024},
}

📩 Contact

A GitHub issue is preferable for all problems related to using Polaris.

For other concerns, please email Yusen Hou or Yanlin Zhang (yhou925@connect.hkust-gz.edu.cn, yanlinzhang@hkust-gz.edu.cn).