consenrich 0.6.3b1__cp311-cp311-macosx_11_0_arm64.whl → 0.7.0b1__cp311-cp311-macosx_11_0_arm64.whl

consenrich/consenrich.py

@@ -39,11 +39,11 @@ def _listOrEmpty(list_):
 
 
 def _getMinR(cfg, numBams: int) -> float:
+    fallBackMinR: float = 1.0
     try:
         raw = cfg.get("observationParams.minR", None)
-        return float(raw) if raw is not None else (1 / numBams) + 1e-4
+        return float(raw) if raw is not None else fallBackMinR
     except (TypeError, ValueError, KeyError):
-        fallBackMinR: float = 1.0e-2
         logger.warning(
             f"Invalid or missing 'observationParams.minR' in config. Using `{fallBackMinR}`."
         )
@@ -174,7 +174,21 @@ def getInputArgs(config_path: str) -> core.inputParams:
         for i, bamFile in enumerate(bamFilesControl):
             misc_util.checkBamFile(bamFile)
 
-    return core.inputParams(bamFiles=bamFiles, bamFilesControl=bamFilesControl)
+    # if we've made it here, we can check pairedEnd
+    pairedEndList = misc_util.bamsArePairedEnd(bamFiles)
+    _isPairedEnd: Optional[bool] = config.get("inputParams.pairedEnd", None)
+    if _isPairedEnd is None:
+        # only set auto if not provided in config
+        _isPairedEnd = all(pairedEndList)
+        if _isPairedEnd:
+            logger.info(
+                "Paired-end BAM files detected"
+            )
+        else:
+            logger.info(
+                "One or more single-end BAM files detected"
+            )
+    return core.inputParams(bamFiles=bamFiles, bamFilesControl=bamFilesControl, pairedEnd=_isPairedEnd)
 
 
 def getGenomeArgs(config_path: str) -> core.genomeParams:
@@ -294,6 +308,7 @@ def readConfig(config_path: str) -> Dict[str, Any]:
     genomeParams = getGenomeArgs(config_path)
     countingParams = getCountingArgs(config_path)
     minR_default = _getMinR(config, len(inputParams.bamFiles))
+    minQ_default = (minR_default / (len(inputParams.bamFiles))) + 0.10 # protect condition number
     matchingExcludeRegionsBedFile_default: Optional[str] = (
         genomeParams.blacklistFile
     )
@@ -304,12 +319,12 @@ def readConfig(config_path: str) -> Dict[str, Any]:
         "countingArgs": countingParams,
         "processArgs": core.processParams(
             deltaF=config.get("processParams.deltaF", 0.5),
-            minQ=config.get("processParams.minQ", 0.25),
+            minQ=config.get("processParams.minQ", minQ_default),
             maxQ=config.get("processParams.maxQ", 500.0),
             offDiagQ=config.get("processParams.offDiagQ", 0.0),
             dStatAlpha=config.get("processParams.dStatAlpha", 3.0),
             dStatd=config.get("processParams.dStatd", 10.0),
-            dStatPC=config.get("processParams.dStatPC", 2.0),
+            dStatPC=config.get("processParams.dStatPC", 1.0),
             scaleResidualsByP11=config.get(
                 "processParams.scaleResidualsByP11", False
             ),
@@ -351,8 +366,9 @@ def readConfig(config_path: str) -> Dict[str, Any]:
             offsetStr=config.get("samParams.offsetStr", "0,0"),
             extendBP=config.get("samParams.extendBP", []),
             maxInsertSize=config.get("samParams.maxInsertSize", 1000),
-            pairedEndMode=config.get("samParams.pairedEndMode", 0),
-            inferFragmentLength=config.get("samParams.inferFragmentLength", 0),
+            pairedEndMode=config.get("samParams.pairedEndMode", 1 if inputParams.pairedEnd is not None and int(inputParams.pairedEnd) > 0 else 0),
+            inferFragmentLength=config.get("samParams.inferFragmentLength", 1 if inputParams.pairedEnd is not None and int(inputParams.pairedEnd) == 0 else 0),
+            countEndsOnly=config.get("samParams.countEndsOnly", False),
         ),
         "detrendArgs": core.detrendParams(
             detrendWindowLengthBP=config.get(
@@ -380,7 +396,7 @@ def readConfig(config_path: str) -> Dict[str, Any]:
                 "matchingParams.minSignalAtMaxima", "q:0.75"
             ),
             merge=config.get("matchingParams.merge", True),
-            mergeGapBP=config.get("matchingParams.mergeGapBP", 50),
+            mergeGapBP=config.get("matchingParams.mergeGapBP", None),
             useScalingFunction=config.get(
                 "matchingParams.useScalingFunction", True
             ),
@@ -492,7 +508,7 @@ def main():
         "--match-no-merge", action="store_true", dest="matchNoMerge"
     )
     parser.add_argument(
-        "--match-merge-gap", type=int, default=50, dest="matchMergeGapBP"
+        "--match-merge-gap", type=int, default=None, dest="matchMergeGapBP"
     )
     parser.add_argument(
         "--match-use-wavelet", action="store_true", dest="matchUseWavelet"
@@ -748,6 +764,7 @@ def main():
                     inferFragmentLength=samArgs.inferFragmentLength,
                     applyAsinh=countingArgs.applyAsinh,
                     applyLog=countingArgs.applyLog,
+                    countEndsOnly=samArgs.countEndsOnly
                 )
                 if countingArgs.rescaleToTreatmentCoverage:
                     finalSF = max(1.0, initialTreatmentScaleFactors[j_])
