HiCExplorer

https://hicexplorer.readthedocs.io/en/latest
Admin
HiCExplorer is a set of programs designed to process, normalize, analyze, and visualize Hi-C and...
Tokens:60,204
Snippets:485
Trust Score:8.3
Update:9 months ago
Show doc for...
Tokens:
Raw
### Install HiCExplorer from Source (Manual)

Source: https://hicexplorer.readthedocs.io/en/latest/content/installation

This method involves cloning the HiCExplorer repository and installing it manually using `setup.py`. It allows for custom installation prefixes and is an alternative if pip or conda are not suitable.

```bash
$ git clone https://github.com/deeptools/HiCExplorer.git
$ python setup.py install --prefix /User/Tools/hicexplorer

```

--------------------------------

### Install HiCExplorer from Source using Pip

Source: https://hicexplorer.readthedocs.io/en/latest/content/installation

This command installs HiCExplorer from its GitHub repository using pip, allowing for specific installation paths. This method is also primarily for older versions and requires a GitHub repository URL.

```bash
$ pip install --install-option="--prefix=/MyPath/Tools/hicexplorer" git+https://github.com/deeptools/HiCExplorer.git

```

--------------------------------

### hicFindTADs Basic Usage Example

Source: https://hicexplorer.readthedocs.io/en/latest/content/tools/hicFindTADs

A practical example demonstrating how to run hicFindTADs with essential arguments. This example shows how to specify the input Hi-C matrix, an output prefix for the results, and the method for multiple testing correction.

```bash
$ hicFindTads -m hic_matrix.h5 –outPrefix TADs –correctForMultipleTesting fdr

```

--------------------------------

### Example: Running hicMergeMatrixBins for Different Resolutions

Source: https://hicexplorer.readthedocs.io/en/latest/content/tools/hicMergeMatrixBins

These examples demonstrate how to use hicMergeMatrixBins to create matrices with different bin resolutions from an initial matrix. The first command merges bins by 3, and the second merges by 50. This allows for plotting and analysis at various scales, from specific regions to whole chromosomes.

```bash
$ hicMergeMatrixBins -m myMatrix.h5 -o myMatrix_merged_nb3.h5 -nb 3

$ hicMergeMatrixBins -m myMatrix.h5 -o myMatrix_merged_nb50.h5 -nb 50
```

--------------------------------

### Install HiCExplorer Docker Image

Source: https://hicexplorer.readthedocs.io/en/latest/content/installation

This command pulls the HiCExplorer Docker image, which provides a pre-configured environment for using HiCExplorer within the Galaxy framework. This is useful for users who prefer a virtualized solution.

```bash
$ sudo docker pull quay.io/bgruening/galaxy-hicexplorer

```

--------------------------------

### HicTransform Example Usage

Source: https://hicexplorer.readthedocs.io/en/latest/content/tools/hicTransform

An example demonstrating how to use the hicTransform tool to convert a .cool matrix into an observed/expected matrix. This specific example uses the 'obs_exp' method and specifies input and output file names.

```bash
$ hicTransform -m matrix.cool --method obs_exp -o obs_exp.cool

```

--------------------------------

### Install HiCExplorer using Conda

Source: https://hicexplorer.readthedocs.io/en/latest/content/installation

This command installs HiCExplorer and its dependencies using the conda package manager. It is the recommended method for installation. Ensure you have Anaconda or Miniconda installed.

```bash
$ conda install hicexplorer -c bioconda -c conda-forge

```

--------------------------------

### hicCompartmentalization Example

Source: https://hicexplorer.readthedocs.io/en/latest/content/tools/hicCompartmentalization

An example of how to run the hicCompartmentalization tool, specifying the observed/expected matrices, the PC1 bedgraph file, and the output file name for the global signal plot. This demonstrates a typical use case for analyzing Hi-C data compartmentalization.

