GPatch 0.4.0__tar.gz → 0.6.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.
gpatch-0.6.0/PKG-INFO ADDED
@@ -0,0 +1,154 @@
1
+ Metadata-Version: 2.1
2
+ Name: gpatch
3
+ Version: 0.6.0
4
+ Summary: Assemble contigs into a chromosome-scalse pseudo-assembly using alignments to a reference sequence. Download the github repository for helper scripts to automate GPatch workflows, identify and correct misjoins in the contig assembly, produce dot-plots of patched pseudoassemblies to a reference assembly, and generate chrom.sizes and liftover chains for patched pseudoassemblies.
5
+ Home-page: https://github.com/adadiehl/GPatch
6
+ Author: Adam Diehl
7
+ Author-email: adadiehl@umich.edu
8
+ License: UNKNOWN
9
+ Description: # GPatch
10
+ ## Assemble contigs into a chromosome-scalse pseudo-assembly using alignments to a reference sequence.
11
+
12
+ Starting with alignments of contigs to a reference genome, produce a chromosome-scale pseudoassembly by patching gaps between mapped contigs with sequences from the reference.
13
+
14
+ ## Dependencies
15
+ * Python >= v3.7
16
+ * samtools (https://github.com/samtools/samtools)
17
+ * biopython (https://biopython.org/)
18
+ * pysam (https://github.com/pysam-developers/pysam)
19
+ * minimap2 (https://github.com/lh3/minimap2)
20
+
21
+ We recommend using minimap2 for alignment, using the -a option to generate SAM output.
22
+
23
+ ## Installation
24
+
25
+ We recommend installing with conda, into a new environment:
26
+ ```
27
+ conda create -n GPatch -c conda-forge -c bioconda Bio pysam minimap2 samtools GPatch
28
+ ```
29
+
30
+ Install with pip:
31
+ ```
32
+ pip install GPatch
33
+ ```
34
+
35
+ Installation from the github repository is not recommended. However, if you must, follow the steps below:
36
+ 1) git clone https://github.com/adadiehl/GPatch
37
+ 2) cd GPatch/
38
+ 3) python3 -m pip install -e .
39
+
40
+
41
+ ## Usage
42
+ ```
43
+ GPatch.py [-h] -q SAM/BAM -r FASTA [-x STR] [-b FILENAME] [-m N] [-w PATH] [-d] [-t] [-s] [-l N] [-e] [-k]
44
+ [--legacy_junctions] [--max_resid N] [--chain_mapq N] [--chain_minlen N] [--chain_maxgap N]
45
+ [--chain_tol N] [--anchor N] [--min_overlap_identity F] [--indel_tol N] [--max_mm2_tests N]
46
+ [--win_min N] [--win_max N] [--minimap2 PATH] [--threads N]
47
+ [--no_extension] [--ext_min_overlap N] [--ext_region_pad N] [--ext_window N] [--ext_max_steps N]
48
+ ```
49
+
50
+ Starting with alignments of contigs to a reference genome, produce a chromosome-scale pseudoassembly by patching gaps between mapped contigs with sequences from the reference. By default, reference chromosomes with no mapped contigs are printed to output unchanged. Use the --drop_missing option to disable this behavior. By default, patches are applied to the 5' and 3' telomere ends of pseudochromsomes if the first and last contig alignments do not extend to the start/end of the reference chromsome. In some cases, this may cause spurious duplications. Use the --no_extend option if this is a concern. Note that GPatch is designed to be run on single-haplotype or unphased genome assemblies. For phased assemblies, each haplotype should be separated into its own input FASTA file prior to alignment. GPatch can then be run separately on the BAM files for each haplotype to obtain phased pseudoassemblies, otherwise results will be unpredictable and likely incorrect.
51
+
52
+ #### Required Arguments
53
+ | Argument | Description |
54
+ |---|---|
55
+ | __-q SAM/BAM, --query_bam SAM/BAM__ | Path to SAM/BAM file containing non-overlapping contig mappings to the reference genome. |
56
+ | __-r FASTA, --reference_fasta FASTA__ | Path to reference genome fasta. |
57
+
58
+ #### Optional Arguments:
59
+ | Argument | Description |
60
+ |---|---|
61
+ | __-h, --help__ | Show this help message and exit. |
62
+ | __-x STR, --prefix STR__ | Prefix to add to output file names. Default=None |
63
+ | __-b FILENAME, --store_final_bam FILENAME__ | Store the final set of primary contig alignments to the given file name. Default: Do not store the final BAM. |
64
+ | __-m N, --min_qual_score N__ | Minimum mapping quality score to retain an alignment. Default=30 |
65
+ | __-w PATH, --whitelist PATH__ | Path to BED file containing whitelist regions: i.e., the inverse of blacklist regions. Supplying this will have the effect of excluding alignments that fall entirely within blacklist regions. Default=None |
66
+ | __-d, --drop_missing__ | Omit unpatched reference chromosome records from the output if no contigs map to them. Default: Unpatched chromosomes are printed to output unchanged. |
67
+ | __-t, --no_trim__ | Do not trim the 5' end of contigs that overlap the previously-placed contig; overlapping contigs are bookended untrimmed. Default: Trim the overlap, measured directly from the contig sequences (or, with --legacy_junctions, inferred from the soft-clip-extended alignment coordinates). |
68
+ | __-s, --scaffold_only__ | Pad gaps between placed contigs with strings of N characters instead of patching with sequence from the reference assembly. Effectively turns GPatch into a reference-guided scaffolding tool. Note that patches.bed will still be generated to document (inverse) mapped contig boundaries in reference frame. |
69
+ | __-l N, --gap_length N__ | Length of "N" gaps separating placed gontigs when using --scaffold_only. Has no effect when in default patching mode. Default=Estimate gap length from alignment. |
70
+ | __-e, --no_extend__ | Do not patch telomere ends of pseudochromosomes with reference sequence upstream of the first mapped contig and downstream of the last mapped contig. Default is to include 5' and 3' patches to extend telomeres to the ends implied by the alignment. |
71
+ | __-k, --keep_nested__ | Do not drop contigs with mapped positions nested entirely inside other mapped contigs. Instead, these will be bookended after the contig in which they are nested. Default is to drop contigs with mapped positions nested entirely within other mapped contigs. This option should be used with caution as these mappings cannot be placed unambigiously relative to other mapped contigs, thus including them is likely to lead to unpredictable and possibly incorrect results. Do not use this unless you are sure you know what you are doing! |
72
+
73
+ #### Junction-Handling Arguments:
74
+ | Argument | Description |
75
+ |---|---|
76
+ | __--legacy_junctions__ | Use the original (GPatch <= 0.4) junction logic: contig extents from the primary alignment extended by its full soft-clips, overlaps trimmed by the overlap of those extents, and gaps patched by their distance. No junctions.tsv is written. |
77
+ | __--max_resid N__ | Maximum unaligned sequence (bp) remaining at a contig end, after chaining, for the reference gap estimate at that end to be trusted. Default=10000 |
78
+ | __--chain_mapq N__ | Minimum mapping quality of supplementary alignments used to extend contig extents. Default=20 |
79
+ | __--chain_minlen N__ | Minimum aligned query length (bp) of supplementary alignments used to extend contig extents. Default=10000 |
80
+ | __--chain_maxgap N__ | Maximum gap (bp), in both query and reference, between chained alignments. Default=1000000 |
81
+ | __--chain_tol N__ | Maximum overlap (bp) allowed between chained alignments. Default=10000 |
82
+ | __--anchor N__ | Length (bp) of the exact anchors used to detect overlaps between adjacent contigs; also the minimum detectable overlap. Default=500 |
83
+ | __--min_overlap_identity F__ | Minimum identity over the whole overlap for a candidate overlap to be accepted. Default=0.999 |
84
+ | __--indel_tol N__ | Maximum length difference (bp) between the two anchor-implied overlap lengths for a candidate containing indels; such candidates are verified with minimap2. 0 disables. Default=50 |
85
+ | __--max_mm2_tests N__ | Maximum number of indel-containing candidate overlaps verified with minimap2 per junction. Default=20 |
86
+ | __--win_min N__ | Minimum size (bp) of the contig-end windows searched for overlaps. Default=1000000 |
87
+ | __--win_max N__ | Maximum size (bp) of the contig-end windows searched for overlaps. Default=4000000 |
88
+ | __--minimap2 PATH__ | Path to minimap2, used only to verify candidate overlaps containing indels. Default: minimap2 on PATH; if not found, such candidates are not considered. |
89
+ | __--threads N__ | Number of processes used for overlap detection. Default=1 |
90
+
91
+ #### Overlap-Extension Arguments:
92
+ | Argument | Description |
93
+ |---|---|
94
+ | __--no_extension__ | Do not insert unplaced contigs by overlap extension. |
95
+ | __--ext_min_overlap N__ | Minimum overlap (bp) for an extension step, or for a walk to be considered to have reached the opposite flanking contig. Short overlaps in tandem and palindromic repeats are often spurious. Default=5000 |
96
+ | __--ext_region_pad N__ | A candidate contig's primary alignment must lie within the gap region extended by this many bp beyond the flanking contigs' alignments. Default=1000000 |
97
+ | __--ext_window N__ | Size (bp) of the contig-end windows searched for extension overlaps. Default=2000000 |
98
+ | __--ext_max_steps N__ | Maximum number of contigs added by one walk. Default=50 |
99
+
100
+ ## Junction Handling
101
+
102
+ At each junction between adjacent placed contigs, GPatch either trims the 5' end of the second contig (the contigs overlap), patches the gap between them with reference sequence, or bookends them. N characters are never introduced, except that patches are replaced by N runs in --scaffold_only mode.
103
+
104
+ 1. __Contig extents.__ The primary alignment of each contig is chained to supplementary alignments of the same contig that are on the same chromosome and strand and colinear with it in both query and reference. Each contig end is then extrapolated onto the reference only by the unaligned sequence remaining beyond the outermost chained alignment (the "residual"). These extents are also used to identify nested contigs. With --legacy_junctions, the primary alignment's full soft-clips are used instead.
105
+ 2. __Overlap measurement.__ Overlaps are measured directly from the contig sequences. Candidate overlaps come from exact matches of two anchors: the next contig's first bases within the end of the previous contig, and the previous contig's last bases within the start of the next contig. A candidate supported by both anchors is accepted if identity over the whole overlap is at least --min_overlap_identity.
106
+ 3. __Decision.__ The extent-based gap estimate is *trusted* when the residuals at both contig ends of the junction are at most --max_resid, *one-sided* when only one exceeds it, and *untrusted* otherwise.
107
+
108
+ | Decision | When |
109
+ |---|---|
110
+ | trim_measured | Exactly one overlap was found; it is trimmed. |
111
+ | trim_ambiguous | Several overlap offsets were found (tandem repeats). The one closest to the estimated overlap is trimmed if the estimate is trusted or one-sided; otherwise the smallest. |
112
+ | patch | No overlap; the estimated gap is >= 0 and trusted. The gap is patched with reference sequence. |
113
+ | patch_one_sided | No overlap; the estimated gap is >= 0 and one-sided. The gap is patched with reference sequence. |
114
+ | bookend | No overlap; the estimate predicts an overlap or is untrusted. The contigs are joined directly. |
115
+
116
+ __Overlap extension.__ Contigs left out because of low mapping quality or nesting are often unambiguously connected to placed contigs by sequence overlap. After alignment-based placement, GPatch walks into each gap (and each chromosome end) from both flanking placed contigs. At each step, it adds an unplaced contig if it is the only one that overlaps the current contig end by at least --ext_min_overlap and its primary alignment is on the same reference sequence, within the gap region and in the orientation in which it would be placed. A walk stops at the first ambiguous or missing step, or when it reaches the contig on the other side of the gap; contigs claimed by more than one walk are rejected. Because the alignments of inserted contigs are unreliable, their reference extents are carried from the contig each was reached from through the measured overlap, and inherit that contig's residual for the decision rules. Every step and stop reason is written to extension.tsv. Disable with --no_extension.
117
+
118
+ Chromosome ends are patched when the residual at the terminal contig end is at most --max_resid (and --no_extend is not set). Contigs are never trimmed against a chromosome end. The decision and reasoning for every junction are written to junctions.tsv.
119
+
120
+ ## Output
121
+
122
+ GPatch produces the following output files:
123
+ | File | Description |
124
+ |---|---|
125
+ | __patched.fasta__ | The final patched genome. |
126
+ | __contigs.bed__ | Location of contigs in the coordinate frame of the patched genome. |
127
+ | __patches.bed__ | Location of patches in the coordinate frame of the reference genome. |
128
+ | __unplaced.tsv__ | Contigs in the input BAM that are not in the pseudoassembly, with the reason (unmapped, low_mapq, whitelist, nested) and their primary alignment. |
129
+ | __unplaced.fasta__ | Sequences of the unplaced contigs, in their original orientation. |
130
+ | __extension.tsv__ | Every overlap-extension walk step (contig added, orientation, overlaps) and the reason each walk stopped, including contigs rejected because several walks claimed them. Not written with --legacy_junctions or --no_extension. |
131
+ | __junctions.tsv__ | The decision (trim, patch or bookend) made at each junction between adjacent contigs and at chromosome ends, with the contig extents, residual unaligned lengths, gap estimate, candidate overlaps and the reason for the decision. Not written with --legacy_junctions. |
132
+
133
+ ## Helper Scripts
134
+
135
+ The scripts directory contains helper scripts for running GPatch and working with its output, including a shell script to automate a two-stage patching process, including initial alignment and patching steps, misjoin breakpoint prediction and contig-breaking, and subsequent realignment and patching of the split contigs, with dot-plots against the reference assembly created after both patching stages. In addition, scripts are provided to generate a chrom.sizes file for a patched pseudoassembly and a set of liftover chains that can be used to translate features mapped to the unpatched contigs to the patched pseudoassembly. Please see the README.md within the scripts for detailed usage information.
136
+
137
+ ## Citing GPatch
138
+ Please use the following citation if you use this software in your work:
139
+
140
+ Fast and Accurate Draft Genome Patching with GPatch
141
+ Adam Diehl, Alan Boyle
142
+ bioRxiv 2025.05.22.655567; doi: https://doi.org/10.1101/2025.05.22.655567
143
+
144
+ Keywords: genomics,genome assembly
145
+ Platform: UNKNOWN
146
+ Classifier: Development Status :: 4 - Beta
147
+ Classifier: Programming Language :: Python :: 3
148
+ Classifier: License :: OSI Approved :: MIT License
149
+ Classifier: Operating System :: OS Independent
150
+ Classifier: Intended Audience :: Science/Research
151
+ Classifier: Topic :: Scientific/Engineering
152
+ Classifier: Topic :: Scientific/Engineering :: Information Analysis
153
+ Classifier: Natural Language :: English
154
+ Description-Content-Type: text/markdown
gpatch-0.6.0/README.md ADDED
@@ -0,0 +1,134 @@
1
+ # GPatch
2
+ ## Assemble contigs into a chromosome-scalse pseudo-assembly using alignments to a reference sequence.
3
+
4
+ Starting with alignments of contigs to a reference genome, produce a chromosome-scale pseudoassembly by patching gaps between mapped contigs with sequences from the reference.
5
+
6
+ ## Dependencies
7
+ * Python >= v3.7
8
+ * samtools (https://github.com/samtools/samtools)
9
+ * biopython (https://biopython.org/)
10
+ * pysam (https://github.com/pysam-developers/pysam)
11
+ * minimap2 (https://github.com/lh3/minimap2)
12
+
13
+ We recommend using minimap2 for alignment, using the -a option to generate SAM output.
14
+
15
+ ## Installation
16
+
17
+ We recommend installing with conda, into a new environment:
18
+ ```
19
+ conda create -n GPatch -c conda-forge -c bioconda Bio pysam minimap2 samtools GPatch
20
+ ```
21
+
22
+ Install with pip:
23
+ ```
24
+ pip install GPatch
25
+ ```
26
+
27
+ Installation from the github repository is not recommended. However, if you must, follow the steps below:
28
+ 1) git clone https://github.com/adadiehl/GPatch
29
+ 2) cd GPatch/
30
+ 3) python3 -m pip install -e .
31
+
32
+
33
+ ## Usage
34
+ ```
35
+ GPatch.py [-h] -q SAM/BAM -r FASTA [-x STR] [-b FILENAME] [-m N] [-w PATH] [-d] [-t] [-s] [-l N] [-e] [-k]
36
+ [--legacy_junctions] [--max_resid N] [--chain_mapq N] [--chain_minlen N] [--chain_maxgap N]
37
+ [--chain_tol N] [--anchor N] [--min_overlap_identity F] [--indel_tol N] [--max_mm2_tests N]
38
+ [--win_min N] [--win_max N] [--minimap2 PATH] [--threads N]
39
+ [--no_extension] [--ext_min_overlap N] [--ext_region_pad N] [--ext_window N] [--ext_max_steps N]
40
+ ```
41
+
42
+ Starting with alignments of contigs to a reference genome, produce a chromosome-scale pseudoassembly by patching gaps between mapped contigs with sequences from the reference. By default, reference chromosomes with no mapped contigs are printed to output unchanged. Use the --drop_missing option to disable this behavior. By default, patches are applied to the 5' and 3' telomere ends of pseudochromsomes if the first and last contig alignments do not extend to the start/end of the reference chromsome. In some cases, this may cause spurious duplications. Use the --no_extend option if this is a concern. Note that GPatch is designed to be run on single-haplotype or unphased genome assemblies. For phased assemblies, each haplotype should be separated into its own input FASTA file prior to alignment. GPatch can then be run separately on the BAM files for each haplotype to obtain phased pseudoassemblies, otherwise results will be unpredictable and likely incorrect.
43
+
44
+ #### Required Arguments
45
+ | Argument | Description |
46
+ |---|---|
47
+ | __-q SAM/BAM, --query_bam SAM/BAM__ | Path to SAM/BAM file containing non-overlapping contig mappings to the reference genome. |
48
+ | __-r FASTA, --reference_fasta FASTA__ | Path to reference genome fasta. |
49
+
50
+ #### Optional Arguments:
51
+ | Argument | Description |
52
+ |---|---|
53
+ | __-h, --help__ | Show this help message and exit. |
54
+ | __-x STR, --prefix STR__ | Prefix to add to output file names. Default=None |
55
+ | __-b FILENAME, --store_final_bam FILENAME__ | Store the final set of primary contig alignments to the given file name. Default: Do not store the final BAM. |
56
+ | __-m N, --min_qual_score N__ | Minimum mapping quality score to retain an alignment. Default=30 |
57
+ | __-w PATH, --whitelist PATH__ | Path to BED file containing whitelist regions: i.e., the inverse of blacklist regions. Supplying this will have the effect of excluding alignments that fall entirely within blacklist regions. Default=None |
58
+ | __-d, --drop_missing__ | Omit unpatched reference chromosome records from the output if no contigs map to them. Default: Unpatched chromosomes are printed to output unchanged. |
59
+ | __-t, --no_trim__ | Do not trim the 5' end of contigs that overlap the previously-placed contig; overlapping contigs are bookended untrimmed. Default: Trim the overlap, measured directly from the contig sequences (or, with --legacy_junctions, inferred from the soft-clip-extended alignment coordinates). |
60
+ | __-s, --scaffold_only__ | Pad gaps between placed contigs with strings of N characters instead of patching with sequence from the reference assembly. Effectively turns GPatch into a reference-guided scaffolding tool. Note that patches.bed will still be generated to document (inverse) mapped contig boundaries in reference frame. |
61
+ | __-l N, --gap_length N__ | Length of "N" gaps separating placed gontigs when using --scaffold_only. Has no effect when in default patching mode. Default=Estimate gap length from alignment. |
62
+ | __-e, --no_extend__ | Do not patch telomere ends of pseudochromosomes with reference sequence upstream of the first mapped contig and downstream of the last mapped contig. Default is to include 5' and 3' patches to extend telomeres to the ends implied by the alignment. |
63
+ | __-k, --keep_nested__ | Do not drop contigs with mapped positions nested entirely inside other mapped contigs. Instead, these will be bookended after the contig in which they are nested. Default is to drop contigs with mapped positions nested entirely within other mapped contigs. This option should be used with caution as these mappings cannot be placed unambigiously relative to other mapped contigs, thus including them is likely to lead to unpredictable and possibly incorrect results. Do not use this unless you are sure you know what you are doing! |
64
+
65
+ #### Junction-Handling Arguments:
66
+ | Argument | Description |
67
+ |---|---|
68
+ | __--legacy_junctions__ | Use the original (GPatch <= 0.4) junction logic: contig extents from the primary alignment extended by its full soft-clips, overlaps trimmed by the overlap of those extents, and gaps patched by their distance. No junctions.tsv is written. |
69
+ | __--max_resid N__ | Maximum unaligned sequence (bp) remaining at a contig end, after chaining, for the reference gap estimate at that end to be trusted. Default=10000 |
70
+ | __--chain_mapq N__ | Minimum mapping quality of supplementary alignments used to extend contig extents. Default=20 |
71
+ | __--chain_minlen N__ | Minimum aligned query length (bp) of supplementary alignments used to extend contig extents. Default=10000 |
72
+ | __--chain_maxgap N__ | Maximum gap (bp), in both query and reference, between chained alignments. Default=1000000 |
73
+ | __--chain_tol N__ | Maximum overlap (bp) allowed between chained alignments. Default=10000 |
74
+ | __--anchor N__ | Length (bp) of the exact anchors used to detect overlaps between adjacent contigs; also the minimum detectable overlap. Default=500 |
75
+ | __--min_overlap_identity F__ | Minimum identity over the whole overlap for a candidate overlap to be accepted. Default=0.999 |
76
+ | __--indel_tol N__ | Maximum length difference (bp) between the two anchor-implied overlap lengths for a candidate containing indels; such candidates are verified with minimap2. 0 disables. Default=50 |
77
+ | __--max_mm2_tests N__ | Maximum number of indel-containing candidate overlaps verified with minimap2 per junction. Default=20 |
78
+ | __--win_min N__ | Minimum size (bp) of the contig-end windows searched for overlaps. Default=1000000 |
79
+ | __--win_max N__ | Maximum size (bp) of the contig-end windows searched for overlaps. Default=4000000 |
80
+ | __--minimap2 PATH__ | Path to minimap2, used only to verify candidate overlaps containing indels. Default: minimap2 on PATH; if not found, such candidates are not considered. |
81
+ | __--threads N__ | Number of processes used for overlap detection. Default=1 |
82
+
83
+ #### Overlap-Extension Arguments:
84
+ | Argument | Description |
85
+ |---|---|
86
+ | __--no_extension__ | Do not insert unplaced contigs by overlap extension. |
87
+ | __--ext_min_overlap N__ | Minimum overlap (bp) for an extension step, or for a walk to be considered to have reached the opposite flanking contig. Short overlaps in tandem and palindromic repeats are often spurious. Default=5000 |
88
+ | __--ext_region_pad N__ | A candidate contig's primary alignment must lie within the gap region extended by this many bp beyond the flanking contigs' alignments. Default=1000000 |
89
+ | __--ext_window N__ | Size (bp) of the contig-end windows searched for extension overlaps. Default=2000000 |
90
+ | __--ext_max_steps N__ | Maximum number of contigs added by one walk. Default=50 |
91
+
92
+ ## Junction Handling
93
+
94
+ At each junction between adjacent placed contigs, GPatch either trims the 5' end of the second contig (the contigs overlap), patches the gap between them with reference sequence, or bookends them. N characters are never introduced, except that patches are replaced by N runs in --scaffold_only mode.
95
+
96
+ 1. __Contig extents.__ The primary alignment of each contig is chained to supplementary alignments of the same contig that are on the same chromosome and strand and colinear with it in both query and reference. Each contig end is then extrapolated onto the reference only by the unaligned sequence remaining beyond the outermost chained alignment (the "residual"). These extents are also used to identify nested contigs. With --legacy_junctions, the primary alignment's full soft-clips are used instead.
97
+ 2. __Overlap measurement.__ Overlaps are measured directly from the contig sequences. Candidate overlaps come from exact matches of two anchors: the next contig's first bases within the end of the previous contig, and the previous contig's last bases within the start of the next contig. A candidate supported by both anchors is accepted if identity over the whole overlap is at least --min_overlap_identity.
98
+ 3. __Decision.__ The extent-based gap estimate is *trusted* when the residuals at both contig ends of the junction are at most --max_resid, *one-sided* when only one exceeds it, and *untrusted* otherwise.
99
+
100
+ | Decision | When |
101
+ |---|---|
102
+ | trim_measured | Exactly one overlap was found; it is trimmed. |
103
+ | trim_ambiguous | Several overlap offsets were found (tandem repeats). The one closest to the estimated overlap is trimmed if the estimate is trusted or one-sided; otherwise the smallest. |
104
+ | patch | No overlap; the estimated gap is >= 0 and trusted. The gap is patched with reference sequence. |
105
+ | patch_one_sided | No overlap; the estimated gap is >= 0 and one-sided. The gap is patched with reference sequence. |
106
+ | bookend | No overlap; the estimate predicts an overlap or is untrusted. The contigs are joined directly. |
107
+
108
+ __Overlap extension.__ Contigs left out because of low mapping quality or nesting are often unambiguously connected to placed contigs by sequence overlap. After alignment-based placement, GPatch walks into each gap (and each chromosome end) from both flanking placed contigs. At each step, it adds an unplaced contig if it is the only one that overlaps the current contig end by at least --ext_min_overlap and its primary alignment is on the same reference sequence, within the gap region and in the orientation in which it would be placed. A walk stops at the first ambiguous or missing step, or when it reaches the contig on the other side of the gap; contigs claimed by more than one walk are rejected. Because the alignments of inserted contigs are unreliable, their reference extents are carried from the contig each was reached from through the measured overlap, and inherit that contig's residual for the decision rules. Every step and stop reason is written to extension.tsv. Disable with --no_extension.
109
+
110
+ Chromosome ends are patched when the residual at the terminal contig end is at most --max_resid (and --no_extend is not set). Contigs are never trimmed against a chromosome end. The decision and reasoning for every junction are written to junctions.tsv.
111
+
112
+ ## Output
113
+
114
+ GPatch produces the following output files:
115
+ | File | Description |
116
+ |---|---|
117
+ | __patched.fasta__ | The final patched genome. |
118
+ | __contigs.bed__ | Location of contigs in the coordinate frame of the patched genome. |
119
+ | __patches.bed__ | Location of patches in the coordinate frame of the reference genome. |
120
+ | __unplaced.tsv__ | Contigs in the input BAM that are not in the pseudoassembly, with the reason (unmapped, low_mapq, whitelist, nested) and their primary alignment. |
121
+ | __unplaced.fasta__ | Sequences of the unplaced contigs, in their original orientation. |
122
+ | __extension.tsv__ | Every overlap-extension walk step (contig added, orientation, overlaps) and the reason each walk stopped, including contigs rejected because several walks claimed them. Not written with --legacy_junctions or --no_extension. |
123
+ | __junctions.tsv__ | The decision (trim, patch or bookend) made at each junction between adjacent contigs and at chromosome ends, with the contig extents, residual unaligned lengths, gap estimate, candidate overlaps and the reason for the decision. Not written with --legacy_junctions. |
124
+
125
+ ## Helper Scripts
126
+
127
+ The scripts directory contains helper scripts for running GPatch and working with its output, including a shell script to automate a two-stage patching process, including initial alignment and patching steps, misjoin breakpoint prediction and contig-breaking, and subsequent realignment and patching of the split contigs, with dot-plots against the reference assembly created after both patching stages. In addition, scripts are provided to generate a chrom.sizes file for a patched pseudoassembly and a set of liftover chains that can be used to translate features mapped to the unpatched contigs to the patched pseudoassembly. Please see the README.md within the scripts for detailed usage information.
128
+
129
+ ## Citing GPatch
130
+ Please use the following citation if you use this software in your work:
131
+
132
+ Fast and Accurate Draft Genome Patching with GPatch
133
+ Adam Diehl, Alan Boyle
134
+ bioRxiv 2025.05.22.655567; doi: https://doi.org/10.1101/2025.05.22.655567
@@ -29,7 +29,7 @@ def main():
29
29
 
30
30
  metadata = dict(
31
31
  name="gpatch",
32
- version="0.4.0",
32
+ version="0.6.0",
33
33
  author="Adam Diehl",
34
34
  author_email="adadiehl@umich.edu",
35
35
  description="Assemble contigs into a chromosome-scalse pseudo-assembly using alignments to a reference sequence. Download the github repository for helper scripts to automate GPatch workflows, identify and correct misjoins in the contig assembly, produce dot-plots of patched pseudoassemblies to a reference assembly, and generate chrom.sizes and liftover chains for patched pseudoassemblies.",