MACS3.Signal.CallPeakUnit module

CallerFromAlignments uses the shared invocation execution policy. Process phases also require at least 262,144 stored treatment and distinct control locations across two nonempty chromosomes. FRAG counts do not multiply the stored-location cost. This minimum is an internal startup heuristic.

Chromosomes empty in both inputs are ignored; an empty comparison returns an empty peak collection. One-sided empty chromosomes retain zero treatment or background control coverage. Large chromosomes remain individual tasks and small ones are batched, with at most 32 tasks per eligible worker. Results retain serial chromosome and peak order. See CPU budgets and process backends for resource limits and empty output artifacts.

Compute MACS3 peak-calling scores and helper statistics.

This code is free software; you can redistribute it and/or modify it under the terms of the BSD License (see the file LICENSE included with the distribution).

class MACS3.Signal.CallPeakUnit.CallerFromAlignments

Bases: object

Compute pileups, scores, and peaks from FWTrack/PETrack alignments.

Scoring caches belong to this instance and live until it is released. PeakExecution and PileupStorage own its scheduling and temporary files; neither helper imports scoring types or retains a reference to this caller. Independent instances may overlap; do not call one instance concurrently. Forked pools are serialized from creation through shutdown so one pool cannot inherit another pool’s descriptors. Pools finish before an operation returns, including on failure.

treat: Treatment track (FWTrack or PETrackI/PETrackII).

ctrl: Control track (FWTrack or PETrackI/PETrackII).

d: Fragment extension size for treatment (unused in PE mode).

ctrl_d_s: Fragment extension size for control.

treat_scaling_factor: Scaling factor for treatment.

ctrl_scaling_factor_s: Scaling factors for control.

lambda_bg: Minimum local bias to fill missing values.

chromosomes: Common chromosome names in treat/control.

pseudocount: Pseudocount used for logLR/FE/logFE calculations.

bedGraph_filename_prefix: Prefix for pileup/lambda bedGraph outputs.

end_shift: Shift applied to read ends before extension.

trackline: Whether to emit UCSC track lines in bedGraph outputs.

save_bedGraph: Whether to save pileup/lambda bedGraph files.

save_SPMR: Whether to save pileup normalized per million reads.

no_lambda_flag: Whether to ignore local lambda (use global only).

PE_mode: Whether treatment is paired-end.

call_broadpeaks(scoring_function_symbols, lvl1_cutoff_s, lvl2_cutoff_s, min_length=200, lvl1_max_gap=50, lvl2_max_gap=400, cutoff_analysis=False)

This function try to find enriched regions within which, scores are continuously higher than a given cutoff for level 1, and link them using the gap above level 2 cutoff with a maximum length of lvl2_max_gap.

Parameters:

scoring_function_symbols (list) – Symbols for score functions. Use 'p' (pscore), 'q' (qscore), 'f' (fold change), or 's' (subtraction). Example: ['p', 'q'].
lvl1_cutoff_s (list) – Cutoffs for highly enriched regions.
lvl2_cutoff_s (list) – Cutoffs for linkage regions.
min_length (cython.int) – Minimum peak length.
lvl1_max_gap (cython.int) – Maximum gap to merge nearby peaks.
lvl2_max_gap (cython.int) – Maximum length of linkage regions.
cutoff_analysis (bool) – Whether to compute cutoff-vs-peak metrics.

Returns:

(PeakIO, BroadPeakIO) for level-1 peaks and broad regions.

Return type:

tuple

Examples

lvl1, broad = caller.call_broadpeaks(['p'], [5.0], [2.0])

call_peaks(scoring_function_symbols, score_cutoff_s, min_length=200, max_gap=50, call_summits=False, cutoff_analysis=False)

Call narrow peaks for all chromosomes.

Parameters:

scoring_function_symbols (list) – Symbols for score functions. Use 'p' (pscore), 'q' (qscore), 'f' (fold change), or 's' (subtraction). Example: ['p', 'q'].
score_cutoff_s (list) – Cutoff values corresponding to scoring_function_symbols.
min_length (cython.int) – Minimum peak length.
max_gap (cython.int) – Maximum gap of insignificant regions within a peak.
call_summits (bool) – Whether to call sub-peaks (summits).
cutoff_analysis (bool) – Whether to compute cutoff-vs-peak metrics.