```bash
$ _hicCompartmentalization --obsexp_matrices obsExpMatrix.h5 --pca pc1.bedgraph \
  -o global_signal.png
```

--------------------------------

### hicPlotDistVsCounts Usage Example

Source: https://hicexplorer.readthedocs.io/en/latest/content/tools/hicPlotDistVsCounts

Example usage of the hicPlotDistVsCounts command-line tool. It demonstrates how to provide multiple Hi-C matrices, specify output file, labels, maximum plotting depth, and plot dimensions. This tool is best used with corrected matrices and large bins (>= 50kb).

```bash
hicPlotDistVsCounts -m \
condition1_sample1_50_bins_merged.h5 \
condition1_sampel2_50_bins_merged.h5 \
condition2_sample1_50_bins_merged.h5 \
condition2_sample2_50_bins_merged.h5 \
-o counts_vs_dist_50_bins_merged.png \
--labels 'Cond 1 Sample 1' 'Cond 1 Sample 2' 'Cond 2 Sample 1' 'Cond 2 Sample 2' \
--maxdepth 20000000 \
--plotsize 5 4.2
```

--------------------------------

### HicCorrectMatrix: Usage Example

Source: https://hicexplorer.readthedocs.io/en/latest/content/tools/hicCorrectMatrix

Provides a general usage example for the hicCorrectMatrix command-line tool. This demonstrates the basic structure for invoking the tool, including subcommands and common arguments.

```bash
usage: hicCorrectMatrix [-h] [--version]  ...
```

--------------------------------

### hicQuickQC Usage Example

Source: https://hicexplorer.readthedocs.io/en/latest/content/tools/hicQuickQC

This snippet shows the command-line usage for the hicQuickQC tool. It outlines the required arguments such as input SAM files, output folder, restriction cut file, and restriction/dangling sequences, as well as optional arguments like the number of lines to process.

```bash
usage: hicQuickQC --samFiles two sam files two sam files --QCfolder FOLDER
                  --restrictionCutFile BED file [BED file ...]
                  --restrictionSequence RESTRICTIONSEQUENCE
                  [RESTRICTIONSEQUENCE ...] --danglingSequence
                  DANGLINGSEQUENCE [DANGLINGSEQUENCE ...] [--lines LINES]
                  [--help] [--version]

```

--------------------------------

### Hi-C Matrix Creation with hicBuildMatrix

Source: https://hicexplorer.readthedocs.io/en/latest/content/example_usage

Builds a Hi-C contact matrix from independently mapped read pairs using hicBuildMatrix. This command requires aligned BAM files, a specified bin size, restriction enzyme information, and optionally outputs a QC folder with analysis plots.

```bash
# build matrix from independently mated read pairs
# the restriction sequence GATC is recognized by the DpnII restriction enzyme

$ hicBuildMatrix --samFiles mate_R1.bam mate_R2.bam \
                 --binSize 10000 \
                 --restrictionSequence GATC \
                 --danglingSequence GATC \
                 --restrictionCutFile cut_sites.bed \
                 --threads 4 \
                 --inputBufferSize 100000 \
                 --outBam hic.bam \
                 -o hic_matrix.h5 \
                 --QCfolder ./hicQC

```

--------------------------------

### Get help for HiCExplorer tools

Source: https://hicexplorer.readthedocs.io/en/latest/content/list-of-tools

This command displays all available command-line options for a specific HiCExplorer tool, such as hicPlotMatrix. This is crucial for understanding the full range of parameters and customizing analysis.

```bash
$ hicPlotMatrix --help

```

--------------------------------

### Run HiCExplorer analysis

Source: https://hicexplorer.readthedocs.io/en/latest/content/list-of-tools

This example demonstrates a typical HiCExplorer command to plot a Hi-C matrix. It specifies the input matrix, output file, masking behavior, a specific genomic region, and value limits for visualization. The output format is determined by the file extension.