@@ -768,12 +785,13 @@ def main():
                 samArgs.samThreads,
                 samArgs.samFlagExclude,
                 offsetStr=samArgs.offsetStr,
-                extendBP=samArgs.extendBP,
+                extendBP=extendBP_,
                 maxInsertSize=samArgs.maxInsertSize,
                 pairedEndMode=samArgs.pairedEndMode,
                 inferFragmentLength=samArgs.inferFragmentLength,
                 applyAsinh=countingArgs.applyAsinh,
                 applyLog=countingArgs.applyLog,
+                countEndsOnly=samArgs.countEndsOnly
             )
         sparseMap = None
         if genomeArgs.sparseBedFile and not observationArgs.useALV:

consenrich/core.py

@@ -194,6 +194,8 @@ class samParams(NamedTuple):
        extend reads from 5'. Ignored if `pairedEndMode > 0` or `extendBP` set. This parameter is particularly
        important when targeting broader marks (e.g., ChIP-seq H3K27me3).
     :type inferFragmentLength: int
+    :param countEndsOnly: If True, only the 5' ends of reads are counted. Overrides `inferFragmentLength` and `pairedEndMode`.
+    :type countEndsOnly: Optional[bool]
 
     .. tip::
 
@@ -210,6 +212,7 @@ class samParams(NamedTuple):
     maxInsertSize: Optional[int] = 1000
     pairedEndMode: Optional[int] = 0
     inferFragmentLength: Optional[int] = 0
+    countEndsOnly: Optional[bool] = False
 
 
 class detrendParams(NamedTuple):
@@ -251,6 +254,7 @@ class inputParams(NamedTuple):
 
     bamFiles: List[str]
     bamFilesControl: Optional[List[str]]
+    pairedEnd: Optional[bool]
 
 
 class genomeParams(NamedTuple):
@@ -309,9 +313,9 @@ class countingParams(NamedTuple):
 
 
 class matchingParams(NamedTuple):
-    r"""Parameters related to the matching algorithm packaged with this software.
+    r"""Parameters related to the matching algorithm.
 
-    See :ref:`matching` for details.
+    See :ref:`matching` for an overview of the approach.
 
     :param templateNames: A list of str values -- wavelet bases used for matching, e.g., `[haar, db2, sym4]`
     :type templateNames: List[str]
@@ -327,15 +331,13 @@ class matchingParams(NamedTuple):
     :type alpha: float
     :param minMatchLengthBP: Within a window of `minMatchLengthBP` length (bp), relative maxima in
         the signal-template convolution must be greater in value than others to qualify as matches.
-        *Set to a negative value to disable this filter*.
     :type minMatchLengthBP: int
