prokapeak 0.1.0__py3-none-any.whl

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.
assign_targets.py ADDED
@@ -0,0 +1,251 @@
1
+ #!/usr/bin/env python3
2
+ """ProkaPeak: assign MACS3 peaks to target genes through TSS and gene-start windows.
3
+ Checked on small artificial test data (example/)."""
4
+ import argparse
5
+ import re
6
+ import sys
7
+ from pathlib import Path
8
+
9
+ import numpy as np
10
+ import pandas as pd
11
+
12
+ from predict_operons import CUTOFF, predict_operons
13
+
14
+ TSS_WINDOW, START_WINDOW, INTERNAL_WINDOW = (-200, 100), (-400, 25), (-250, 50) # up, down in bp around the anchor
15
+ OVERLAP_RULES = ("closest", "both", "farthest") # which of several overlapping windows a summit is assigned to
16
+ SAME_STRAND, OPP_STRAND = "closest", "closest" # default rule: on one strand; across the two strands
17
+ CHUNK = 50 # peaks per pass; bounds the size of the summit x anchor matrix
18
+
19
+
20
+ def ext(path, *ok):
21
+ if not Path(path).is_file():
22
+ raise ValueError(f"{path}: file not found")
23
+ if Path(path).suffix not in ok:
24
+ raise ValueError(f"{path}: file name must end in {' or '.join(ok)} (plain text, not gzipped)")
25
+ return Path(path).suffix
26
+
27
+
28
+ def read_table(path, n, what, num=(1, 2, 9)):
29
+ """Tab-separated, no header, at least n columns; columns num (0-based, those < n) must be integers."""
30
+ try:
31
+ t = pd.read_csv(path, sep="\t", header=None, comment="#", dtype=str)
32
+ except pd.errors.EmptyDataError:
33
+ t = pd.DataFrame(columns=range(n), dtype=str)
34
+ except pd.errors.ParserError:
35
+ raise ValueError(f"{path}: {what}, tab-separated without header lines")
36
+ if t.shape[1] < n:
37
+ raise ValueError(f"{path}: {what}; found {t.shape[1]} columns")
38
+ num = t[[c for c in num if c < n]].apply(pd.to_numeric, errors="coerce")
39
+ if num.isna().any().any():
40
+ raise ValueError(f"{path}: {what}; non-integer coordinates (header line?)")
41
+ t[num.columns] = num.astype(int)
42
+ return t
43
+
44
+
45
+ def read_genome(gff, features=("gene", "CDS"), attribute="locus_tag"):
46
+ """GFF3 path or file -> one span per locus (locus, chrom, start, end, strand), list of warnings."""
47
+ rows, types, attrs, w = [], set(), set(), []
48
+ for line in (gff if hasattr(gff, "read") else open(gff)):
49
+ f = line.rstrip("\r\n").split("\t")
50
+ if line.startswith("#") or len(f) < 9:
51
+ continue
52
+ types.add(f[2])
53
+ if f[2] in features:
54
+ attrs.update(x.partition("=")[0] for x in f[8].split(";"))
55
+ if m := re.search(rf"(?:^|;){re.escape(attribute)}=([^;]+)", f[8]):
56
+ rows.append((m.group(1), f[0], int(f[3]), int(f[4]), f[6]))
57
+ g = pd.DataFrame(rows, columns=["locus", "chrom", "start", "end", "strand"])
58
+ split = g.groupby("locus")[["chrom", "strand"]].nunique().max(axis=1) > 1
59
+ if split.any():
60
+ w.append(f"gff: {split.sum()} loci with rows on several chromosomes or strands dropped: {list(split.index[split][:3])}")
61
+ g = g[~g.locus.isin(split.index[split])]
62
+ g = g.groupby("locus", sort=False).agg({"chrom": "first", "start": "min", "end": "max", "strand": "first"}).reset_index()
63
+ if g.empty:
64
+ raise ValueError(f"gff: no {'/'.join(features)} feature with a {attribute} attribute. Feature types in the "
65
+ f"file: {', '.join(sorted(types))}; attributes of the {'/'.join(features)} rows: "
66
+ f"{', '.join(sorted(attrs)) or 'none'}. Set --gff-feature and --gff-attribute to match.")
67
+ return g, w
68
+
69
+
70
+ def build_units(g, operons=None, tss=None, tss_window=TSS_WINDOW, start_window=START_WINDOW,
71
+ internal_window=INTERNAL_WINDOW, no_internal=False, no_gene_start=False):
72
+ """Units to assign (operon starts, internal starts or single genes) with anchor and window, list of warnings.
73
+ operons: table with operon id and comma-separated locus tags per row; tss: BED6 table; from read_table, or None."""
74
+ w = []
75
+ sc = dict(zip(g.locus, np.where(g.strand == "+", g.start, g.end)))
76
+ strand, chrom = dict(zip(g.locus, g.strand)), dict(zip(g.locus, g.chrom))
77
+ base = [] # units: genes ordered 5'->3', the first gene's start codon is the unit start
78
+ if operons is not None:
79
+ op = operons.iloc[:, :2].set_axis(["operon", "locus"], axis=1)
80
+ op = op.assign(locus=op.locus.str.strip().str.split(r"\s*,\s*", regex=True)).explode("locus") # one row per gene
81
+ if unknown := (~op.locus.isin(g.locus)).sum():
82
+ w.append(f"operons: {unknown}/{len(op)} listed genes are not in the annotation")
83
+ order = dict(zip(g.locus, np.where(g.strand == "+", g.start, -g.start))) # 5'->3' along the strand
84
+ split = 0
85
+ for oid, genes in op[op.locus.isin(g.locus)].groupby("operon", sort=False).locus:
86
+ genes = sorted(genes, key=order.get)
87
+ if len({(chrom[x], strand[x]) for x in genes}) > 1:
88
+ split += 1
89
+ continue
90
+ for i in range(1 if no_internal else len(genes)):
91
+ base.append(dict(operon=oid, internal=bool(i), genes=genes[i:]))
92
+ if split:
93
+ w.append(f"operons: {split} operons with genes on several chromosomes or strands ignored")
94
+ listed = {x for u in base for x in u["genes"]}
95
+ base += [dict(operon=".", internal=False, genes=[x]) for x in g.locus if x not in listed] # single-gene units
96
+
97
+ links = {} # gene -> positions of the TSSs that start it, on its strand and chromosome
98
+ if tss is not None:
99
+ t = tss.iloc[:, :6].set_axis(["chrom", "start", "end", "name", "score", "strand"], axis=1)
100
+ ok = (t["name"].map(strand) == t.strand) & (t["name"].map(chrom) == t.chrom)
101
+ for r in t[ok].itertuples():
102
+ links.setdefault(r.name, []).append(r.end)
103
+ if lost := (~ok & ~t["name"].isin(["", "."])).sum():
104
+ w.append(f"tss: {lost}/{len(t)} linked rows skipped: gene unknown or on another strand or chromosome")
105
+ if not links:
106
+ w.append("tss: no usable TSS (name must be the locus tag of the gene it starts), all units use start-codon windows")
107
+
108
+ rows = []
109
+ for u in base:
110
+ first = u["genes"][0]
111
+ u.update(chrom=chrom[first], strand=strand[first])
112
+ for pos in links.get(first, []):
113
+ rows.append({**u, "anchor": "TSS", "anchor_pos": pos, "up": tss_window[0], "down": tss_window[1]})
114
+ if first not in links and not no_gene_start:
115
+ lo, hi = internal_window if u["internal"] else start_window
116
+ rows.append({**u, "anchor": "start_codon", "anchor_pos": sc[first], "up": lo, "down": hi})
117
+ return pd.DataFrame(rows), w
118
+
119
+
120
+ def resolve(h, same_strand=SAME_STRAND, opp_strand=OPP_STRAND):
121
+ """Overlapping windows: every rule deciding which window a summit is assigned to lives here.
122
+ h: one row per summit p x unit row u whose window holds it (|distance| d, strand s); rules: see OVERLAP_RULES."""
123
+ if bad := {same_strand, opp_strand} - set(OVERLAP_RULES):
124
+ raise ValueError(f"overlap rule {', '.join(sorted(bad))}: choose from {', '.join(OVERLAP_RULES)}")
125
+ h = h.sort_values("d", kind="stable").drop_duplicates(["p", "uid"]) # 1. one anchor per unit: the nearest TSS
126
+ pick = {"closest": "min", "farthest": "max"}
127
+ if same_strand != "both": # 2. units on one strand: the nearest or the farthest
128
+ h = h[h.d == h.groupby(["p", "s"]).d.transform(pick[same_strand])]
129
+ if opp_strand != "both": # 3. the two strands, by the units kept in 2.
130
+ m = h.groupby(["p", "s"]).d.transform("min") # each strand's nearest kept anchor
131
+ h = h[m == m.groupby(h.p).transform(pick[opp_strand])]
132
+ return h.sort_values(["p", "u"]) # ties in 2. and 3. keep all tied units
133
+
134
+
135
+ def read_peaks(path, fmt):
136
+ """narrowPeak (.narrowPeak) or 1-bp summit BED (.bed) -> 10-column table, 1-based summit positions."""
137
+ if fmt == ".narrowPeak":
138
+ pk = read_table(path, 10, "narrowPeak: 10 columns, summit offset in column 10")
139
+ if (pk[9] < 0).any():
140
+ raise ValueError(f"{path}: {(pk[9] < 0).sum()} rows without summit (column 10 = -1)")
141
+ return pk, (pk[1] + pk[9] + 1).to_numpy(int)
142
+ pk = read_table(path, 3, "summit BED: 1-bp intervals at the summits")
143
+ if (pk[2] - pk[1] != 1).any():
144
+ raise ValueError(f"{path}: {(pk[2] - pk[1] != 1).sum()} rows are not 1-bp summit intervals")
145
+ return pk.reindex(columns=range(10), fill_value="."), pk[2].to_numpy(int)
146
+
147
+
148
+ def assign(units, g, pk, summits, same_strand=SAME_STRAND, opp_strand=OPP_STRAND):
149
+ """One TF: peak table and summits -> output table (one row per peak x target gene), peaks assigned, warnings.
150
+ same_strand, opp_strand: overlapping-window rules, see resolve()."""
151
+ if units.empty:
152
+ raise ValueError("no units to assign")
153
+ pos, up, down = units.anchor_pos.to_numpy(), units.up.to_numpy(), units.down.to_numpy()
154
+ sgn = np.where(units.strand == "+", 1, -1)
155
+ chrom_id = {c: i for i, c in enumerate(units.chrom.unique())}
156
+ u_chrom = units.chrom.map(chrom_id).to_numpy()
157
+ uid = pd.factorize(units.genes.str[0])[0] # a unit is identified by its first gene
158
+ c_all, w = pk[0].map(chrom_id).fillna(-1).to_numpy(int), []
159
+ if (c_all < 0).any():
160
+ w.append(f"{(c_all < 0).sum()}/{len(pk)} peaks on chromosomes not in the annotation: "
161
+ f"{sorted(set(pk[0][c_all < 0]))[:3]}")
162
+ out = []
163
+ for c0 in range(0, max(len(pk), 1), CHUNK):
164
+ s, c = summits[c0:c0 + CHUNK], c_all[c0:c0 + CHUNK]
165
+ D = (s[:, None] - pos) * sgn
166
+ pi, ui = np.nonzero((D >= up) & (D <= down) & (c[:, None] == u_chrom))
167
+ h = resolve(pd.DataFrame({"p": pi, "u": ui, "d": np.abs(D[pi, ui]), "s": sgn[ui], "uid": uid[ui]}),
168
+ same_strand, opp_strand)
169
+ pi, ui = h.p.to_numpy(), h.u.to_numpy()
170
+ u = units.iloc[ui]
171
+ out.append(pd.DataFrame({"i": c0 + pi, "gene": u.genes.to_numpy(), "anchor": u.anchor.to_numpy(),
172
+ "distance_to_anchor": D[pi, ui], "operon": u.operon.to_numpy()}))
173
+ r = pd.concat(out, ignore_index=True).explode("gene", ignore_index=True)
174
+ near = r.distance_to_anchor.abs().sort_values(kind="stable").index # one row per peak and gene: nearest anchor
175
+ r = r.loc[near].drop_duplicates(["i", "gene"]).sort_index()
176
+ p = pk.iloc[r.i.to_numpy()]
177
+ strand, chrom = dict(zip(g.locus, g.strand)), dict(zip(g.locus, g.chrom))
178
+ g_start, g_end = dict(zip(g.locus, g.start - 1)), dict(zip(g.locus, g.end)) # BED, 0-based start
179
+ bed = pd.DataFrame({
180
+ "chrom": p[0].to_numpy(), "start": summits[r.i] - 1, "end": summits[r.i], "target": r.gene.to_numpy(),
181
+ "peak_score": p[4].to_numpy(), "strand": r.gene.map(strand).to_numpy(), "signal": p[6].to_numpy(),
182
+ "pscore": p[7].to_numpy(), "qscore": p[8].to_numpy(), "target_chrom": r.gene.map(chrom).to_numpy(),
183
+ "target_start": r.gene.map(g_start).to_numpy(), "target_end": r.gene.map(g_end).to_numpy(),
184
+ "peak_id": p[3].to_numpy(), "operon": r.operon.to_numpy(), "anchor": r.anchor.to_numpy(),
185
+ "distance_to_anchor": r.distance_to_anchor.to_numpy()})
186
+ return bed.sort_values(["chrom", "start"], kind="stable"), r.i.nunique(), w
187
+
188
+
189
+ def main(argv=None):
190
+ win, lst = lambda x: tuple(int(v) for v in x.split(",")), lambda x: x.split(",")
191
+ ap = argparse.ArgumentParser(description=__doc__, epilog="Windows are up,down in bp (negative = upstream); "
192
+ "pass them as --tss-window=-200,100.")
193
+ ap.add_argument("--gff", required=True, help="GFF3 genome annotation")
194
+ ap.add_argument("--gff-feature", type=lst, default="gene,CDS", help="GFF feature types to read; a locus with several "
195
+ "rows spans them all")
196
+ ap.add_argument("--gff-attribute", default="locus_tag", help="GFF attribute holding the gene id")
197
+ ap.add_argument("--peaks", required=True, nargs="+", help="MACS3 narrowPeak file(s), one TF each, named by the file name")
198
+ ap.add_argument("--out", required=True, help="output folder; one <TF>_assigned_peaks.bed per peak file, one row per peak "
199
+ "x target gene: chrom, summit start, summit end, target, peak_score, target strand, signal, pscore, qscore, "
200
+ "target_chrom, target_start, target_end, peak_id, operon, anchor (TSS/start_codon), distance_to_anchor")
201
+ ap.add_argument("--operons", help="operon map: tab-separated, operon id and its genes (comma-separated), one row per operon")
202
+ ap.add_argument("--tss", help="TSS BED6 (TSS = end); name = locus tag of the gene the TSS starts, '.' = unlinked")
203
+ ap.add_argument("--predict-operons", action="store_true", help="predict operons from gene spacing instead of --operons; "
204
+ "writes predicted_operons.tsv and predicted_operon_pairs.tsv into --out")
205
+ ap.add_argument("--operon-cutoff", type=float, default=CUTOFF, help="pair probability that joins two genes (--predict-operons)")
206
+ ap.add_argument("--no-gene-start", action="store_true", help="no start-codon windows; units without a TSS are not assigned")
207
+ ap.add_argument("--no-internal", action="store_true", help="no internal units (operon starts only)")
208
+ ap.add_argument("--same-strand", choices=OVERLAP_RULES, default=SAME_STRAND, help="a summit in windows of several "
209
+ "units on one strand: assign the unit with the nearest anchor (closest), all of them (both) or the farthest")
210
+ ap.add_argument("--opp-strand", choices=OVERLAP_RULES, default=OPP_STRAND, help="a summit in windows on both strands "
211
+ "(between divergent genes): assign the strand with the nearest anchor (closest), both strands, or the other")
212
+ ap.add_argument("--tss-window", type=win, default="%d,%d" % TSS_WINDOW, help="window around a linked TSS")
213
+ ap.add_argument("--start-window", type=win, default="%d,%d" % START_WINDOW, help="operon-start window around the start codon")
214
+ ap.add_argument("--internal-window", type=win, default="%d,%d" % INTERNAL_WINDOW, help="internal window around the start codon")
215
+ a = ap.parse_args(argv)
216
+ warn = lambda m: print("warning:", m, file=sys.stderr)
217
+ try:
218
+ ext(a.gff, ".gff", ".gff3")
219
+ g, w = read_genome(a.gff, a.gff_feature, a.gff_attribute)
220
+ if a.predict_operons and a.operons:
221
+ raise ValueError("--predict-operons cannot be combined with --operons")
222
+ op = read_table(a.operons, 2, "operon file: operon id, locus tags", num=()) if a.operons and ext(a.operons, ".tsv") else None
223
+ if a.predict_operons:
224
+ op, pairs, w3 = predict_operons(g, a.operon_cutoff)
225
+ Path(a.out).mkdir(parents=True, exist_ok=True)
226
+ op.to_csv(Path(a.out) / "predicted_operons.tsv", sep="\t", header=False, index=False)
227
+ pairs.to_csv(Path(a.out) / "predicted_operon_pairs.tsv", sep="\t", index=False, float_format="%.6f")
228
+ w += w3
229
+ ts = read_table(a.tss, 6, "TSS file: BED6") if a.tss and ext(a.tss, ".bed") else None
230
+ units, w2 = build_units(g, op, ts, a.tss_window, a.start_window, a.internal_window, a.no_internal, a.no_gene_start)
231
+ for m in w + w2:
232
+ warn(m)
233
+ if units.empty:
234
+ raise ValueError("no units to assign")
235
+ tfs, fmts = [Path(p).stem for p in a.peaks], [ext(p, ".narrowPeak", ".bed") for p in a.peaks]
236
+ if len(set(tfs)) < len(tfs):
237
+ raise ValueError("peak file names must be distinct: they name the TFs and the output files")
238
+ Path(a.out).mkdir(parents=True, exist_ok=True)
239
+ for path, tf, fmt in zip(a.peaks, tfs, fmts): # one output file per peak file
240
+ pk, summits = read_peaks(path, fmt)
241
+ bed, n, w3 = assign(units, g, pk, summits, a.same_strand, a.opp_strand)
242
+ for m in w3:
243
+ warn(f"{tf}: {m}")
244
+ bed.rename(columns={"chrom": "#chrom"}).to_csv(Path(a.out) / f"{tf}_assigned_peaks.bed", sep="\t", index=False)
245
+ print(f"{tf}: {n}/{len(pk)} peaks assigned, {bed.target.nunique()} target genes")
246
+ except ValueError as e:
247
+ raise SystemExit(e)
248
+
249
+
250
+ if __name__ == "__main__":
251
+ main()
predict_operons.py ADDED
@@ -0,0 +1,123 @@
1
+ #!/usr/bin/env python3
2
+ """Predict operons from gene spacing, following UniOP (Su, Zhang and Söding, bioRxiv 2024, 10.1101/2024.11.11.623000):
3
+ the intergenic distances of same-strand gene pairs are compared with those of convergent and divergent pairs, which
4
+ cannot be in one operon. Intended to reproduce the UniOP script's probabilities; checked in tests/."""
5
+ import argparse
6
+ import sys
7
+ from pathlib import Path
8
+
9
+ import numpy as np
10
+ import pandas as pd
11
+
12
+ CUTOFF, N_NULL, SEED = 0.5, 10000, 0 # pair probability that joins two genes; null sample size and seed (as UniOP)
13
+ Q_RANGE = (0.01, 0.99) # the prior (fraction of same-strand pairs in operons) is clipped to this range
14
+ MAX_H, MIN_OPPOSITE = 0.2, 20 # bandwidth above which probabilities tend to the prior; opposite-strand pairs for the null
15
+
16
+
17
+ def gene_pairs(g):
18
+ """Consecutive genes along each chromosome (file order of chromosomes, then start):
19
+ chrom, a, b, gap = start of b - end of a + 1 (as UniOP), class same / convergent / divergent."""
20
+ g = g.assign(c=pd.factorize(g.chrom)[0]).sort_values(["c", "start"], kind="stable")
21
+ a, b = g.iloc[:-1].reset_index(drop=True), g.iloc[1:].reset_index(drop=True)
22
+ cls = np.where(a.strand == b.strand, "same", np.where(a.strand == "+", "convergent", "divergent"))
23
+ p = pd.DataFrame({"chrom": a.chrom, "a": a.locus, "b": b.locus, "gap": b.start - a.end + 1, "class": cls})
24
+ return p[a.chrom.to_numpy() == b.chrom.to_numpy()].reset_index(drop=True)
25
+
26
+
27
+ def prior(pairs):
28
+ """q = (S - O) / S: same-strand pairs S minus opposite-strand pairs O, assuming same-strand pairs that are not in an
29
+ operon are as frequent as opposite-strand ones. Returns the clipped value and the raw one."""
30
+ s = (pairs["class"] == "same").sum()
31
+ q = (2 * s - len(pairs)) / s if s else np.nan
32
+ return min(max(q, Q_RANGE[0]), Q_RANGE[1]), q
33
+
34
+
35
+ def kde(x, sample, h):
36
+ """Gaussian kernel density of sample, bandwidth h, at the points x (as scikit-learn's KernelDensity)."""
37
+ out = np.empty(len(x))
38
+ for i in range(0, len(x), 500): # bounds the x by sample matrix
39
+ d = (x[i:i + 500, None] - sample) / h
40
+ out[i:i + 500] = np.exp(-0.5 * d * d).sum(1) / (len(sample) * h * np.sqrt(2 * np.pi))
41
+ return out
42
+
43
+
44
+ def predict_operons(g, cutoff=CUTOFF, n_null=N_NULL, seed=SEED):
45
+ """Gene table from read_genome -> operon table (operon id, comma-separated locus tags 5'->3'), pair table
46
+ (gene_pairs columns plus prob, empty for opposite-strand pairs), list of warnings."""
47
+ w, pairs = [], gene_pairs(g)
48
+ cls, gap = pairs["class"].to_numpy(), pairs.gap.to_numpy()
49
+ same, conv, div = (gap[cls == c] for c in ("same", "convergent", "divergent"))
50
+ s, o = len(same), len(conv) + len(div)
51
+ pairs["prob"] = np.nan
52
+ if s == 0 or o == 0:
53
+ w.append(f"predict: {s} same-strand and {o} opposite-strand pairs; no operon can be predicted")
54
+ return pd.DataFrame(columns=["operon", "genes"]), pairs, w
55
+ if o < MIN_OPPOSITE:
56
+ w.append(f"predict: only {o} opposite-strand pairs to draw the null distances from")
57
+ q, raw = prior(pairs)
58
+ if q != raw:
59
+ w.append(f"predict: prior {raw:.2f} clipped to {q}")
60
+ np.random.seed(seed) # legacy generator and call order as UniOP, so the null sample is the same
61
+ null = [np.random.choice(x, n_null) for x in (conv, div) if len(x)]
62
+ if len(null) < 2:
63
+ w.append("predict: no convergent or no divergent pairs; the null distances come from the other class alone")
64
+ null = np.mean(null, axis=0) # mean of one convergent and one divergent distance
65
+ srt = np.sort(same)
66
+ rank = lambda x: (np.searchsorted(srt, x, side="right") + 0.5) / (s + 1) # fraction of same-strand gaps <= x
67
+ h = 2 * float(f"{100 / s:.2f}") # UniOP's bandwidth
68
+ if h == 0:
69
+ h = 0.01
70
+ w.append("predict: UniOP's bandwidth is 0 for this many pairs; 0.01 used")
71
+ if h > MAX_H:
72
+ w.append(f"predict: only {s} same-strand pairs; bandwidth {h:.2f} on the rank scale smooths the densities, "
73
+ f"probabilities tend to the prior {q:.2f}")
74
+ r = rank(same)
75
+ p = 1 - (1 - q) * kde(r, rank(null), h) / kde(r, r, h) # 1 - P(pair is not in an operon | gap)
76
+ p[p <= 0] = 0.01
77
+ order = np.argsort(same, kind="stable") # by gap: beyond the first minimum, p is held at that minimum (as UniOP)
78
+ ps = p[order]
79
+ ps[ps.argmin() + 1:] = ps.min()
80
+ p[order] = ps
81
+ pairs.loc[cls == "same", "prob"] = p
82
+
83
+ join = pairs.prob.to_numpy() >= cutoff
84
+ run = np.cumsum(~join | (pairs.chrom != pairs.chrom.shift()).to_numpy()) # consecutive joined pairs share a run
85
+ strand = dict(zip(g.locus, g.strand))
86
+ ops = []
87
+ for _, u in pairs[join].groupby(run[join], sort=False):
88
+ genes = u.a.tolist() + [u.b.iloc[-1]]
89
+ ops.append(",".join(genes if strand[genes[0]] == "+" else genes[::-1]))
90
+ return pd.DataFrame({"operon": [f"pred{i + 1}" for i in range(len(ops))], "genes": ops}), pairs, w
91
+
92
+
93
+ def main(argv=None):
94
+ from assign_targets import ext, read_genome
95
+ lst = lambda x: x.split(",")
96
+ ap = argparse.ArgumentParser(description=__doc__)
97
+ ap.add_argument("--gff", required=True, help="GFF3 genome annotation")
98
+ ap.add_argument("--gff-feature", type=lst, default="gene,CDS", help="GFF feature types to read")
99
+ ap.add_argument("--gff-attribute", default="locus_tag", help="GFF attribute holding the gene id")
100
+ ap.add_argument("--out", required=True, help="operon table (.tsv): operon id, comma-separated locus tags")
101
+ ap.add_argument("--pairs", help="pair table (.tsv): chrom, gene a, gene b, gap, class, probability")
102
+ ap.add_argument("--cutoff", type=float, default=CUTOFF, help="pair probability that joins two genes")
103
+ a = ap.parse_args(argv)
104
+ try:
105
+ ext(a.gff, ".gff", ".gff3")
106
+ if Path(a.out).suffix != ".tsv": # an output: may not exist yet
107
+ raise ValueError(f"{a.out}: file name must end in .tsv")
108
+ g, w = read_genome(a.gff, a.gff_feature, a.gff_attribute)
109
+ ops, pairs, w2 = predict_operons(g, a.cutoff)
110
+ for m in w + w2:
111
+ print("warning:", m, file=sys.stderr)
112
+ ops.to_csv(a.out, sep="\t", header=False, index=False)
113
+ if a.pairs:
114
+ pairs.to_csv(a.pairs, sep="\t", index=False, float_format="%.6f")
115
+ q, _ = prior(pairs)
116
+ print(f"{len(ops)} operons with {ops.genes.str.count(',').sum() + len(ops)} genes; "
117
+ f"{(pairs['class'] == 'same').sum()} same-strand pairs, prior {q:.2f}, cutoff {a.cutoff}")
118
+ except ValueError as e:
119
+ raise SystemExit(e)
120
+
121
+
122
+ if __name__ == "__main__":
123
+ main()
@@ -0,0 +1,266 @@
1
+ Metadata-Version: 2.4
2
+ Name: prokapeak
3
+ Version: 0.1.0
4
+ Summary: ProkaPeak: assign MACS3 peaks to target genes through TSS and gene-start windows
5
+ Author: Alexandre Dentler, Julian Trouillon
6
+ License-Expression: MIT
7
+ Project-URL: Repository, https://github.com/trouillon-lab/prokapeak
8
+ Keywords: ChIP-seq,DAP-seq,MACS3,transcription factor,operon,bacteria
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Operating System :: OS Independent
11
+ Classifier: Intended Audience :: Science/Research
12
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
13
+ Requires-Python: >=3.9
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ Requires-Dist: numpy>=1.21
17
+ Requires-Dist: pandas>=1.4
18
+ Provides-Extra: test
19
+ Requires-Dist: pytest; extra == "test"
20
+ Dynamic: license-file
21
+
22
+ <img align="left" width="170" src="https://raw.githubusercontent.com/trouillon-lab/prokapeak/v0.1.0/images/ProkaPeak_logo.png" />
23
+
24
+ ### A Python package to assign **Proka**ryotic **Peak**s to target genes.
25
+ #### ➡️ [_ProkaPeak web app_](https://prokapeak.trouillonlab.org/)
26
+ &nbsp;
27
+
28
+ &nbsp;
29
+ <br clear="left"/>
30
+
31
+ # ProkaPeak
32
+
33
+ ProkaPeak assigns transcription factor (TF) binding peaks from ChIP-seq, DAP-seq, or similar assays to the genes
34
+ they likely regulate. A peak is assigned to a gene when its summit lies in a window around that gene's start or
35
+ transcription start site (TSS), depending on available annotation.
36
+
37
+ ProkaPeak can run with only a peak list and gene annotation, but also supports
38
+ both TSS and operon information for more precise predictions. If no operon information is provided, ProkaPeak can predict operons first.
39
+ ProkaPeak uses default window sizes and peak assignment rules chosen to maximize target gene recovery, as defined based on experimental
40
+ binding sites. All parameters are optionally modifiable.
41
+
42
+ ### Web app
43
+ In addition to the Python package, we provide the [ProkaPeak web app](https://prokapeak.trouillonlab.org/), which allows for flexible peak assignment with visualisation of summary metrics. The web app allows to assign multiple peak files simultaneously, provides pre-made TSS and operon maps for selected bacterial species, and runs entirely locally in the user's browser without the need of data upload.
44
+
45
+ ## Installation
46
+
47
+ ```bash
48
+ pip install prokapeak
49
+ ```
50
+
51
+ Python ≥ 3.9; installs numpy ≥ 1.21, pandas ≥ 1.4 and the commands `prokapeak` and `prokapeak-operons`. The
52
+ development version installs with `pip install git+https://github.com/trouillon-lab/prokapeak`.
53
+
54
+ ## Usage
55
+
56
+ ```bash
57
+ prokapeak --gff genome.gff --peaks peaks/*.narrowPeak --operons operons.tsv --tss tss.bed --out out/
58
+ ```
59
+
60
+ Without installing, `python assign_targets.py` in a clone takes the same options (`python predict_operons.py` for
61
+ `prokapeak-operons`). Only `--gff`, `--peaks` and `--out` are required. `--predict-operons` replaces `--operons`
62
+ with operons predicted from gene spacing (see Predicted operons). Each peak file is processed in turn and gives one
63
+ output file.
64
+
65
+ `assign_targets` can also be imported: `read_genome` and `read_peaks` read the input files, `build_units` and `assign`
66
+ take the resulting tables; `main()` is the command line.
67
+
68
+ ## Example
69
+
70
+ `example/` in the [repository](https://github.com/trouillon-lab/prokapeak) holds an artificial genome to show the file
71
+ formats: 100 genes on two chromosomes (`chrom1`, `plasmid1`), 45 operons, 28 TSSs and peak files for four made-up
72
+ TFs. `example/expected/` is the output of
73
+
74
+ ```bash
75
+ cd example
76
+ prokapeak --gff genome.gff --operons operons.tsv --tss tss.bed --peaks peaks/*.narrowPeak --out out
77
+ ```
78
+
79
+ which should match `expected/` file for file. `expected/predicted_operons.tsv` and `predicted_operon_pairs.tsv` are
80
+ the operons predicted from the same genome by
81
+
82
+ ```bash
83
+ prokapeak-operons --gff genome.gff --out expected/predicted_operons.tsv --pairs expected/predicted_operon_pairs.tsv
84
+ ```
85
+
86
+ (25 operons instead of the 45 the example was built with: a genome of 100 genes is far too small for the method,
87
+ see Predicted operons).
88
+
89
+ ## Input files
90
+
91
+ All coordinates refer to the same genome; the chromosome name (column 1, or the GFF seqid) must be written
92
+ identically in every file. Genomes with several chromosomes or plasmids are supported. Files are plain text, named
93
+ by format: `.gff` or `.gff3`, `.tsv`, `.bed`, `.narrowPeak`. Lines starting with `#` are skipped and extra columns are
94
+ ignored; a missing file or a file of the wrong shape (too few columns, header lines, non-integer coordinates, missing
95
+ summits) stops the run with a message naming it.
96
+ Rows that cannot be matched to the annotation (loci with rows on several chromosomes or strands, peaks on unknown
97
+ chromosomes, operon genes not in the GFF, operons with genes on several chromosomes or strands, linked
98
+ TSSs whose gene is not found) are counted in warnings on stderr.
99
+
100
+ ### `--gff` genome annotation (required)
101
+
102
+ GFF3. Rows of the listed feature types are read (`--gff-feature`, default `gene,CDS`); a locus with several rows,
103
+ of one type or of several, spans all of them. Every row needs the attribute holding the gene identifier
104
+ (`--gff-attribute`, default `locus_tag`), which is used in all other files and in the output.
105
+
106
+ | column | used |
107
+ |---|---|
108
+ | 1 seqid | chromosome |
109
+ | 3 type | one of `--gff-feature` (default `gene,CDS`) |
110
+ | 4 start, 5 end | 1-based, inclusive |
111
+ | 7 strand | `+` or `-`; the start codon is `start` on `+` and `end` on `-` |
112
+ | 9 attributes | `<--gff-attribute>=...` |
113
+
114
+ ### `--peaks` peak files (required, one or more)
115
+
116
+ One file per TF, either MACS3 narrowPeak (`.narrowPeak`, 10 tab-separated columns, no header) or a BED file of
117
+ summits (`.bed`, at least 3 columns, every row a 1-bp interval at the summit, as in MACS3 `NAME_summits.bed`). Both
118
+ give the same assignments; a summit BED has no signal, p- or q-value, so those output columns are `.` (see Output).
119
+
120
+ | column | content |
121
+ |---|---|
122
+ | 1 chrom | chromosome |
123
+ | 2 start | 0-based peak start |
124
+ | 3 end | peak end |
125
+ | 4 name | peak id (copied to the output) |
126
+ | 5 score | copied to the output |
127
+ | 6 strand | ignored |
128
+ | 7 signal | fold enrichment, copied to the output |
129
+ | 8 pValue, 9 qValue | −log10, copied to the output |
130
+ | 10 peak | summit offset from column 2 |
131
+
132
+ The summit is column 2 + column 10 (0-based), or column 3 of a summit BED. The TF name is the file name without
133
+ extension, so file names must be distinct. An empty peak file gives an output file with only the header line.
134
+
135
+ ### `--operons` operon map (optional)
136
+
137
+ Tab-separated, no header, two columns: operon id, locus tags of its genes separated by commas. One row per operon;
138
+ rows with the same operon id are merged, so one gene per row works too. The order of the genes in the list does
139
+ not matter: the genes of an operon are ordered 5'→3' from their GFF coordinates. Genes not listed are single-gene
140
+ units. Listed genes that are not in the GFF, and operons whose genes lie on several chromosomes or strands, are
141
+ skipped with a warning.
142
+
143
+ ```
144
+ op1 b0002,b0003,b0004
145
+ op2 b0005
146
+ ```
147
+
148
+ ### `--tss` TSS map (optional)
149
+
150
+ BED6, tab-separated, no header, one row per TSS.
151
+
152
+ | column | content |
153
+ |---|---|
154
+ | 1 chrom | chromosome |
155
+ | 2 start, 3 end | the TSS as a 1-bp interval (0-based start; TSS position = end, 1-based) |
156
+ | 4 name | locus tag of the gene the TSS starts; `.` = not linked to a gene |
157
+ | 5 score | ignored |
158
+ | 6 strand | `+` or `-` |
159
+
160
+ A TSS is an anchor for the unit its gene starts: the operon or internal unit beginning with that gene, or the gene
161
+ itself. TSSs that are unlinked, or whose gene is not in the GFF or lies on another strand or chromosome, are skipped.
162
+
163
+ Example: `NC_000913.3 147 148 b0001 0 +`
164
+
165
+ ## Assignment
166
+
167
+ **Units.** With `--operons`, every operon is a unit (operon start), and every gene of an operon other than the
168
+ first starts an internal unit: that gene and the genes downstream of it. Genes in no operon are single-gene
169
+ units. Without `--operons`, every gene is a unit.
170
+
171
+ **Windows** (bp, along the unit's strand, negative = upstream; summit position minus anchor position):
172
+
173
+ | unit | anchor | default | option |
174
+ |---|---|---|---|
175
+ | any unit with a linked TSS | the TSS | −200 to +100 | `--tss-window` |
176
+ | operon start or single gene without a TSS | start codon of the first gene | −400 to +25 | `--start-window` |
177
+ | internal start without a TSS | start codon of that gene | −250 to +50 | `--internal-window` |
178
+
179
+ Pass windows with `=`, as in `--tss-window=-150,100`, so the leading minus is not read as an option.
180
+
181
+ **Overlapping windows** (function `resolve` in the script).
182
+ 1. A unit with several TSSs is assigned once, through the TSS nearest the summit.
183
+ 2. Of several units on one strand, only the one with the nearest anchor is assigned (`--same-strand`).
184
+ 3. A summit in windows on both strands (between divergent genes) is assigned only on the strand with the nearest
185
+ anchor (`--opp-strand`), compared over the units kept by rule 2.
186
+ Units or strands tied in distance are all kept.
187
+ 4. An assigned unit assigns all its genes; a gene assigned through several units is listed once, through the
188
+ nearest anchor.
189
+
190
+ ## Predicted operons
191
+
192
+ Without an operon map, operons can be predicted from gene spacing using the method from UniOP (Su, Zhang and
193
+ Söding, bioRxiv 2024, doi:10.1101/2024.11.11.623000). Pairs at or above the cutoff (default 0.5) are joined; operons
194
+ of two or more genes are kept, in the operon map format.
195
+
196
+ The simplest is to predict them as part of the run, with `--predict-operons` in place of `--operons`:
197
+
198
+ ```bash
199
+ prokapeak --gff genome.gff --peaks peaks/*.narrowPeak --predict-operons --out out/
200
+ ```
201
+
202
+ `predicted_operons.tsv` and `predicted_operon_pairs.tsv` are written into `--out`; `--operon-cutoff` sets the cutoff.
203
+
204
+ Alternatively, `prokapeak-operons` predicts them on their own, to inspect them or pass them later to `--operons`:
205
+
206
+ ```bash
207
+ prokapeak-operons --gff genome.gff --out operons.tsv [--pairs pairs.tsv] [--cutoff 0.5]
208
+ ```
209
+
210
+ `--gff-feature` and `--gff-attribute` work as in `prokapeak`. The pair table has one row per pair of consecutive genes:
211
+
212
+ | column | content |
213
+ |---|---|
214
+ | chrom | chromosome |
215
+ | a, b | locus tags, in genome order |
216
+ | gap | start of b − end of a + 1 |
217
+ | class | `same`, `convergent` or `divergent` |
218
+ | prob | probability that a and b are in one operon; empty for opposite-strand pairs |
219
+
220
+ The probabilities equal those of the UniOP script (`tests/`), except that pairs are formed within a chromosome
221
+ only, the prior is clipped to 0.01–0.99, and a genome without convergent or without divergent pairs uses the
222
+ other class alone. The method needs a genome-sized gene set: below about 1,000 same-strand pairs the gaps stop
223
+ separating the pairs and nearly all same-strand neighbours are joined.
224
+
225
+ ## Options
226
+
227
+ | option | effect |
228
+ |---|---|
229
+ | `--gff-feature` | GFF feature types to read, comma-separated (default `gene,CDS`); a locus spans all its rows |
230
+ | `--gff-attribute` | GFF attribute holding the gene id (default `locus_tag`) |
231
+ | `--predict-operons` | operons predicted from gene spacing instead of `--operons` |
232
+ | `--operon-cutoff` | pair probability that joins two genes for `--predict-operons` (default 0.5) |
233
+ | `--no-gene-start` | no start-codon windows; units without a TSS are not assigned |
234
+ | `--no-internal` | operon starts only, no internal units |
235
+ | `--same-strand closest\|both\|farthest` | a summit in windows of several units on one strand: assign the unit with the nearest anchor (default), all of them, or the one with the farthest anchor |
236
+ | `--opp-strand closest\|both\|farthest` | a summit in windows on both strands: assign the strand with the nearest anchor (default), both strands, or only the other strand |
237
+ | `--tss-window`, `--start-window`, `--internal-window` | window `up,down` in bp |
238
+
239
+ ## Output
240
+
241
+ One `<TF>_assigned_peaks.bed` per peak file in `--out`: tab-separated, a `#` header line naming the columns, then
242
+ one row per peak and assigned gene, sorted by position. A peak assigned to an operon of four genes gives four rows;
243
+ a peak in no window is not listed. With `--predict-operons`, `--out` also holds `predicted_operons.tsv` and
244
+ `predicted_operon_pairs.tsv` (see Predicted operons).
245
+
246
+ | column | content |
247
+ |---|---|
248
+ | 1 chrom | chromosome of the peak |
249
+ | 2 start, 3 end | summit as a 1-bp interval (0-based start) |
250
+ | 4 target | locus tag of the assigned gene |
251
+ | 5 peak_score | column 5 of the peak file; `.` for a 3-column summit BED |
252
+ | 6 strand | strand of the target gene |
253
+ | 7 signal, 8 pscore, 9 qscore | narrowPeak columns 7–9; `.` for a summit BED |
254
+ | 10 target_chrom | chromosome of the target gene |
255
+ | 11 target_start, 12 target_end | target gene coordinates (0-based start) |
256
+ | 13 peak_id | column 4 of the peak file; `.` for a 3-column summit BED |
257
+ | 14 operon | operon id, `.` for a gene in no operon |
258
+ | 15 anchor | `TSS` or `start_codon` |
259
+ | 16 distance_to_anchor | summit minus anchor, along the target's strand (negative = upstream) |
260
+
261
+ `prokapeak` prints one line per TF: peaks assigned and number of target genes.
262
+
263
+ ## License
264
+
265
+ ProkaPeak is released under the [MIT License](https://github.com/trouillon-lab/prokapeak/blob/main/LICENSE),
266
+ copyright (c) 2026 Trouillon lab.
@@ -0,0 +1,8 @@
1
+ assign_targets.py,sha256=7Gh_Y5iuIlOM5Spy1Y0xlZKV1sJB_XwN1X3noXCp9X0,16004
2
+ predict_operons.py,sha256=MyWxaatjSwL6UKH3tMwvyHSyMaAj5wUfn41tIXkJzSE,6599
3
+ prokapeak-0.1.0.dist-info/licenses/LICENSE,sha256=Bc5gU45CIpCsuwzDA8wioVKwK7y5_GUoVJGPbovJlao,1070
4
+ prokapeak-0.1.0.dist-info/METADATA,sha256=U3BZ_edsitpNKrvr4FqXurL1bbxGn5pen7jfcVJ1DwE,13109
5
+ prokapeak-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
6
+ prokapeak-0.1.0.dist-info/entry_points.txt,sha256=Qs1UD-KP7jfUpbm4SKClpLj5SSWUgHYcaONITV1l3pU,91
7
+ prokapeak-0.1.0.dist-info/top_level.txt,sha256=nwugijhMpC1o-MrTOfOZh4CJSe73WrijL5qKzhtHngM,31
8
+ prokapeak-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ prokapeak = assign_targets:main
3
+ prokapeak-operons = predict_operons:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Trouillon lab
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,2 @@
1
+ assign_targets
2
+ predict_operons