```bash
$ hicPlotMatrix -m myHiCmatrix.h5 \
-o myHiCmatrix.pdf \
--clearMaskedBins \
--region chrX:10,000,000-15,000,000 \
--vMin -4 --vMax 4 \

```

--------------------------------

### Run hicFindTADs with specified parameters

Source: https://hicexplorer.readthedocs.io/en/latest/content/tools/hicFindTADs

This command-line example demonstrates how to use `hicFindTADs` to call TADs. It specifies the input Hi-C matrix, output prefix, and various parameters for depth, threshold, delta, and multiple testing correction. The output includes BED and GFF files for TAD boundaries and domains, as well as score files.

```bash
$ hicFindTADs -m myHiCmatrix.h5 \
--outPrefix myHiCmatrix_min3000_max31500_step1500_thres0.05_delta0.01_fdr \
--minDepth 3000 \
--maxDepth 31500 \
--step 1500 \
--thresholdComparisons 0.05 \
--delta 0.01 \
--correctForMultipleTesting fdr \
-p 64

```

--------------------------------

### Example: Compute TADs and then Average Regions - Shell

Source: https://hicexplorer.readthedocs.io/en/latest/content/tools/hicAverageRegions

This example demonstrates a two-step process using HiCExplorer tools. First, `hicFindTADs` is used to identify TADs within a specified chromosome of a Hi-C matrix. Subsequently, `hicAverageRegions` utilizes the TAD boundaries identified in the previous step as reference points to compute an averaged contact matrix, with a specified range of 100kb up and downstream of each boundary.

```shell
$ hicFindTADs -m GSE63525_GM12878_insitu_primary_10kb_KR.cool --outPrefix TADs
    --correctForMultipleTesting fdr --minDepth 30000 --maxDepth 100000
    --step 10000 -p 20 --chromosomes 1

$ hicAverageRegions -m GSE63525_GM12878_insitu_primary_10kb_KR.cool
    -r TADs_domains.bed --range 100000 100000 --outFileName primary_chr1
```

--------------------------------

### Example: Plotting Merged Matrices with hicPlotMatrix

Source: https://hicexplorer.readthedocs.io/en/latest/content/tools/hicMergeMatrixBins

This set of commands illustrates how to visualize the effect of bin merging on Hi-C interaction plots using hicPlotMatrix. It shows plotting corrected matrices at the scale of a whole chromosome, with different bin merging strategies applied previously. This helps in understanding how bin resolution impacts visualization.

```bash
$ hicPlotMatrix -m myMatrix_corrected.h5 \
-o myMatrix_corrected_Xchr.png \
--chromosomeOrder X \
-t Restriction_sites_resolution --log1p \
--clearMaskedBins

$ hicPlotMatrix -m myMatrix_merged_nb3_corrected.h5 \
-o myMatrix_merged_nb3_corrected_Xchr.png \
--chromosomeOrder X \
-t Bins_merged_by_3 --log1p \
--clearMaskedBins

 $ hicPlotMatrix -m myMatrix_merged_nb50_corrected.h5 \
-o myMatrix_merged_nb50_corrected_Xchr.png \
--chromosomeOrder X \
-t Bins_merged_by_50 --log1p \
--clearMaskedBins
```

--------------------------------

### Mapping Reads with Bowtie2 and Samtools

Source: https://hicexplorer.readthedocs.io/en/latest/content/capture-Hi-C

This snippet demonstrates how to map FASTQ files against a reference genome (mm9) using bowtie2 and then convert the output to BAM format using samtools. It is crucial for preparing sequencing data for downstream analysis. Ensure bowtie2 and samtools are installed and the mm9 index is available.