-    :param minSignalAtMaxima: Secondary significance threshold coupled with `alpha`. Require the *signal value*
+    :param minSignalAtMaxima: Secondary significance threshold coupled with `alpha`. Requires the *signal value*
         at relative maxima in the response sequence to be greater than this threshold. Comparisons are made in log-scale.
         If a `float` value is provided, the minimum signal value must be greater than this (absolute) value. *Set to a
         negative value to disable the threshold*.
-        If a `str` value is provided, looks for 'q:quantileValue', e.g., 'q:0.75'. The
+        If a `str` value is provided, looks for 'q:quantileValue', e.g., 'q:0.90'. The
         threshold is then set to the corresponding quantile of the non-zero signal estimates.
-        Defaults to str value 'q:0.75' --- the 75th percentile of signal values.
     :type minSignalAtMaxima: Optional[str | float]
     :param useScalingFunction: If True, use (only) the scaling function to build the matching template.
         If False, use (only) the wavelet function.
@@ -343,20 +345,21 @@ class matchingParams(NamedTuple):
     :param excludeRegionsBedFile: A BED file with regions to exclude from matching
     :type excludeRegionsBedFile: Optional[str]
 
-    :seealso: :class:`consenrich.core.matchingParams`, :func:`cconsenrich.csampleBlockStats`, :ref:`matching`
+    :seealso: :func:`cconsenrich.csampleBlockStats`, :ref:`matching`
+
     """
 
     templateNames: List[str]
     cascadeLevels: List[int]
     iters: int
     alpha: float
+    useScalingFunction: Optional[bool]
     minMatchLengthBP: Optional[int]
     maxNumMatches: Optional[int]
-    minSignalAtMaxima: Optional[str | float] = "q:0.75"
-    merge: bool = False
-    mergeGapBP: int = 25
-    useScalingFunction: bool = True
-    excludeRegionsBedFile: Optional[str] = None
+    minSignalAtMaxima: Optional[str | float]
+    merge: Optional[bool]
+    mergeGapBP: Optional[int]
+    excludeRegionsBedFile: Optional[str]
 
 
 def _numIntervals(start: int, end: int, step: int) -> int:
@@ -518,6 +521,7 @@ def readBamSegments(
     maxInsertSize: Optional[int] = 1000,
     pairedEndMode: Optional[int] = 0,
     inferFragmentLength: Optional[int] = 0,
+    countEndsOnly: Optional[bool] = False,
 ) -> npt.NDArray[np.float32]:
     r"""Calculate tracks of read counts (or a function thereof) for each BAM file.
 
