{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# hicstuff command line interface demo\n", "\n", "## Preparing the data\n", "\n", "If using bowtie, genome must first be indexed using bowtie2-build\n", "\n", "```bash\n", "bowtie2-build genome.fa genome\n", "```\n", "The input reads can be in fastq format, or in name-sorted BAM format if already aligned to the genome.\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Generating matrices\n", "\n", "The pipeline command can be used to generate the Hi-C contact map from the input reads.\n", "\n", "```bash\n", "hicstuff pipeline --no-cleanup \\\n", " --enzyme DpnII \\\n", " --distance-law \\\n", " --filter \\\n", " --threads 12 \\\n", " --plot \\\n", " --iterative \\\n", " --genome genome \\\n", " --output output/ \\\n", " --prefix demo \\\n", " forward.fq \\\n", " reverse.fq\n", "```\n", "For instance, this will create a directory named \"output\", containing the output files with the prefix \"demo\". The ouput directory will contain two subdirectories; \"tmp\", containing all temporary files and \"plots\", containing figures generated at different stages of the pipeline. Reads will be truncated to 20bp and aligned to the genome by iterative extension. The process is parallelized on 12 threadsd. Hi-C pairs will also be filtered to exclude uninformative religation events." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Output files\n", "The output files should look like this:\n", "```\n", "output\n", "├── demo.chr.tsv\n", "├── demo.frags.tsv\n", "├── demo.hicstuff_20190423185220.log\n", "├── demo.mat.tsv\n", "├── demo.distance_law.txt\n", "├── plots\n", "│   ├── event_distance.pdf\n", "│   ├── event_distribution.pdf\n", "│   └── frags_hist.pdf\n", "└── tmp\n", " ├── demo.for.bam\n", " ├── demo.genome.fasta\n", " ├── demo.rev.bam\n", " ├── demo.valid_idx_filtered.pairs\n", " ├── demo.valid_idx.pairs\n", " └── demo.valid.pairs\n", "```\n", "\n", "There are 3 output files in the base `output` directory: the contact matrix (demo.mat.tsv), the info_contigs file (demo.chr.tsv) and the fragments_list (demo.frags.tsv), there is another file if the arguments `--distance-law` is enabled: the raw distance law table. The `tmp` directory contains the fasta genome extracted from the bowtie2 index, the alignments in SAM format and all temporary files in .pairs fomat.\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Generating the distance law\n", "\n", "The distance law is the probability of contact of two fragments in function of the distance between these fragments. There are two ways to compute it with hicstuff. The first one using the full pipeline with the option `--distance-law`, as done above. It's possible to add an option `--centromeres` if you want to compute the distance law on separate arms. The output of this command will be a raw table of the distance without any treatment of the data. It will be then possible with the command distancelaw to process this table.\n", "\n", "The second way is to use the command distancelaw with the pairs file as input:\n", "\n", "```bash\n", "hicstuff distancelaw --average \\\n", " --big-arm-only \\\n", " --centromeres centromeres.txt \\\n", " --frags output/demo.frags.tsv \\\n", " --inf 3000 \\ \n", " --outputfile-img output/demo_distance_law.svg \\ \n", " --labels labels.txt \\\n", " --sup 500000 \\\n", " --pairs output/tmp/demo.valid_idx_filtered.pairs\n", "```\n", "\n", "For instance, this will create an image with the distance law generated from the pairs file given in input. The distance law will be the average between all the distance laws of the arms bigger than 500kb. The logspace used to plot it will have a base 1.1 by default. The limits of the x axis will be 3kb and 500kb." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Visualizing the matrix\n", "\n", "The view command can be used to visualise the output Hi-C matrix.\n", "\n", "```bash\n", "hicstuff view --binning 5kb --normalize --frags output/demo.frags.tsv output/demo.mat.tsv\n", "```\n", "\n", "This will show an interactive heatmap using matplotlib. In order to save the matrix to a file instead, one could add `--output output/demo.png`\n", "\n", "Note there are many options allowing to process the matrix to improve the signal." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Converting output\n", "\n", "The default output files of hicstuff pipeline can be converted into a cool file or a bedgraph2d file using the command `hicstuff convert`. For example to generate the file `cool_output/demo.cool`:\n", "\n", "```bash\n", "hicstuff convert --frags output/demo.frags.tsv \\\n", " --chroms output/demo.chr.tsv \\\n", " --out cool_output \\\n", " --prefix demo \\\n", " --from GRAAL \\\n", " --to cool output/demo.mat.tsv\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Rebining existing files\n", "Files previously produced by hicstuff pipeline can be rebinned at a lower resolution using the `hicstuff rebin` command.\n", "This will generate a new matrix, a new fragments_list.txt and a new info_contigs.txt, all with updated number of bins:\n", "\n", "```bash\n", "hicstuff rebin -f output/demo.frags.tsv \\\n", " -c output/demo.chr.tsv \\\n", " --out rebin_1kb \\\n", " --binning 1kb output/demo.mat.tsv\n", "```" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.7.3" } }, "nbformat": 4, "nbformat_minor": 2 }