```shell
bowtie2 -x mm9_index --threads 8 -U SRR3950565_1.fastq.gz --reorder | samtools view -Shb - > SRR3950565_1.bam
bowtie2 -x mm9_index --threads 8 -U SRR3950565_2.fastq.gz --reorder | samtools view -Shb - > SRR3950565_2.bam
bowtie2 -x mm9_index --threads 8 -U SRR3950566_1.fastq.gz --reorder | samtools view -Shb - > SRR3950566_1.bam
bowtie2 -x mm9_index --threads 8 -U SRR3950566_2.fastq.gz --reorder | samtools view -Shb - > SRR3950566_2.bam
bowtie2 -x mm9_index --threads 8 -U SRR3950559_1.fastq.gz --reorder | samtools view -Shb - > SRR3950559_1.bam
bowtie2 -x mm9_index --threads 8 -U SRR3950559_2.fastq.gz --reorder | samtools view -Shb - > SRR3950559_2.bam
bowtie2 -x mm9_index --threads 8 -U SRR3950560_1.fastq.gz --reorder | samtools view -Shb - > SRR3950560_1.bam
bowtie2 -x mm9_index --threads 8 -U SRR3950560_2.fastq.gz --reorder | samtools view -Shb - > SRR3950560_2.bam
```

--------------------------------

### Install HiCExplorer using Pip (Older Versions)

Source: https://hicexplorer.readthedocs.io/en/latest/content/installation

This command installs HiCExplorer using pip. Note that pip installation is discontinued from version 3.0 onwards due to dependency on non-Python packages. This method is suitable for older versions.

```bash
$ pip install hicexplorer

```

--------------------------------

### chicQualityControl Command Line Usage

Source: https://hicexplorer.readthedocs.io/en/latest/content/tools/chicQualityControl

Demonstrates the command-line interface for the chicQualityControl tool, including required and optional arguments for matrix input, reference points, sparsity threshold, and output file naming.

```bash
chicQualityControl -m matrix1.cool matrix2.cool -rp referencePointsFile.bed --range 20000 40000 --sparsity 0.01 -o referencePointFile_QC_passed.bed
usage: chicQualityControl --matrices MATRICES [MATRICES ...] --referencePoints REFERENCEPOINTS --sparsity SPARSITY [--outFileName OUTFILENAME] [--outFileNameHistogram OUTFILENAMEHISTOGRAM] [--outFileNameSparsity OUTFILENAMESPARSITY] [--threads THREADS] [--fixateRange FIXATERANGE] [--dpi DPI] [--help] [--version]
```

--------------------------------

### Run hicFindTADs using a pre-computed z-score matrix

Source: https://hicexplorer.readthedocs.io/en/latest/content/tools/hicFindTADs

This example shows how to speed up `hicFindTADs` by providing a pre-computed z-score matrix using the `--TAD_sep_score_prefix` option. This bypasses the computationally intensive z-score matrix calculation, allowing for faster testing of parameters like `--thresholdComparisons`. Parameters like `--minDepth`, `--maxDepth`, and `--step` are ignored when using this option.

```bash
$ hicFindTADs -m myHiCmatrix.h5 \
--outPrefix myHiCmatrix_min10000_max40000_step1500_thres0.01_delta0.01_fdr \
--TAD_sep_score_prefix myHiCmatrix_min10000_max40000_step1500_thres0.05_delta0.01_fdr \
--thresholdComparisons 0.01 \
--delta 0.01 \
--correctForMultipleTesting fdr \
-p 64

```

--------------------------------

### HicAggregateContacts Command-Line Usage Example

Source: https://hicexplorer.readthedocs.io/en/latest/content/tools/hicAggregateContacts

Example of using the `hicAggregateContacts` command to generate an aggregate Hi-C matrix. This command processes Hi-C data from a specified matrix file and BED file, applies transformations (e.g., observed/expected), and plots the results with customizable parameters for minimum/maximum values, range, number of bins, chromosomes, operation type, and mode.

```bash
$ hicAggregateContacts --matrix Dmel.h5 --BED ChIP-seq-peaks.bed \
--outFileName Dmel_aggregate_Contacts --vMin 0.8 --vMax 2.2 \
--range 300000:1000000 --numberOfBins 30 --chromosomes X \
--operationType mean --transform obs/exp --mode intra-chr

```

