Evaluator Feature Registry
This documentation is directly synthesized from the nbs/features/*.ipynb Jupyter notebooks. These notebooks act as the active execution environment for each specific biological feature. During the nbdev-export step, they are automatically compiled into the Python classes below.
The registry.py module dynamically discovers all FeatureEvaluator subclasses and registers them into the kreview execution engine.
For the biological rationale behind each feature, see the Fragmentomics Feature Glossary.
📏 Fragment Size Coverage & Distributions
These features measure length distortions in circulating blood DNA caused by necrotic tumor shedding biases.
kreview.features.fsc_gene
FSCGeneEvaluator
kreview.features.fsc_binlevel
FSCOnTargetEvaluator
Bases: FeatureEvaluator
Extracts GC-corrected log2 fragment size category signals from on-target genomic bins.
Only bins with read coverage (total > 0) are included in aggregation. On-target panels typically cover ~2% of bins; without this filter, the 98% zero-coverage bins dominate the median with sentinel values.
kreview.features.fsc_binlevel_genomewide
FSCGenomewideEvaluator
Bases: FeatureEvaluator
Extracts GC-corrected log2 fragment size category signals from genomewide bins.
Only bins with read coverage (total > 0) are included in aggregation. Genomewide panels typically cover ~93% of bins, but the filter ensures uncovered bins don't contribute noise to summary statistics.
kreview.features.fsc_regions
FSCRegionsEvaluator
Bases: FeatureEvaluator
Extracts fragment size category ratios aggregated across gene-level regions.
Only regions with read coverage (total > 0) are included in aggregation. FSC regions are typically ~99.8% covered, so this filter is a consistency safeguard rather than a critical fix.
kreview.features.fsd
FSDOnTargetEvaluator
Bases: FeatureEvaluator
Extracts normalized densities for on-target fragment size buckets.
Derived metrics: - Bimodality index: mono-nucleosomal peak / di-nucleosomal valley - Shannon entropy of the size distribution - 143/166 ratio (classic cfDNA short-fragment proxy) - Per-chromosome 143/166 ratio (if chrom/region column available)
kreview.features.fsd_genomewide
FSDGenomewideEvaluator
Bases: FeatureEvaluator
Extracts normalized densities for genomewide fragment size buckets.
Derived metrics: - Bimodality index: mono-nucleosomal peak / di-nucleosomal valley - Shannon entropy of the size distribution - 143/166 ratio (classic cfDNA short-fragment proxy) - Per-chromosome 143/166 ratio (if chrom/region column available)
kreview.features.fsr
FSROnTargetEvaluator
Bases: FeatureEvaluator
Extracts the short/long fragment size ratio across on-target genomic bins.
Only bins with read coverage (total_count > 0) are included in aggregation. On-target panels typically cover ~2% of bins; without this filter, the 98% zero-coverage bins dominate the median with zero values.
Per-chromosome metrics: median short_long_ratio per chromosome,
parsed from region column format chrN:start-end.
kreview.features.fsr_genomewide
FSRGenomewideEvaluator
Bases: FeatureEvaluator
Extracts the short/long fragment size ratio across genomewide bins.
Only bins with read coverage (total_count > 0) are included in aggregation. Genomewide panels typically cover ~93% of bins, but the filter ensures uncovered bins don't contribute noise to summary statistics.
Per-chromosome metrics: median short_long_ratio per chromosome,
parsed from region column format chrN:start-end.
✂️ Nucleosome Protection (WPS & TFBS)
Measures the physical blockade signatures left by transcription factors and wrapped DNA histones before nuclease shedding.
kreview.features.wps_panel
WPSPanelEvaluator
Bases: FeatureEvaluator
Extracts WPS panel features aggregated per region_type.
For each WPS array column (wps_nuc, wps_tf, prot_frac_nuc, prot_frac_tf) and each region_type (TSS, CTCF), computes aggregate statistics across all panel regions of that type:
- mean: average of per-region array means (signal level)
- peak_valley: average of per-region (max − min) amplitude
- std: std of per-region array means (variability)
- mad: MAD of per-region array means (robust dispersion)
- spectral_dominant_freq: mean dominant FFT frequency across regions
Also aggregates scalar local_depth per region_type (mean).
Handles numpy arrays (native parquet list<float>),
Python lists, and string-encoded arrays (legacy format via _to_array).
Note
spectral_max_power was removed — real-data analysis (4 patient
samples) showed r=0.90–1.00 correlation with std after
per-region-type aggregation, making it completely redundant.
spectral_dominant_freq is retained because wps_tf showed
38.5% CV across samples, indicating potentially informative
periodicity from curated TSS/CTCF target loci.
Note
WPSGenome does NOT include spectral_dominant_freq because
genome-wide regions are dominated by window harmonics (72% of
arrays show period=200). Panel targets have more structured WPS
profiles due to curated genomic loci.
extract(df)
Extract WPS panel features aggregated per region_type.
For each region_type and array column, computes mean, peak_valley,
std, mad, and spectral_dominant_freq. Also averages scalar
local_depth per region_type.
Returns:
| Type | Description |
|---|---|
dict[str, float]
|
dict mapping |
dict[str, float]
|
Empty dict if no features could be extracted. |
kreview.features.wps_genomewide
WPSGenomeEvaluator
Bases: FeatureEvaluator
Extracts genome-wide WPS metrics per region_type.
For each WPS array column (wps_nuc, wps_tf, prot_frac_nuc, prot_frac_tf) and each region_type (TSS, CTCF), computes aggregate statistics across all genomic regions of that type:
- mean: average of per-region array means (signal level)
- peak_valley: average of per-region (max - min) amplitude
- std: standard deviation of per-region array means (variability)
- mad: median absolute deviation of per-region array means (robust dispersion)
Output features (example): TSS_wps_nuc_mean, CTCF_prot_frac_tf_peak_valley
Extraction paths
- SQL pushdown (
extract_sql()): Uses DuckDB nativelist_avg,list_max,list_minto aggregate 1.9B rows → ~158 rows inside DuckDB. MAD is computed via a lightweight second query (exact). Memory: <1 GB vs 96+ GB for the Python path. - Python fallback (
extract()): Per-sample chunked extraction with numpy — used when SQL pushdown is unavailable or fails.
Note
Krewlyzer stores WPS arrays as native list<float> in parquet,
not as string-encoded arrays. The extract() method handles
numpy arrays directly via _to_array() — no string parsing needed.
Note
FFT spectral features were evaluated and found to be redundant with
basic stats (r=0.91–1.00 with peak_valley/std). Nucleosome periodicity
is captured at the chromosome level by WPSBackgroundEvaluator
(NRL, periodicity_score). See wps_fft_analysis.md for details.
extract(df)
Extract WPS features aggregated per region_type.
For each region_type (TSS, CTCF) and each array column, computes:
- mean: average of per-region array means (signal level)
- peak_valley: average of per-region (max - min) (nucleosome amplitude)
- std: std of per-region array means (variability across regions)
- mad: MAD of per-region array means (robust dispersion)
Handles both numpy arrays (from native parquet list<float>)
and string-encoded arrays (legacy format, via parse_array()).
extract_sql()
DuckDB SQL pushdown for genome-wide WPS extraction.
Uses native list functions (list_avg, list_max, list_min) to aggregate 1.9B rows → ~158 rows inside DuckDB. Memory: <1 GB vs 96+ GB.
Returns multi-row result (one per sample × region_type). The CLI pivots this to wide format matching extract() output naming.
Note: MAD is NOT computed here — it's added by a lightweight Python post-step using a second DuckDB query on row-level means (exact).
kreview.features.wps_background
WPSBackgroundEvaluator
Bases: FeatureEvaluator
Extracts per-chromosome nucleosome periodicity metrics.
Each row in the source parquet represents one chromosome (group_id).
Metrics are pre-computed by krewlyzer from long-range WPS autocorrelation:
- nrl_bp: nucleosome repeat length
- nrl_deviation_bp: deviation from expected NRL
- periodicity_score: strength of periodic nucleosome signal
- adjusted_score: adjusted periodicity score
- fragment_ratio: fragment ratio
Since group_id is unique per row (one per chromosome), features are
extracted directly without aggregation — each row maps to a distinct
{chromosome}_{metric} feature.
extract(df)
Extract per-chromosome periodicity features.
Returns:
| Type | Description |
|---|---|
dict[str, float]
|
dict mapping |
dict[str, float]
|
Empty dict if no features could be extracted. |
kreview.features.tfbs
TFBSOnTargetEvaluator
kreview.features.tfbs_genomewide
TFBSGenomewideEvaluator
🛑 Cleavage Signatures (EndMotifs)
Models the specific micro-nuclease patterns (like DNASE1L3) structurally slicing accessible DNA at CCCA junctions.
kreview.features.endmotif
EndMotifOnTargetEvaluator
Bases: FeatureEvaluator
Extracts 4-mer fragment end motif frequencies for on-target regions.
Produces raw 256 4-mer frequencies plus derived summary metrics: - Shannon entropy (cleavage site diversity) - DNASE1L3 signature score (CC-ending motif sum) - Top-10 motif concentration - Purine/pyrimidine asymmetry at terminal base
kreview.features.endmotif_genomewide
EndMotifGenomewideEvaluator
Bases: FeatureEvaluator
Extracts 4-mer fragment end motif frequencies for genomewide regions.
Produces raw 256 4-mer frequencies plus derived summary metrics: - Shannon entropy (cleavage site diversity) - DNASE1L3 signature score (CC-ending motif sum) - Top-10 motif concentration - Purine/pyrimidine asymmetry at terminal base
kreview.features.endmotif_1mer
EndMotif1merEvaluator
Bases: FeatureEvaluator
Extracts 1-mer fragment end base frequencies with strand bias metrics.
Derived metrics: - Purine/pyrimidine asymmetry: (A+G) - (C+T) - A/T strand bias: A / (A+T) - C/G strand bias: C / (C+G)
kreview.features.breakpoint_motif
BreakPointMotifOnTargetEvaluator
kreview.features.breakpoint_motif_genomewide
BreakPointMotifGenomewideEvaluator
🧬 Motif Divergence Scores
Measures the statistical divergence of end-motif distributions from healthy baselines.
kreview.features.mds
MDSOnTargetEvaluator
Bases: FeatureEvaluator
On-target MDS signature.
Extracts ALL numeric columns from the single-row MDS on-target parquet rather than just the 2 originally hardcoded scalars.
kreview.features.mds_genomewide
MDSGenomewideEvaluator
Bases: FeatureEvaluator
Genomewide MDS signature.
Extracts ALL numeric columns from the single-row MDS genomewide parquet rather than just the 2 originally hardcoded scalars.
kreview.features.mds_gene
MDSGeneEvaluator
Bases: FeatureEvaluator
Gene-specific MDS signatures with cross-gene distribution statistics.
Per-gene metrics: mds_mean, mds_e1, mds_std, mds_z, mds_e1_z Cross-gene derived: z-score std/skew, fraction of genes diverged (|z|>2)
kreview.features.mds_exon
MDSExonEvaluator
Bases: FeatureEvaluator
Exon-level MDS distributions with cross-exon statistics.
Per-gene exon-level: mean and std of MDS across exons per gene. Cross-exon derived: global mean, std, skew, fraction diverged (|MDS|>2).
🗺️ Accessibility & Orientation
kreview.features.atac
ATACOnTargetEvaluator
kreview.features.atac_genomewide
ATACGenomewideEvaluator
kreview.features.ocf_ontarget
OCFOntargetEvaluator
Bases: FeatureEvaluator
Extracts on-target OCF metrics per tissue with cross-tissue aggregates.
Cross-tissue derived metrics: - max_ocf_z: highest z-score across all tissues - n_tissues_elevated: count of tissues with z > 2.0 - ocf_entropy: Shannon entropy of positive z-score distribution
kreview.features.ocf_offtarget
OCFOfftargetEvaluator
Bases: FeatureEvaluator
Extracts off-target OCF metrics per tissue with cross-tissue aggregates.
Cross-tissue derived metrics: - max_ocf_z: highest z-score across all tissues - n_tissues_elevated: count of tissues with z > 2.0 - ocf_entropy: Shannon entropy of positive z-score distribution