Returns:

Collection of called peaks.

Return type:

PeakIO

Examples

peaks = caller.call_peaks(['p'], [5.0], min_length=200)

destroy()

Remove owned pileup files after workers join; safe to call again.

A subsequent peak call allocates fresh storage. Scoring caches remain caller-owned and are reset separately when an operation fails.

enable_trackline(): Enable UCSC track line output when writing bedGraphs.

execution_policy

set_pseudocount(pseudocount): Update the pseudocount used in scoring.

class MACS3.Signal.CallPeakUnit.PScoreCache

Bases: object

Open-addressing hash table of -log10 Poisson upper-tail p-scores keyed by (observed, lambda), with linear probing.

Each p-score is computed once by poisson_cdf and stored as float32, exactly as the dict of packed (int, float32 bits) keys it replaces does.

class MACS3.Signal.CallPeakUnit.QScoreTable

Bases: object

The p-score to q-score table of CallerFromAlignments: an open-addressing hash table, with linear probing, from float32 p-score to float32 q-score.

It holds what the dict pqtable given the same puts would hold: a later put of an equal key overwrites the value, so get returns the float32 value the dict returns, and raises the same KeyError for a p-score the dict does not hold, without a Python object per lookup.

class MACS3.Signal.CallPeakUnit.SlotAboveCutoff

Bases: object

Whether the q-score of the p-score in each slot of caller.pscore_cache is above threshold, looked up in qtable the first time this process meets the slot: 0 for a slot not looked up yet, 1 for a q-score at or below the threshold (or a NaN), 2 for one above it. Like SlotQScores, the flags are for the slots of a cache of capacity mask + 1.

class MACS3.Signal.CallPeakUnit.SlotQScores

Bases: object

The q-score of the p-score in each slot of pscore_cache, looked up in qtable the first time this process meets the slot, so that the q-score of a position takes one hash lookup instead of two.

An entry holds the complemented bits of the q-score, or 0 for a slot not looked up yet; a q-score whose bits are 0xFFFFFFFF (a NaN) is looked up again each time. The entries are for the slots of a cache of capacity mask + 1; a cache that grows has moved its slots, and needs new entries. A slot’s p-score never changes once it is used, and a QScoreTable is filled before any q-score is read from it.

MACS3.Signal.CallPeakUnit.call_peaks_worker(task)

Worker side of CallerFromAlignments._call_peaks_in_workers.

Runs in a forked process. task is (chromosome indices, scoring function symbols, cutoffs, min_length, max_gap, call_summits). For each chromosome, return (name, file holding its pileup or None, its peaks).

Return type:: list

MACS3.Signal.CallPeakUnit.float32_threshold(cutoff)

The float32 t for which numpy’s a > cutoff, a a float32 array, is a > t in C float arithmetic for every element, or None when there is none to be found here (a NaN or infinite cutoff, or one beyond float32’s range).

Whether numpy compares in float32 or in float64 depends on the version and on the type of cutoff, so numpy itself is asked: the comparison is monotone in the element, and its threshold lies between t and the next float32 up exactly when numpy finds t not above cutoff and that next float32 above it.

MACS3.Signal.CallPeakUnit.initialize_peak_worker(caller): Bind a forked worker to this pool’s caller.

MACS3.Signal.CallPeakUnit.pscore_stat_worker(chroms)

Worker side of CallerFromAlignments._pscore_stat_in_workers.

Runs in a forked process. Adds the chromosomes whose indices are in chroms to this process’s p-score histogram, in increasing index order, without computing p-scores, and returns [(name, file holding its pileup or None)] for them with the histogram’s key, first-segment and length arrays. Taking the histogram resets it for the worker’s next task.

Return type:: tuple

MACS3.Signal.CallPeakUnit.score_pending_chunks(cache, observed, lams, values, pscores, firsts, lengths, chunk, state): Thread side of PScoreCache.score_pending: take the next chunk pending keys until none is left, and decode them, compute their p-scores and store them, without the GIL. pscores, firsts and lengths are the histogram arrays, or all None. The first exception raised stops every thread at its next chunk and is kept in state[2].