--------------------------------

### hicMergeTADbins Command Line Usage

Source: https://hicexplorer.readthedocs.io/en/latest/content/tools/hicMergeTADbins

This snippet shows the basic command-line usage for the hicMergeTADbins tool. It requires the input Hi-C matrix, a BED file of domains, and an output file name. Optional arguments include a version flag.

```bash
usage: hicMergeTADbins [-h] --matrix MATRIX --domains DOMAINS --outFile OUTFILE [--version]
```

--------------------------------

### Run hicDetectLoops with example parameters

Source: https://hicexplorer.readthedocs.io/en/latest/content/tools/hicDetectLoops

This snippet demonstrates the basic usage of hicDetectLoops, specifying the input matrix, output file, and several key parameters controlling loop detection sensitivity and range. It highlights the `--maxLoopDistance` parameter for defining the maximum genomic distance for interactions and parameters like `--pValuePreselection`, `--windowSize`, and `--peakWidth` for refining the peak detection process.

```bash
$ hicDetectLoops -m matrix.cool -o loops.bedgraph --maxLoopDistance 2000000 --windowSize 10 --peakWidth 6 --pValuePreselection 0.05 --pValue 0.05

```

--------------------------------

### hicNormalize: Normalize to 0-1 Range

Source: https://hicexplorer.readthedocs.io/en/latest/content/tools/hicNormalize

This example demonstrates how to use the hicNormalize tool to normalize a Hi-C matrix to a 0-1 range. This means the maximum interaction value in the matrix will be scaled to 1, and the minimum to 0.

```bash
$ hicNormalize -m matrix.cool --normalize norm_range -o matrix_0_1_range.cool

```

--------------------------------

### Hi-C Matrix Correction using KR Algorithm

Source: https://hicexplorer.readthedocs.io/en/latest/content/tools/hicCorrectMatrix

Example of correcting a Hi-C matrix using the Knight-Ruiz (KR) algorithm. This command takes a matrix file and specifies chromosomes to include, outputting the corrected matrix.

```bash
$ hicCorrectMatrix correct --matrix matrix.cool --correctionMethod KR --chromosomes chrUextra chr3LHet --outFileName corrected_KR.cool
```

--------------------------------

### HicCorrectMatrix: Diagnostic Plot Command

Source: https://hicexplorer.readthedocs.io/en/latest/content/tools/hicCorrectMatrix

A specific command-line example for generating a diagnostic plot using the `diagnostic_plot` subcommand of `hicCorrectMatrix`. It specifies the input Hi-C matrix file and the output file name for the generated plot.

```bash
hicCorrectMatrix diagnostic_plot --matrix hic_matrix.h5 -o file.png
```

--------------------------------

### Build Multicooler Matrix with hicBuildMatrix

Source: https://hicexplorer.readthedocs.io/en/latest/content/tools/hicBuildMatrix

This command demonstrates how to build a multicooler matrix using hicBuildMatrix. It specifies input BAM files, an output file name, multiple bin sizes for different resolutions, and a folder for QC reports. This is useful for creating matrices required for visualization tools like HiGlass.

```bash
$ hicBuildMatrix -s forward.bam reverse.bam -o multi_resolution.cool
  --binSize 10000 20000 50000 100000 --QCfolder QC

```

--------------------------------

### hicNormalize: Normalize to Smallest Read Count

Source: https://hicexplorer.readthedocs.io/en/latest/content/tools/hicNormalize

This example shows how to normalize multiple Hi-C matrices so that they all have the same total read count, equivalent to the matrix with the smallest read count among the inputs. This is useful for comparing matrices with different sequencing depths.

```bash
$ hicNormalize -m matrix.cool matrix2.cool matrix3.cool --normalize smallest
  -o matrix_normalized.cool matrix2_normalized.cool matrix3_normalized.cool

```

--------------------------------

### Hi-C Matrix Correction using ICE Algorithm

