hicstuff 3.2.5__tar.gz → 3.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {hicstuff-3.2.5/src/hicstuff.egg-info → hicstuff-3.3.0}/PKG-INFO +79 -64
- {hicstuff-3.2.5 → hicstuff-3.3.0}/README.md +76 -60
- {hicstuff-3.2.5 → hicstuff-3.3.0}/pyproject.toml +39 -5
- {hicstuff-3.2.5 → hicstuff-3.3.0}/src/hicstuff/_misc.py +0 -2
- {hicstuff-3.2.5 → hicstuff-3.3.0}/src/hicstuff/cli.py +72 -34
- {hicstuff-3.2.5 → hicstuff-3.3.0}/src/hicstuff/digest.py +61 -35
- {hicstuff-3.2.5 → hicstuff-3.3.0}/src/hicstuff/distance_law.py +20 -19
- {hicstuff-3.2.5 → hicstuff-3.3.0}/src/hicstuff/filter.py +60 -22
- {hicstuff-3.2.5 → hicstuff-3.3.0}/src/hicstuff/io.py +240 -104
- {hicstuff-3.2.5 → hicstuff-3.3.0}/src/hicstuff/iteralign.py +18 -2
- hicstuff-3.3.0/src/hicstuff/log.py +62 -0
- {hicstuff-3.2.5 → hicstuff-3.3.0}/src/hicstuff/pipeline.py +394 -128
- {hicstuff-3.2.5 → hicstuff-3.3.0}/src/hicstuff/stats.py +55 -19
- {hicstuff-3.2.5 → hicstuff-3.3.0/src/hicstuff.egg-info}/PKG-INFO +79 -64
- {hicstuff-3.2.5 → hicstuff-3.3.0}/src/hicstuff.egg-info/SOURCES.txt +8 -1
- {hicstuff-3.2.5 → hicstuff-3.3.0}/src/hicstuff.egg-info/requires.txt +3 -3
- hicstuff-3.3.0/tests/test_digest.py +177 -0
- {hicstuff-3.2.5 → hicstuff-3.3.0}/tests/test_distance_law.py +91 -0
- hicstuff-3.3.0/tests/test_filter.py +194 -0
- hicstuff-3.3.0/tests/test_io.py +574 -0
- hicstuff-3.3.0/tests/test_iteralign.py +258 -0
- hicstuff-3.3.0/tests/test_pipeline.py +763 -0
- hicstuff-3.3.0/tests/test_synthetic_cli.py +683 -0
- hicstuff-3.3.0/tests/test_synthetic_generator.py +158 -0
- hicstuff-3.3.0/tests/test_synthetic_io.py +430 -0
- hicstuff-3.3.0/tests/test_synthetic_matrices.py +180 -0
- hicstuff-3.3.0/tests/test_synthetic_pipeline.py +951 -0
- hicstuff-3.3.0/tests/test_synthetic_stats.py +174 -0
- hicstuff-3.2.5/src/hicstuff/log.py +0 -91
- hicstuff-3.2.5/tests/test_digest.py +0 -50
- hicstuff-3.2.5/tests/test_filter.py +0 -65
- hicstuff-3.2.5/tests/test_io.py +0 -167
- hicstuff-3.2.5/tests/test_pipeline.py +0 -264
- {hicstuff-3.2.5 → hicstuff-3.3.0}/LICENSE +0 -0
- {hicstuff-3.2.5 → hicstuff-3.3.0}/setup.cfg +0 -0
- {hicstuff-3.2.5 → hicstuff-3.3.0}/src/hicstuff/__init__.py +0 -0
- {hicstuff-3.2.5 → hicstuff-3.3.0}/src/hicstuff/cutsite.py +0 -0
- {hicstuff-3.2.5 → hicstuff-3.3.0}/src/hicstuff/hicstuff.py +0 -0
- {hicstuff-3.2.5 → hicstuff-3.3.0}/src/hicstuff/view.py +0 -0
- {hicstuff-3.2.5 → hicstuff-3.3.0}/src/hicstuff.egg-info/dependency_links.txt +0 -0
- {hicstuff-3.2.5 → hicstuff-3.3.0}/src/hicstuff.egg-info/entry_points.txt +0 -0
- {hicstuff-3.2.5 → hicstuff-3.3.0}/src/hicstuff.egg-info/top_level.txt +0 -0
- {hicstuff-3.2.5 → hicstuff-3.3.0}/tests/test_commands.py +0 -0
- {hicstuff-3.2.5 → hicstuff-3.3.0}/tests/test_doctests.py +0 -0
- {hicstuff-3.2.5 → hicstuff-3.3.0}/tests/test_hicstuff.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: hicstuff
|
|
3
|
-
Version: 3.
|
|
3
|
+
Version: 3.3.0
|
|
4
4
|
Summary: General purpose stuff to generate and handle Hi-C data in its simplest form.
|
|
5
5
|
Author-email: Jacques Serizay <jacques.serizay@pasteur.fr>, Cyril Matthey-Doret <cyril.matthey-doret@pasteur.fr>, Lyam Baudry <lyam.baudry@pasteur.fr>
|
|
6
6
|
License: BSD-3-Clause
|
|
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.10
|
|
|
19
19
|
Classifier: Programming Language :: Python :: 3.11
|
|
20
20
|
Classifier: Programming Language :: Python :: 3.12
|
|
21
21
|
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
22
23
|
Classifier: Topic :: Scientific/Engineering
|
|
23
24
|
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
24
25
|
Classifier: Topic :: Scientific/Engineering :: Visualization
|
|
@@ -34,12 +35,9 @@ Requires-Dist: pandas>=1.5.0
|
|
|
34
35
|
Requires-Dist: matplotlib>=3.4.0
|
|
35
36
|
Requires-Dist: rich-click>=1.7
|
|
36
37
|
Requires-Dist: biopython
|
|
37
|
-
Requires-Dist: requests
|
|
38
|
-
Requires-Dist: scikit-learn
|
|
39
38
|
Requires-Dist: pysam
|
|
40
39
|
Requires-Dist: pyfastx
|
|
41
40
|
Requires-Dist: cooler
|
|
42
|
-
Requires-Dist: pairtools
|
|
43
41
|
Provides-Extra: dev
|
|
44
42
|
Requires-Dist: pytest>=7.0; extra == "dev"
|
|
45
43
|
Requires-Dist: pytest-cov>=4.0; extra == "dev"
|
|
@@ -48,6 +46,7 @@ Requires-Dist: pre-commit>=3.0; extra == "dev"
|
|
|
48
46
|
Requires-Dist: sphinx; extra == "dev"
|
|
49
47
|
Requires-Dist: sphinx-rtd-theme; extra == "dev"
|
|
50
48
|
Requires-Dist: ipython>=8.12.3; extra == "dev"
|
|
49
|
+
Requires-Dist: bump-my-version>=1.2; python_version >= "3.10" and extra == "dev"
|
|
51
50
|
Dynamic: license-file
|
|
52
51
|
|
|
53
52
|
# hicstuff
|
|
@@ -82,7 +81,8 @@ The goal is to make generation and manipulation of Hi-C matrices as simple as po
|
|
|
82
81
|
5. [Viewing the contact map](#viewing-the-contact-map)
|
|
83
82
|
3. [File formats](#file-formats)
|
|
84
83
|
4. [Contributing](#contributing)
|
|
85
|
-
5. [
|
|
84
|
+
5. [Releasing](#releasing)
|
|
85
|
+
6. [Citation](#citation)
|
|
86
86
|
|
|
87
87
|
## Installation
|
|
88
88
|
|
|
@@ -101,8 +101,8 @@ cd hicstuff
|
|
|
101
101
|
uv sync --extra dev
|
|
102
102
|
```
|
|
103
103
|
|
|
104
|
-
If `hicstuff` is installed via pip, additional system dependencies such as
|
|
105
|
-
`bowtie2`, `bwa`, `minimap2` and `samtools` will be needed. You can install
|
|
104
|
+
If `hicstuff` is installed via pip, additional system dependencies such as
|
|
105
|
+
`bowtie2`, `bwa`, `minimap2` and `samtools` will be needed. You can install
|
|
106
106
|
them as follows on Debian/Ubuntu:
|
|
107
107
|
|
|
108
108
|
```bash
|
|
@@ -111,7 +111,7 @@ apt-get install bowtie2 bwa minimap2 samtools libbz2-dev liblzma-dev
|
|
|
111
111
|
|
|
112
112
|
### Conda
|
|
113
113
|
|
|
114
|
-
hicstuff is also available on bioconda, which will automatically handle all
|
|
114
|
+
hicstuff is also available on bioconda, which will automatically handle all
|
|
115
115
|
dependencies:
|
|
116
116
|
|
|
117
117
|
```bash
|
|
@@ -120,7 +120,7 @@ conda install bioconda::hicstuff
|
|
|
120
120
|
|
|
121
121
|
### Docker
|
|
122
122
|
|
|
123
|
-
Docker images are automatically built and published to GitHub Container
|
|
123
|
+
Docker images are automatically built and published to GitHub Container
|
|
124
124
|
Registry (GHCR) when releases are tagged:
|
|
125
125
|
|
|
126
126
|
```bash
|
|
@@ -130,16 +130,16 @@ docker pull ghcr.io/baudrly/hicstuff:<version>
|
|
|
130
130
|
|
|
131
131
|
## Usage
|
|
132
132
|
|
|
133
|
-
The hicstuff command line interface is composed of multiple subcommands.
|
|
133
|
+
The hicstuff command line interface is composed of multiple subcommands.
|
|
134
134
|
You can always get a summary of all available commands by running:
|
|
135
135
|
|
|
136
136
|
```txt
|
|
137
137
|
hicstuff --help
|
|
138
|
-
|
|
139
|
-
Usage: hicstuff [OPTIONS] COMMAND [ARGS]...
|
|
140
|
-
|
|
141
|
-
Simple Hi-C pipeline for generating and manipulating contact matrices.
|
|
142
|
-
|
|
138
|
+
|
|
139
|
+
Usage: hicstuff [OPTIONS] COMMAND [ARGS]...
|
|
140
|
+
|
|
141
|
+
Simple Hi-C pipeline for generating and manipulating contact matrices.
|
|
142
|
+
|
|
143
143
|
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
|
|
144
144
|
│ --version Show the version and exit. │
|
|
145
145
|
│ --help -h Show this message and exit. │
|
|
@@ -169,22 +169,22 @@ hicstuff --help
|
|
|
169
169
|
|
|
170
170
|
### Full pipeline
|
|
171
171
|
|
|
172
|
-
All components of the pipeline can be run at once using the `hicstuff pipeline` command.
|
|
173
|
-
This allows to generate a contact matrix from reads in a single command.
|
|
174
|
-
By default, the output is a `cool` file.
|
|
172
|
+
All components of the pipeline can be run at once using the `hicstuff pipeline` command.
|
|
173
|
+
This allows to generate a contact matrix from reads in a single command.
|
|
174
|
+
By default, the output is a `cool` file.
|
|
175
175
|
|
|
176
176
|
```txt
|
|
177
177
|
hicstuff pipeline --help
|
|
178
|
-
|
|
179
|
-
Usage: hicstuff pipeline [OPTIONS] INPUT1 [INPUT2]
|
|
180
|
-
|
|
181
|
-
Run the full Hi-C pipeline from FASTQ to contact matrix.
|
|
182
|
-
Example — generate a multi-resolution .mcool for Arima Hi-C:
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
hicstuff pipeline --enzyme "DpnII,HinfI" --binning 1000 --threads 8 \
|
|
186
|
-
--genome ref.fa R1.fq.gz R2.fq.gz
|
|
187
|
-
|
|
178
|
+
|
|
179
|
+
Usage: hicstuff pipeline [OPTIONS] INPUT1 [INPUT2]
|
|
180
|
+
|
|
181
|
+
Run the full Hi-C pipeline from FASTQ to contact matrix.
|
|
182
|
+
Example — generate a multi-resolution .mcool for Arima Hi-C:
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
hicstuff pipeline --enzyme "DpnII,HinfI" --binning 1000 --threads 8 \
|
|
186
|
+
--genome ref.fa R1.fq.gz R2.fq.gz
|
|
187
|
+
|
|
188
188
|
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮
|
|
189
189
|
│ * INPUT1 TEXT [required] │
|
|
190
190
|
│ INPUT2 TEXT │
|
|
@@ -214,7 +214,8 @@ hicstuff pipeline --help
|
|
|
214
214
|
│ --remove-centromeres -r INT kb to remove around centromere positions. [default: 0] │
|
|
215
215
|
│ --read-len -R INT Maximum read length (estimated from first read if │
|
|
216
216
|
│ omitted). │
|
|
217
|
-
│ --size -s INT Minimum contig size
|
|
217
|
+
│ --size -s INT Minimum contig size (bp): shorter contigs, and the pairs │
|
|
218
|
+
│ on them, are left out. [default: 0] │
|
|
218
219
|
│ --start-stage -S STR Pipeline start stage. [default: fastq] │
|
|
219
220
|
│ --threads -t INT Number of parallel threads. [default: 1] │
|
|
220
221
|
│ --tmpdir -T DIR Temporary directory. │
|
|
@@ -250,18 +251,18 @@ The general steps of the pipeline are as follows:
|
|
|
250
251
|
For more advanced usage, different scripts can be used independently on the command line to perform individual parts of the pipeline. This readme contains quick descriptions and example usages. To obtain detailed instructions on any subcommand, one can use `hicstuff <subcommand> --help`.
|
|
251
252
|
|
|
252
253
|
#### Digestion of fastq reads
|
|
253
|
-
|
|
254
|
+
|
|
254
255
|
Generates new gzipped fastq files from original fastq. The function will cut the reads at their religation sites and creates new pairs of reads with the different fragments obtained after cutting at the digestion sites.
|
|
255
256
|
|
|
256
257
|
```
|
|
257
258
|
hicstuff cutsite --help
|
|
258
|
-
|
|
259
|
-
Usage: hicstuff cutsite [OPTIONS]
|
|
260
|
-
|
|
261
|
-
Preprocess FASTQ files by cutting reads at religation sites.
|
|
262
|
-
Generates gzipped FASTQ files with reads cut at ligation junctions, creating new fragment pairs
|
|
263
|
-
for mapping.
|
|
264
|
-
|
|
259
|
+
|
|
260
|
+
Usage: hicstuff cutsite [OPTIONS]
|
|
261
|
+
|
|
262
|
+
Preprocess FASTQ files by cutting reads at religation sites.
|
|
263
|
+
Generates gzipped FASTQ files with reads cut at ligation junctions, creating new fragment pairs
|
|
264
|
+
for mapping.
|
|
265
|
+
|
|
265
266
|
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
|
|
266
267
|
│ * --forward -F FILE Forward reads FASTQ file. [required] │
|
|
267
268
|
│ * --reverse -R FILE Reverse reads FASTQ file. [required] │
|
|
@@ -280,13 +281,13 @@ Truncate reads from a fastq file to 20 basepairs and iteratively extend and re-a
|
|
|
280
281
|
|
|
281
282
|
```
|
|
282
283
|
hicstuff iteralign --help
|
|
283
|
-
|
|
284
|
-
Usage: hicstuff iteralign [OPTIONS] READS_FQ
|
|
285
|
-
|
|
286
|
-
Iteratively align reads to a reference genome.
|
|
287
|
-
Truncates reads to 20 bp then iteratively extends and re-aligns unmapped reads to maximise the
|
|
288
|
-
proportion of uniquely aligned reads in a 3C library.
|
|
289
|
-
|
|
284
|
+
|
|
285
|
+
Usage: hicstuff iteralign [OPTIONS] READS_FQ
|
|
286
|
+
|
|
287
|
+
Iteratively align reads to a reference genome.
|
|
288
|
+
Truncates reads to 20 bp then iteratively extends and re-aligns unmapped reads to maximise the
|
|
289
|
+
proportion of uniquely aligned reads in a 3C library.
|
|
290
|
+
|
|
290
291
|
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮
|
|
291
292
|
│ * READS_FQ TEXT [required] │
|
|
292
293
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
@@ -310,12 +311,12 @@ named "info_contigs.txt" and "fragments_list.txt"
|
|
|
310
311
|
|
|
311
312
|
```
|
|
312
313
|
hicstuff digest --help
|
|
313
|
-
|
|
314
|
-
Usage: hicstuff digest [OPTIONS] FASTA
|
|
315
|
-
|
|
316
|
-
Digest a genome FASTA into restriction fragments.
|
|
317
|
-
Writes ``fragments_list.txt`` and ``info_contigs.txt`` to the output directory.
|
|
318
|
-
|
|
314
|
+
|
|
315
|
+
Usage: hicstuff digest [OPTIONS] FASTA
|
|
316
|
+
|
|
317
|
+
Digest a genome FASTA into restriction fragments.
|
|
318
|
+
Writes ``fragments_list.txt`` and ``info_contigs.txt`` to the output directory.
|
|
319
|
+
|
|
319
320
|
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮
|
|
320
321
|
│ * FASTA TEXT [required] │
|
|
321
322
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
@@ -323,7 +324,8 @@ hicstuff digest --help
|
|
|
323
324
|
│ * --enzyme -e ENZ[,ENZ2,...] Restriction enzyme name(s) or fixed chunk size in bp. │
|
|
324
325
|
│ [required] │
|
|
325
326
|
│ --outdir -o DIR Output directory (default: current directory). │
|
|
326
|
-
│ --size -s INT Minimum
|
|
327
|
+
│ --size -s INT Minimum contig size (bp): shorter contigs are left out. │
|
|
328
|
+
│ [default: 0] │
|
|
327
329
|
│ --circular -c Genome is circular. │
|
|
328
330
|
│ --plot -p Show fragment length distribution histogram. │
|
|
329
331
|
│ --figdir -f DIR Directory to save the distribution figure. │
|
|
@@ -331,7 +333,7 @@ hicstuff digest --help
|
|
|
331
333
|
│ --help -h Show this message and exit. │
|
|
332
334
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
333
335
|
```
|
|
334
|
-
|
|
336
|
+
|
|
335
337
|
For example, to digest the yeast genome with MaeII and HinfI and show histogram of fragment lengths:
|
|
336
338
|
|
|
337
339
|
```sh
|
|
@@ -340,15 +342,15 @@ hicstuff digest --plot --outdir output_dir --enzyme MaeII,HinfI Sc_ref.fa
|
|
|
340
342
|
|
|
341
343
|
#### Filtering of 3C events
|
|
342
344
|
|
|
343
|
-
Filters spurious 3C events such as loops and uncuts from the library based on a minimum distance threshold automatically estimated from the library by default. Can also plot 3C library statistics. This module takes a pairs file with 9 columns as input (readID, chr1, pos1, chr2, pos2, strand1, strand2, frag1, frag2) and filters it.
|
|
345
|
+
Filters spurious 3C events such as loops and uncuts from the library based on a minimum distance threshold automatically estimated from the library by default. Can also plot 3C library statistics. This module takes a pairs file with 9 columns as input (readID, chr1, pos1, chr2, pos2, strand1, strand2, frag1, frag2) and filters it.
|
|
344
346
|
|
|
345
347
|
```
|
|
346
348
|
hicstuff filter --help
|
|
347
|
-
|
|
348
|
-
Usage: hicstuff filter [OPTIONS] INPUT_PAIRS OUTPUT_PAIRS
|
|
349
|
-
|
|
350
|
-
Filter spurious Hi-C events (loops and uncuts) from a pairs file.
|
|
351
|
-
|
|
349
|
+
|
|
350
|
+
Usage: hicstuff filter [OPTIONS] INPUT_PAIRS OUTPUT_PAIRS
|
|
351
|
+
|
|
352
|
+
Filter spurious Hi-C events (loops and uncuts) from a pairs file.
|
|
353
|
+
|
|
352
354
|
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮
|
|
353
355
|
│ * INPUT_PAIRS TEXT [required] │
|
|
354
356
|
│ * OUTPUT_PAIRS TEXT [required] │
|
|
@@ -371,11 +373,11 @@ output image to disk. If no output is specified, the output is displayed.
|
|
|
371
373
|
|
|
372
374
|
```
|
|
373
375
|
hicstuff view --help
|
|
374
|
-
|
|
375
|
-
Usage: hicstuff view [OPTIONS] CONTACT_MAP [CONTACT_MAP2]
|
|
376
|
-
|
|
377
|
-
Visualize a Hi-C matrix as a heatmap.
|
|
378
|
-
|
|
376
|
+
|
|
377
|
+
Usage: hicstuff view [OPTIONS] CONTACT_MAP [CONTACT_MAP2]
|
|
378
|
+
|
|
379
|
+
Visualize a Hi-C matrix as a heatmap.
|
|
380
|
+
|
|
379
381
|
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮
|
|
380
382
|
│ * CONTACT_MAP TEXT [required] │
|
|
381
383
|
│ CONTACT_MAP2 TEXT │
|
|
@@ -467,6 +469,20 @@ uv run ruff check src/
|
|
|
467
469
|
uv run ruff format src/
|
|
468
470
|
```
|
|
469
471
|
|
|
472
|
+
### Releasing
|
|
473
|
+
|
|
474
|
+
Releases are cut with [bump-my-version](https://github.com/callowayproject/bump-my-version) (configured in `pyproject.toml`, needs Python >= 3.10). From a clean, up-to-date `master`:
|
|
475
|
+
|
|
476
|
+
```bash
|
|
477
|
+
uv sync --extra dev # once, to install bump-my-version
|
|
478
|
+
uv run bump-my-version bump minor # or patch / major
|
|
479
|
+
git push --follow-tags
|
|
480
|
+
```
|
|
481
|
+
|
|
482
|
+
The bump updates the version in `pyproject.toml`, `uv.lock`, `doc/conf.py` and the `Dockerfile`, commits as `chore(release): vX.Y.Z` and creates the `vX.Y.Z` tag. Preview the changes first with `uv run bump-my-version bump patch --dry-run -vv`.
|
|
483
|
+
|
|
484
|
+
Pushing the tag triggers the [publish workflow](.github/workflows/publish.yml): it checks that the tag matches the `pyproject.toml` version, publishes the package to PyPI and pushes the Docker image to GHCR (`ghcr.io/koszullab/hicstuff`).
|
|
485
|
+
|
|
470
486
|
### Citation
|
|
471
487
|
|
|
472
488
|
Please cite hicstuff using the official DOI as follows:
|
|
@@ -494,4 +510,3 @@ Bibtex entry:
|
|
|
494
510
|
url = {http://doi.org/10.5281/zenodo.4066363}
|
|
495
511
|
}
|
|
496
512
|
```
|
|
497
|
-
|
|
@@ -30,7 +30,8 @@ The goal is to make generation and manipulation of Hi-C matrices as simple as po
|
|
|
30
30
|
5. [Viewing the contact map](#viewing-the-contact-map)
|
|
31
31
|
3. [File formats](#file-formats)
|
|
32
32
|
4. [Contributing](#contributing)
|
|
33
|
-
5. [
|
|
33
|
+
5. [Releasing](#releasing)
|
|
34
|
+
6. [Citation](#citation)
|
|
34
35
|
|
|
35
36
|
## Installation
|
|
36
37
|
|
|
@@ -49,8 +50,8 @@ cd hicstuff
|
|
|
49
50
|
uv sync --extra dev
|
|
50
51
|
```
|
|
51
52
|
|
|
52
|
-
If `hicstuff` is installed via pip, additional system dependencies such as
|
|
53
|
-
`bowtie2`, `bwa`, `minimap2` and `samtools` will be needed. You can install
|
|
53
|
+
If `hicstuff` is installed via pip, additional system dependencies such as
|
|
54
|
+
`bowtie2`, `bwa`, `minimap2` and `samtools` will be needed. You can install
|
|
54
55
|
them as follows on Debian/Ubuntu:
|
|
55
56
|
|
|
56
57
|
```bash
|
|
@@ -59,7 +60,7 @@ apt-get install bowtie2 bwa minimap2 samtools libbz2-dev liblzma-dev
|
|
|
59
60
|
|
|
60
61
|
### Conda
|
|
61
62
|
|
|
62
|
-
hicstuff is also available on bioconda, which will automatically handle all
|
|
63
|
+
hicstuff is also available on bioconda, which will automatically handle all
|
|
63
64
|
dependencies:
|
|
64
65
|
|
|
65
66
|
```bash
|
|
@@ -68,7 +69,7 @@ conda install bioconda::hicstuff
|
|
|
68
69
|
|
|
69
70
|
### Docker
|
|
70
71
|
|
|
71
|
-
Docker images are automatically built and published to GitHub Container
|
|
72
|
+
Docker images are automatically built and published to GitHub Container
|
|
72
73
|
Registry (GHCR) when releases are tagged:
|
|
73
74
|
|
|
74
75
|
```bash
|
|
@@ -78,16 +79,16 @@ docker pull ghcr.io/baudrly/hicstuff:<version>
|
|
|
78
79
|
|
|
79
80
|
## Usage
|
|
80
81
|
|
|
81
|
-
The hicstuff command line interface is composed of multiple subcommands.
|
|
82
|
+
The hicstuff command line interface is composed of multiple subcommands.
|
|
82
83
|
You can always get a summary of all available commands by running:
|
|
83
84
|
|
|
84
85
|
```txt
|
|
85
86
|
hicstuff --help
|
|
86
|
-
|
|
87
|
-
Usage: hicstuff [OPTIONS] COMMAND [ARGS]...
|
|
88
|
-
|
|
89
|
-
Simple Hi-C pipeline for generating and manipulating contact matrices.
|
|
90
|
-
|
|
87
|
+
|
|
88
|
+
Usage: hicstuff [OPTIONS] COMMAND [ARGS]...
|
|
89
|
+
|
|
90
|
+
Simple Hi-C pipeline for generating and manipulating contact matrices.
|
|
91
|
+
|
|
91
92
|
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
|
|
92
93
|
│ --version Show the version and exit. │
|
|
93
94
|
│ --help -h Show this message and exit. │
|
|
@@ -117,22 +118,22 @@ hicstuff --help
|
|
|
117
118
|
|
|
118
119
|
### Full pipeline
|
|
119
120
|
|
|
120
|
-
All components of the pipeline can be run at once using the `hicstuff pipeline` command.
|
|
121
|
-
This allows to generate a contact matrix from reads in a single command.
|
|
122
|
-
By default, the output is a `cool` file.
|
|
121
|
+
All components of the pipeline can be run at once using the `hicstuff pipeline` command.
|
|
122
|
+
This allows to generate a contact matrix from reads in a single command.
|
|
123
|
+
By default, the output is a `cool` file.
|
|
123
124
|
|
|
124
125
|
```txt
|
|
125
126
|
hicstuff pipeline --help
|
|
126
|
-
|
|
127
|
-
Usage: hicstuff pipeline [OPTIONS] INPUT1 [INPUT2]
|
|
128
|
-
|
|
129
|
-
Run the full Hi-C pipeline from FASTQ to contact matrix.
|
|
130
|
-
Example — generate a multi-resolution .mcool for Arima Hi-C:
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
hicstuff pipeline --enzyme "DpnII,HinfI" --binning 1000 --threads 8 \
|
|
134
|
-
--genome ref.fa R1.fq.gz R2.fq.gz
|
|
135
|
-
|
|
127
|
+
|
|
128
|
+
Usage: hicstuff pipeline [OPTIONS] INPUT1 [INPUT2]
|
|
129
|
+
|
|
130
|
+
Run the full Hi-C pipeline from FASTQ to contact matrix.
|
|
131
|
+
Example — generate a multi-resolution .mcool for Arima Hi-C:
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
hicstuff pipeline --enzyme "DpnII,HinfI" --binning 1000 --threads 8 \
|
|
135
|
+
--genome ref.fa R1.fq.gz R2.fq.gz
|
|
136
|
+
|
|
136
137
|
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮
|
|
137
138
|
│ * INPUT1 TEXT [required] │
|
|
138
139
|
│ INPUT2 TEXT │
|
|
@@ -162,7 +163,8 @@ hicstuff pipeline --help
|
|
|
162
163
|
│ --remove-centromeres -r INT kb to remove around centromere positions. [default: 0] │
|
|
163
164
|
│ --read-len -R INT Maximum read length (estimated from first read if │
|
|
164
165
|
│ omitted). │
|
|
165
|
-
│ --size -s INT Minimum contig size
|
|
166
|
+
│ --size -s INT Minimum contig size (bp): shorter contigs, and the pairs │
|
|
167
|
+
│ on them, are left out. [default: 0] │
|
|
166
168
|
│ --start-stage -S STR Pipeline start stage. [default: fastq] │
|
|
167
169
|
│ --threads -t INT Number of parallel threads. [default: 1] │
|
|
168
170
|
│ --tmpdir -T DIR Temporary directory. │
|
|
@@ -198,18 +200,18 @@ The general steps of the pipeline are as follows:
|
|
|
198
200
|
For more advanced usage, different scripts can be used independently on the command line to perform individual parts of the pipeline. This readme contains quick descriptions and example usages. To obtain detailed instructions on any subcommand, one can use `hicstuff <subcommand> --help`.
|
|
199
201
|
|
|
200
202
|
#### Digestion of fastq reads
|
|
201
|
-
|
|
203
|
+
|
|
202
204
|
Generates new gzipped fastq files from original fastq. The function will cut the reads at their religation sites and creates new pairs of reads with the different fragments obtained after cutting at the digestion sites.
|
|
203
205
|
|
|
204
206
|
```
|
|
205
207
|
hicstuff cutsite --help
|
|
206
|
-
|
|
207
|
-
Usage: hicstuff cutsite [OPTIONS]
|
|
208
|
-
|
|
209
|
-
Preprocess FASTQ files by cutting reads at religation sites.
|
|
210
|
-
Generates gzipped FASTQ files with reads cut at ligation junctions, creating new fragment pairs
|
|
211
|
-
for mapping.
|
|
212
|
-
|
|
208
|
+
|
|
209
|
+
Usage: hicstuff cutsite [OPTIONS]
|
|
210
|
+
|
|
211
|
+
Preprocess FASTQ files by cutting reads at religation sites.
|
|
212
|
+
Generates gzipped FASTQ files with reads cut at ligation junctions, creating new fragment pairs
|
|
213
|
+
for mapping.
|
|
214
|
+
|
|
213
215
|
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
|
|
214
216
|
│ * --forward -F FILE Forward reads FASTQ file. [required] │
|
|
215
217
|
│ * --reverse -R FILE Reverse reads FASTQ file. [required] │
|
|
@@ -228,13 +230,13 @@ Truncate reads from a fastq file to 20 basepairs and iteratively extend and re-a
|
|
|
228
230
|
|
|
229
231
|
```
|
|
230
232
|
hicstuff iteralign --help
|
|
231
|
-
|
|
232
|
-
Usage: hicstuff iteralign [OPTIONS] READS_FQ
|
|
233
|
-
|
|
234
|
-
Iteratively align reads to a reference genome.
|
|
235
|
-
Truncates reads to 20 bp then iteratively extends and re-aligns unmapped reads to maximise the
|
|
236
|
-
proportion of uniquely aligned reads in a 3C library.
|
|
237
|
-
|
|
233
|
+
|
|
234
|
+
Usage: hicstuff iteralign [OPTIONS] READS_FQ
|
|
235
|
+
|
|
236
|
+
Iteratively align reads to a reference genome.
|
|
237
|
+
Truncates reads to 20 bp then iteratively extends and re-aligns unmapped reads to maximise the
|
|
238
|
+
proportion of uniquely aligned reads in a 3C library.
|
|
239
|
+
|
|
238
240
|
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮
|
|
239
241
|
│ * READS_FQ TEXT [required] │
|
|
240
242
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
@@ -258,12 +260,12 @@ named "info_contigs.txt" and "fragments_list.txt"
|
|
|
258
260
|
|
|
259
261
|
```
|
|
260
262
|
hicstuff digest --help
|
|
261
|
-
|
|
262
|
-
Usage: hicstuff digest [OPTIONS] FASTA
|
|
263
|
-
|
|
264
|
-
Digest a genome FASTA into restriction fragments.
|
|
265
|
-
Writes ``fragments_list.txt`` and ``info_contigs.txt`` to the output directory.
|
|
266
|
-
|
|
263
|
+
|
|
264
|
+
Usage: hicstuff digest [OPTIONS] FASTA
|
|
265
|
+
|
|
266
|
+
Digest a genome FASTA into restriction fragments.
|
|
267
|
+
Writes ``fragments_list.txt`` and ``info_contigs.txt`` to the output directory.
|
|
268
|
+
|
|
267
269
|
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮
|
|
268
270
|
│ * FASTA TEXT [required] │
|
|
269
271
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
@@ -271,7 +273,8 @@ hicstuff digest --help
|
|
|
271
273
|
│ * --enzyme -e ENZ[,ENZ2,...] Restriction enzyme name(s) or fixed chunk size in bp. │
|
|
272
274
|
│ [required] │
|
|
273
275
|
│ --outdir -o DIR Output directory (default: current directory). │
|
|
274
|
-
│ --size -s INT Minimum
|
|
276
|
+
│ --size -s INT Minimum contig size (bp): shorter contigs are left out. │
|
|
277
|
+
│ [default: 0] │
|
|
275
278
|
│ --circular -c Genome is circular. │
|
|
276
279
|
│ --plot -p Show fragment length distribution histogram. │
|
|
277
280
|
│ --figdir -f DIR Directory to save the distribution figure. │
|
|
@@ -279,7 +282,7 @@ hicstuff digest --help
|
|
|
279
282
|
│ --help -h Show this message and exit. │
|
|
280
283
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
|
|
281
284
|
```
|
|
282
|
-
|
|
285
|
+
|
|
283
286
|
For example, to digest the yeast genome with MaeII and HinfI and show histogram of fragment lengths:
|
|
284
287
|
|
|
285
288
|
```sh
|
|
@@ -288,15 +291,15 @@ hicstuff digest --plot --outdir output_dir --enzyme MaeII,HinfI Sc_ref.fa
|
|
|
288
291
|
|
|
289
292
|
#### Filtering of 3C events
|
|
290
293
|
|
|
291
|
-
Filters spurious 3C events such as loops and uncuts from the library based on a minimum distance threshold automatically estimated from the library by default. Can also plot 3C library statistics. This module takes a pairs file with 9 columns as input (readID, chr1, pos1, chr2, pos2, strand1, strand2, frag1, frag2) and filters it.
|
|
294
|
+
Filters spurious 3C events such as loops and uncuts from the library based on a minimum distance threshold automatically estimated from the library by default. Can also plot 3C library statistics. This module takes a pairs file with 9 columns as input (readID, chr1, pos1, chr2, pos2, strand1, strand2, frag1, frag2) and filters it.
|
|
292
295
|
|
|
293
296
|
```
|
|
294
297
|
hicstuff filter --help
|
|
295
|
-
|
|
296
|
-
Usage: hicstuff filter [OPTIONS] INPUT_PAIRS OUTPUT_PAIRS
|
|
297
|
-
|
|
298
|
-
Filter spurious Hi-C events (loops and uncuts) from a pairs file.
|
|
299
|
-
|
|
298
|
+
|
|
299
|
+
Usage: hicstuff filter [OPTIONS] INPUT_PAIRS OUTPUT_PAIRS
|
|
300
|
+
|
|
301
|
+
Filter spurious Hi-C events (loops and uncuts) from a pairs file.
|
|
302
|
+
|
|
300
303
|
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮
|
|
301
304
|
│ * INPUT_PAIRS TEXT [required] │
|
|
302
305
|
│ * OUTPUT_PAIRS TEXT [required] │
|
|
@@ -319,11 +322,11 @@ output image to disk. If no output is specified, the output is displayed.
|
|
|
319
322
|
|
|
320
323
|
```
|
|
321
324
|
hicstuff view --help
|
|
322
|
-
|
|
323
|
-
Usage: hicstuff view [OPTIONS] CONTACT_MAP [CONTACT_MAP2]
|
|
324
|
-
|
|
325
|
-
Visualize a Hi-C matrix as a heatmap.
|
|
326
|
-
|
|
325
|
+
|
|
326
|
+
Usage: hicstuff view [OPTIONS] CONTACT_MAP [CONTACT_MAP2]
|
|
327
|
+
|
|
328
|
+
Visualize a Hi-C matrix as a heatmap.
|
|
329
|
+
|
|
327
330
|
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮
|
|
328
331
|
│ * CONTACT_MAP TEXT [required] │
|
|
329
332
|
│ CONTACT_MAP2 TEXT │
|
|
@@ -415,6 +418,20 @@ uv run ruff check src/
|
|
|
415
418
|
uv run ruff format src/
|
|
416
419
|
```
|
|
417
420
|
|
|
421
|
+
### Releasing
|
|
422
|
+
|
|
423
|
+
Releases are cut with [bump-my-version](https://github.com/callowayproject/bump-my-version) (configured in `pyproject.toml`, needs Python >= 3.10). From a clean, up-to-date `master`:
|
|
424
|
+
|
|
425
|
+
```bash
|
|
426
|
+
uv sync --extra dev # once, to install bump-my-version
|
|
427
|
+
uv run bump-my-version bump minor # or patch / major
|
|
428
|
+
git push --follow-tags
|
|
429
|
+
```
|
|
430
|
+
|
|
431
|
+
The bump updates the version in `pyproject.toml`, `uv.lock`, `doc/conf.py` and the `Dockerfile`, commits as `chore(release): vX.Y.Z` and creates the `vX.Y.Z` tag. Preview the changes first with `uv run bump-my-version bump patch --dry-run -vv`.
|
|
432
|
+
|
|
433
|
+
Pushing the tag triggers the [publish workflow](.github/workflows/publish.yml): it checks that the tag matches the `pyproject.toml` version, publishes the package to PyPI and pushes the Docker image to GHCR (`ghcr.io/koszullab/hicstuff`).
|
|
434
|
+
|
|
418
435
|
### Citation
|
|
419
436
|
|
|
420
437
|
Please cite hicstuff using the official DOI as follows:
|
|
@@ -442,4 +459,3 @@ Bibtex entry:
|
|
|
442
459
|
url = {http://doi.org/10.5281/zenodo.4066363}
|
|
443
460
|
}
|
|
444
461
|
```
|
|
445
|
-
|
|
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "hicstuff"
|
|
7
|
-
version = "3.
|
|
7
|
+
version = "3.3.0"
|
|
8
8
|
description = "General purpose stuff to generate and handle Hi-C data in its simplest form."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
requires-python = ">=3.8"
|
|
@@ -27,6 +27,7 @@ classifiers = [
|
|
|
27
27
|
"Programming Language :: Python :: 3.11",
|
|
28
28
|
"Programming Language :: Python :: 3.12",
|
|
29
29
|
"Programming Language :: Python :: 3.13",
|
|
30
|
+
"Programming Language :: Python :: 3.14",
|
|
30
31
|
"Topic :: Scientific/Engineering",
|
|
31
32
|
"Topic :: Scientific/Engineering :: Bio-Informatics",
|
|
32
33
|
"Topic :: Scientific/Engineering :: Visualization",
|
|
@@ -41,12 +42,9 @@ dependencies = [
|
|
|
41
42
|
"matplotlib>=3.4.0",
|
|
42
43
|
"rich-click>=1.7",
|
|
43
44
|
"biopython",
|
|
44
|
-
"requests",
|
|
45
|
-
"scikit-learn",
|
|
46
45
|
"pysam",
|
|
47
46
|
"pyfastx",
|
|
48
47
|
"cooler",
|
|
49
|
-
"pairtools",
|
|
50
48
|
]
|
|
51
49
|
|
|
52
50
|
[project.optional-dependencies]
|
|
@@ -58,6 +56,7 @@ dev = [
|
|
|
58
56
|
"sphinx",
|
|
59
57
|
"sphinx-rtd-theme",
|
|
60
58
|
"ipython>=8.12.3",
|
|
59
|
+
"bump-my-version>=1.2; python_version >= '3.10'",
|
|
61
60
|
]
|
|
62
61
|
|
|
63
62
|
[project.urls]
|
|
@@ -74,6 +73,36 @@ where = ["src"]
|
|
|
74
73
|
[tool.setuptools.package-data]
|
|
75
74
|
hicstuff = ["*"]
|
|
76
75
|
|
|
76
|
+
[tool.bumpversion]
|
|
77
|
+
current_version = "3.3.0"
|
|
78
|
+
commit = true
|
|
79
|
+
tag = true
|
|
80
|
+
tag_name = "v{new_version}"
|
|
81
|
+
message = "chore(release): v{new_version}"
|
|
82
|
+
allow_dirty = false
|
|
83
|
+
|
|
84
|
+
# Each entry pins the hicstuff version only: the `name = "hicstuff"` anchor
|
|
85
|
+
# keeps the search off `current_version` above and off other packages in uv.lock.
|
|
86
|
+
[[tool.bumpversion.files]]
|
|
87
|
+
filename = "pyproject.toml"
|
|
88
|
+
search = "name = \"hicstuff\"\nversion = \"{current_version}\""
|
|
89
|
+
replace = "name = \"hicstuff\"\nversion = \"{new_version}\""
|
|
90
|
+
|
|
91
|
+
[[tool.bumpversion.files]]
|
|
92
|
+
filename = "uv.lock"
|
|
93
|
+
search = "name = \"hicstuff\"\nversion = \"{current_version}\""
|
|
94
|
+
replace = "name = \"hicstuff\"\nversion = \"{new_version}\""
|
|
95
|
+
|
|
96
|
+
[[tool.bumpversion.files]]
|
|
97
|
+
filename = "doc/conf.py"
|
|
98
|
+
search = 'release = "{current_version}"'
|
|
99
|
+
replace = 'release = "{new_version}"'
|
|
100
|
+
|
|
101
|
+
[[tool.bumpversion.files]]
|
|
102
|
+
filename = "Dockerfile"
|
|
103
|
+
search = "LABEL Name=hicstuff Version={current_version}"
|
|
104
|
+
replace = "LABEL Name=hicstuff Version={new_version}"
|
|
105
|
+
|
|
77
106
|
[tool.ruff]
|
|
78
107
|
line-length = 100
|
|
79
108
|
target-version = "py38"
|
|
@@ -87,12 +116,17 @@ ignore = [
|
|
|
87
116
|
"UP006", # use `type` instead of `Type` (py3.9+)
|
|
88
117
|
]
|
|
89
118
|
|
|
119
|
+
[tool.ruff.format]
|
|
120
|
+
quote-style = "double"
|
|
121
|
+
|
|
90
122
|
[tool.pytest.ini_options]
|
|
91
123
|
testpaths = ["tests"]
|
|
92
124
|
|
|
93
125
|
[tool.coverage.run]
|
|
94
126
|
source = ["hicstuff"]
|
|
95
|
-
|
|
127
|
+
# _misc.py is archived experimental code that is no longer supported.
|
|
128
|
+
omit = ["*/tests/*", "*/hicstuff/_misc.py"]
|
|
96
129
|
|
|
97
130
|
[tool.coverage.report]
|
|
98
131
|
show_missing = true
|
|
132
|
+
fail_under = 85
|