@@ -553,6 +557,9 @@ def readBamSegments(
     :type pairedEndMode: int
     :param inferFragmentLength: See :class:`samParams`.
     :type inferFragmentLength: int
+    :param countEndsOnly: If True, only the 5' ends of reads are counted. This overrides `inferFragmentLength` and `pairedEndMode`.
+    :type countEndsOnly: Optional[bool]
+
     """
 
     if len(bamFiles) == 0:
@@ -567,6 +574,12 @@ def readBamSegments(
     offsetStr = ((str(offsetStr) or "0,0").replace(" ", "")).split(",")
     numIntervals = ((end - start) + stepSize - 1) // stepSize
     counts = np.empty((len(bamFiles), numIntervals), dtype=np.float32)
+
+    if isinstance(countEndsOnly, bool) and countEndsOnly:
+        # note: setting this option ignores inferFragmentLength, pairedEndMode
+        inferFragmentLength = 0
+        pairedEndMode = 0
+
     for j, bam in enumerate(bamFiles):
         logger.info(f"Reading {chromosome}: {bam}")
         arr = cconsenrich.creadBamSegment(

consenrich/detrorm.py

@@ -39,7 +39,7 @@ def getScaleFactor1x(
     :type bamFile: str
     :param effectiveGenomeSize: Effective genome size in base pairs. See :func:`consenrich.constants.getEffectiveGenomeSize`.
     :type effectiveGenomeSize: int
-    :param readLength: Read length (base pairs). See :func:`consenrich.core.getReadLength`.
+    :param readLength: read length or fragment length
     :type readLength: int
     :param excludeChroms: List of chromosomes to exclude from the analysis.
     :type excludeChroms: List[str]
@@ -125,9 +125,9 @@ def getPairScaleFactors(
     :type effectiveGenomeSizeA: int
     :param effectiveGenomeSizeB: Effective genome size for the second BAM file.
     :type effectiveGenomeSizeB: int
-    :param readLengthA: Read length for the first BAM file.
+    :param readLengthA: read length or fragment length for the first BAM file.
     :type readLengthA: int
-    :param readLengthB: Read length for the second BAM file.
+    :param readLengthB: read length or fragment length for the second BAM file.
     :type readLengthB: int
     :param excludeChroms: List of chromosomes to exclude from the analysis.
     :type excludeChroms: List[str]
@@ -167,9 +167,18 @@ def getPairScaleFactors(
     else:
         scaleFactorA *= coverageB / coverageA
         scaleFactorB = 1.0
+
     logger.info(
         f"Final scale factors: {bamFileA}: {scaleFactorA}, {bamFileB}: {scaleFactorB}"
     )
+
+    ratio = max(scaleFactorA, scaleFactorB) / min(scaleFactorA, scaleFactorB)
+    if ratio > 5.0:
+        logger.warning(
+            f"Scale factors differ > 5x....\n"
+            f"\n\tAre effective genome sizes {effectiveGenomeSizeA} and {effectiveGenomeSizeB} correct?"
+            f"\n\tAre read/fragment lengths {readLengthA},{readLengthB} correct?"
+        )
     return scaleFactorA, scaleFactorB
 
 

consenrich/matching.py

@@ -53,7 +53,7 @@ def matchExistingBedGraph(
     recenterAtPointSource: bool = True,
     useScalingFunction: bool = True,
     excludeRegionsBedFile: Optional[str] = None,
-    mergeGapBP: int = 50,
+    mergeGapBP: Optional[int] = None,
     merge: bool = True,
     weights: Optional[npt.NDArray[np.float64]] = None,
     randSeed: int = 42,
@@ -74,6 +74,9 @@ def matchExistingBedGraph(
             f"Please use a suffix '.bedGraph' for `bedGraphFile`, got: {bedGraphFile}"
         )
 
+    if mergeGapBP is None:
+        mergeGapBP = (minMatchLengthBP // 2) + 1 if minMatchLengthBP is not None else 75
+
     allowedTemplates = [
         x for x in pw.wavelist(kind="discrete") if "bio" not in x
     ]
@@ -210,8 +213,6 @@ def matchWavelet(
 ) -> pd.DataFrame:
     r"""Detect structured peaks by cross-correlating Consenrich tracks with wavelet- or scaling-function templates.
 
-    See :ref:`matching` for an overview of the approach.
-
     :param chromosome: Chromosome name for the input intervals and values.
     :type chromosome: str
     :param values: 'Consensus' signal estimates derived from multiple samples, e.g., from Consenrich.
@@ -230,7 +231,6 @@ def matchWavelet(
     :type alpha: float
     :param minMatchLengthBP: Within a window of `minMatchLengthBP` length (bp), relative maxima in
         the signal-template convolution must be greater in value than others to qualify as matches.
-        *Set to a negative value to disable this filter*.
     :type minMatchLengthBP: int
     :param minSignalAtMaxima: Secondary significance threshold coupled with `alpha`. Require the *signal value*
         at relative maxima in the response sequence to be greater than this threshold. Comparisons are made in log-scale.
@@ -238,7 +238,7 @@ def matchWavelet(
         negative value to disable the threshold*.
         If a `str` value is provided, looks for 'q:quantileValue', e.g., 'q:0.75'. The
         threshold is then set to the corresponding quantile of the non-zero signal estimates.
-        Defaults to str value 'q:0.75' --- the 75th percentile of signal values.
+        Defaults to str value 'q:0.75' --- the 90th percentile of signal values.
     :type minSignalAtMaxima: Optional[str | float]
     :param useScalingFunction: If True, use (only) the scaling function to build the matching template.
         If False, use (only) the wavelet function.

consenrich/misc_util.py

@@ -62,6 +62,35 @@ def checkBamFile(bamFile: str) -> bool:
     return has_index
 
 
+def bamsArePairedEnd(bamFiles: List[str], maxReads: int = 1_000) -> List[bool]:
+    """
+    Take a list of BAM files, return a list (bool) indicating whether
+    each BAM contains paired-end reads (True) or only single-end reads (False).
+
+    :param bamFiles: List of paths to BAM files
+    :type bamFiles: List[str]
+    :param maxReads: Maximum number of reads to check in each BAM file
+    :type maxReads: int
+    :return: List of booleans corresponding to each BAM file
+    :rtype: List[bool]
+    """
+
+    results = []
+    for path in bamFiles:
+        paired = False
+        seen = 0
+        with sam.AlignmentFile(path, "rb") as bam:
+            for rec in bam.fetch(until_eof=True):
+                if rec.is_paired:
+                    paired = True
+                    break
+                seen += 1
+                if maxReads is not None and seen >= maxReads:
+                    break
+        results.append(paired)
+    return results
+
+
 def getChromSizesDict(
     sizes_file: str,
     excludeRegex: str = r"^chr[A-Za-z0-9]+$",

{consenrich-0.6.3b1.dist-info → consenrich-0.7.0b1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: consenrich
-Version: 0.6.3b1
+Version: 0.7.0b1
 Summary: Genome-wide estimation of signals hidden in noisy multi-sample HTS datasets
 Author-email: "Nolan H. Hamilton" <nolan.hamilton@unc.edu>
 Requires-Python: >=3.11
@@ -43,8 +43,8 @@ Consenrich is an adaptive linear state estimator that yields genome-wide, uncert
 
 Special emphasis is placed on computational efficiency, model interpretability, and practical utility for downstream tasks that require well-resolved genome-wide signal estimates and uncertainty quantification across samples, such as:
 
-* Consensus detection of open chromatin regions, TF footprints, nucleosome occupancy, histone modification
-* Candidate selection and boundary refinement for differential analyses, fine-mapping, reporter assays, etc.
+* Consensus detection of open chromatin regions, TF binding, histone modification, etc.
+* Candidate prioritization for differential analyses, functional validation, integrative modeling, etc.
 
 [**See the Documentation**](https://nolan-h-hamilton.github.io/Consenrich/) for usage examples, installation details, configuration options, and an API reference.
 

{consenrich-0.6.3b1.dist-info → consenrich-0.7.0b1.dist-info}/RECORD

@@ -1,19 +1,13 @@
-consenrich-0.6.3b1.dist-info/RECORD,,
-consenrich-0.6.3b1.dist-info/WHEEL,sha256=sunMa2yiYbrNLGeMVDqEA0ayyJbHlex7SCn1TZrEq60,136
-consenrich-0.6.3b1.dist-info/entry_points.txt,sha256=EXIGcSTyc16vtPkfHJNs-aaSVoq6Pn5Ev5GeW1JCYn0,58
-consenrich-0.6.3b1.dist-info/top_level.txt,sha256=jsWw8GC11dOKPcdULXk-ggW357CO-vTNW6ssryqa21Q,11
-consenrich-0.6.3b1.dist-info/METADATA,sha256=MAf49unrS7M1GZ0pU2s5TJAk2ZYJ3pJ6nfxlUXiMFm8,2563
-consenrich-0.6.3b1.dist-info/licenses/LICENSE,sha256=w09-aT0LFrH_cL3ShJWz-xusRpbThwTpdmBD08tc8EI,1074
-consenrich/detrorm.py,sha256=aJf4uZy2qgDIFfkOpTPJw2akVZ6H8-K64UZ63C6aZBw,8508
-consenrich/misc_util.py,sha256=SoUCgiON_9dbRbrZQoN2NlitDn6fhOgxe4hBYmWvZaI,2726
+consenrich/detrorm.py,sha256=KeAgkPkcvFa1-DW0PKlyf64qy7m19KMnGHe6xE60SDw,8876
+consenrich/misc_util.py,sha256=OIjYvwbkW2SbTNhqFO1LnVFuHJK3syU2M1Vzo2SeLc4,3675
 consenrich/constants.py,sha256=5YdNjeyeR1iGbYJXACpxLFS2xVBoyN9bqC7InXPdqKw,5063
 consenrich/__init__.py,sha256=lg02bx0LdXDIQ7Q-tky01xo0tOXYTcJeXqaCXNSFFyA,320
-consenrich/core.py,sha256=RYRBVNoRCFlOYaD_KHApzIy9CcYIoewPT160o8IlM24,52302
-consenrich/matching.py,sha256=UdZfuoDxeiPLgwtu246rYnNrF4QQRUUeezo5Xcbn_4Y,27725
-consenrich/consenrich.py,sha256=f2ZvuQO5AsSS5oo2vxekMGpeEzLSsee04CKXFknr7FI,35486
-consenrich/cconsenrich.cpython-311-darwin.so,sha256=tlE_iCFWNfkpQQthQrC_y5VJ8Qdg640mw_B-YLvs8YE,392816
+consenrich/core.py,sha256=jm7g_qfdL5dktPluIKUcdYrxXGzbjPMjYEkL9md43J0,52760
+consenrich/matching.py,sha256=-r88HoXN-1r_PXK98nvf2KYox7goHRHFrqYdWXGPhms,27738
+consenrich/consenrich.py,sha256=E2OoBbw7qTRYkikwogbZNecihuZvzlZFaHVWfxu55E8,36469
+consenrich/cconsenrich.cpython-311-darwin.so,sha256=XmIiLr60cY_D5bWRS4vmn_Cqwj93vR1UEyiTWmsIGGw,392816
 consenrich/cconsenrich.pyx,sha256=Wht-d6sUJ-zma0rNHx4DcAIsooFaSR_BdftjJxCLRv8,32604
-consenrich/cconsenrich.c,sha256=fL1mF_9kyb1rt1Hi4ryX-0FdFwUT-KzYCRS_HCye_Cc,2052512
+consenrich/cconsenrich.c,sha256=MnuLySBFOhWr5b0ZrrcZYES2qmuj0bgG_AzsnC4uGVI,2052512
 consenrich/data/hg19.sizes,sha256=ewnSktA_Ps1BoiU3yeLNaJxJO-taq3uKE4-6JUnly1o,365
 consenrich/data/mm10.sizes,sha256=sgHMQGBr6yEm4hKqeN3auQJdlMX4ZdqDQ23EdDmWedU,320
 consenrich/data/hg38_blacklist.bed,sha256=zbamE4bP5JJT-ivyDp61LjvaI00Wo-vd0oKtFxy_u4E,14940
@@ -35,3 +29,9 @@ consenrich/data/mm10_sparse.bed,sha256=ukvVuheKf4gxzAzXUbKZ1sewsmP-WOsUz60ySENkm
 consenrich/data/ce10.sizes,sha256=1crlJDro3lhUpECU_2g9eVIUFM27mw0uMzWqtdmThgA,88
 consenrich/data/dm6.sizes,sha256=0MNGeHSdAwu-Ym_ApUlHoDybDZDNyqYhbVbR_srZiEY,100
 consenrich/data/dm6_sparse.bed,sha256=H9wvrZs2ACdtUbDZhLXEEJ4xL5OpKOxhU_Pqf2EyDOM,445849
+consenrich-0.7.0b1.dist-info/RECORD,,
+consenrich-0.7.0b1.dist-info/WHEEL,sha256=sunMa2yiYbrNLGeMVDqEA0ayyJbHlex7SCn1TZrEq60,136
+consenrich-0.7.0b1.dist-info/entry_points.txt,sha256=EXIGcSTyc16vtPkfHJNs-aaSVoq6Pn5Ev5GeW1JCYn0,58
+consenrich-0.7.0b1.dist-info/top_level.txt,sha256=jsWw8GC11dOKPcdULXk-ggW357CO-vTNW6ssryqa21Q,11
+consenrich-0.7.0b1.dist-info/METADATA,sha256=AxzGS0IcXuR8QTnyRdIzCsR3xp5ivWfVhDtA9ZtctO0,2539
+consenrich-0.7.0b1.dist-info/licenses/LICENSE,sha256=w09-aT0LFrH_cL3ShJWz-xusRpbThwTpdmBD08tc8EI,1074