Source: https://hicexplorer.readthedocs.io/en/latest/content/tools/hicCorrectMatrix

Example of correcting a Hi-C matrix using the Iterative Correction (ICE) algorithm. This command includes parameters for the number of iterations and a filter threshold, in addition to the matrix file and output file name.

```bash
$ hicCorrectMatrix correct --matrix matrix.cool --correctionMethod ICE --chromosomes chrUextra chr3LHet --iterNum 500  --outFileName corrected_ICE.cool --filterThreshold -1.5 5.0
```

--------------------------------

### Download Raw FASTQ Files for Hi-C Analysis

Source: https://hicexplorer.readthedocs.io/en/latest/content/mES-HiC_analysis

This snippet downloads paired-end FASTQ files from the EBI archive and stores them in the 'original_data' directory. These files are essential for subsequent alignment and analysis steps in Hi-C experiments.

```bash
mkdir original_data

wget ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR195/007/SRR1956527/SRR1956527_1.fastq.gz -O original_data/SRR1956527_1.fastq.gz
wget ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR195/007/SRR1956527/SRR1956527_2.fastq.gz -O original_data/SRR1956527_2.fastq.gz

wget ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR195/008/SRR1956528/SRR1956528_1.fastq.gz -O original_data/SRR1956528_1.fastq.gz
wget ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR195/008/SRR1956528/SRR1956528_2.fastq.gz -O original_data/SRR1956528_2.fastq.gz

wget ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR195/009/SRR1956529/SRR1956529_1.fastq.gz -O original_data/SRR1956529_1.fastq.gz
wget ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR195/009/SRR1956529/SRR1956529_2.fastq.gz -O original_data/SRR1956529_2.fastq.gz
```

--------------------------------

### hicAverageRegions Tool

Source: https://hicexplorer.readthedocs.io/en/latest/content/tools/hicAverageRegions

Sums Hi-C contacts around given reference points and computes their average. This tool is useful to detect differences at certain reference points as for example TAD boundaries between samples. It requires a fixed bin size Hi-C matrix.

```APIDOC
## hicAverageRegions

### Description
Sums Hi-C contacts around given reference points and computes their average. This tool is useful to detect differences at certain reference points as for example TAD boundaries between samples. This tool can only be used with fixed bin size Hi-C matrices.

### Method
Not applicable (Command-line tool)

### Endpoint
Not applicable (Command-line tool)

### Parameters
#### Required arguments
- **--matrix** or **-m** (file) - The matrix to use for the average of TAD regions.
- **--regions** or **-r** (file) - BED file which stores a list of regions that are summed and averaged.
- **--outFileName** or **-o** (file) - File name to save the average regions TADs matrix.

#### Optional arguments
- **--range** or **-ra** (integer, integer) - Range of region up- and downstream of each region to include in genomic units.
- **--rangeInBins** or **-rib** (integer, integer) - Range of region up- and downstream of each region to include in bin units.
- **--coordinatesToBinMapping** or **-cb** (string) - Possible choices: start, center, end. If the region contains start and end coordinates, define if the start, center (start + (end-start) / 2) or end bin should be used as start for range. This parameter is only important to set if the given start and end coordinates are not in the same bin (Default: "start").
- **--considerStrandDirection** (boolean) - This parameter specifies if the strand information is taken into account for the aggregation. It has the effect that the contacts of a reverse strand region are inverted e.g. [1,2,3] becomes [3,2,1]. (Default: False)
- **--help** - Show program's help message and exit.
- **--version** - Show program's version number and exit.

### Usage Example
```bash
hicAverageRegions -m input_matrix.cool -r regions.bed --range 100000 100000 --outFileName average_regions_output
```

### Response
#### Success Response (Output File)
The tool generates an output file (specified by `--outFileName`) containing the averaged Hi-C contacts.

#### Response Example
(Output is a file, not a direct response)

```
Tokens:
Raw