Metadata-Version: 2.4
Name: priorcons
Version: 0.1.2
Summary: Tool for the integration of viral consensus sequences obtained by de novo and mapping strategies, supported by prior information.
Author-email: Germán Vallejo Palma <german.vallejo@isciii.es>
License: Attribution Permissive License (APL) 1.0
        
        Copyright (c) 2025 Germán Vallejo Palma
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to use,
        copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
        Software, and to permit persons to whom the Software is furnished to do so,
        subject to the following condition:
        
          * ATTRIBUTION: Redistributions of source or binary form, modified or
            unmodified, must retain the following attribution notice in a conspicuous
            location (for example, in the repository README, the package metadata,
            or in a NOTICE file shipped with binaries):
        
              "This software was developed by Germán Vallejo Palma at the Instituto de
               Salud Carlos III — National Centre of Microbiology (Respiratory Viruses
               and Influenza Unit)."
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/GERMAN00VP/priorCons/
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: biopython>=1.79
Requires-Dist: numpy>=1.21
Requires-Dist: pandas>=1.3
Requires-Dist: pyarrow>=12.0
Requires-Dist: matplotlib>=3.5
Requires-Dist: scipy>=1.7
Requires-Dist: seaborn>=0.11
Dynamic: license-file

# PriorCons 

This repository provides tools to:

1. **Generate Integrated Consensus (`integrate_consensus.py`)**  
   Produces a high-quality viral consensus by strategically using **ABACAS** sequences to fill missing regions in the **mapping** consensus. It employs a sliding-window approach that verifies the evolutionary plausibility of ABACAS content against empirical priors before incorporation.

2. **Build Evolutionary Priors (`build_priors.py`)**  
   Constructs empirical prior distributions from large multiple-sequence alignments. These priors model expected genetic variation across genomic windows and provide likelihood thresholds for quality control during consensus integration.

3. **Access Supporting Utilities (`utils` scripts)**  
   Provides modular helper functions for alignment processing, window scoring, and consensus construction used by both main workflows.

---
### Installation

```bash
pip install priorcons
```
---

### CLI usage 
```bash
# Create priors
priorcons build-priors --input sequences.fasta --ref REF_ID --output priors.parquet

# Run consensus integration
priorcons integrate-consensus --input alignment.aln --ref REF_ID --prior priors.parquet --output_dir results

```

---

## 🚀 Main Script: integrate_consensus.py

This is the entrypoint of the tool. It creates a *integrated consensus sequence* by combining mapping consensus and ABACAS output, both aligned to a reference sequence, but only after performing quality control (QC) at the window level.  

### 🔑 Inputs

- `--input` → path to an alignment file (`.aln`) containing at least:  
  - **1º Reference sequence**  
  - **2º Mapping consensus sequence**  
  - **3º ABACAS consensus sequence**  

 **The sequences in the alignment file must be provided in the specified order, as they will be identified by their position.**


- `--ref` → ID of the reference sequence in the alignment.  

- `--prior` → path to a priors table (`.parquet`) generated with `build_priors.py`.  

- `--output_dir` → directory to save the results.  


---

### 🧪 Workflow

1. **Start with mapping consensus** as the baseline
2. **Identify missing/unreliable regions** in mapping consensus
3. **For each window**:
   - If mapping has coverage → keep mapping sequence
   - If mapping has missing data → evaluate ABACAS for that window:
     * Check fragmentation and quality
     * Verify evolutionary plausibility using priors [(nLL score)](README.md#-methodology-build_priorspy)
     * If ABACAS passes QC → use ABACAS to fill missing regions
4. **Construct final consensus** combining mapping baseline with validated ABACAS fills
5. **Restore mapping-specific insertions**
6. **QC reporting**: compute coverage, substitutions, and insertion metrics comparing the final integrated consensus to MAPPING.  

---

### 📦 Outputs

The script produces **three files** inside `--output_dir`:

1. **Integrated consensus FASTA**  
   - File: `<basename>-INTEGRATED.fasta`  
   - Contains the final consensus sequence after merging and reinserting insertions.  

2. **Window QC trace (CSV)**  
   - File: `windows_trace.csv`  
   - One row per window, recording:  
     - `start`, `end` → genomic coordinates.  
     - `MISSING_MAPPING`, `MISSING_ABACAS` → counts of missing bases.  
     - `ABACAS_MORE_INFO` → whether ABACAS has fewer missing bases than MAPPING.  
     - `ABACAS_FRAGMENTS` → fragmentation level of ABACAS in this window (keep: 0 < n fragments < 3 ).  
     - `WINDOW_PRIOR_nLL_p95` → threshold from priors.  
     - `WINDOW_SCORE_nLL` → score of ABACAS in this window.  
     - `WINDOW_QC_PASSED` → True/False decision.  

3. **Consensus QC summary (JSON)**  
   - File: `qc.json`  
   - Provides overall metrics comparing the MAPPING consensus and the integrated consensus:  
     - `MAPPING_COVERAGE` → % of genome covered in MAPPING.  
     - `FINAL_COVERAGE` → % of genome covered in integrated consensus.  
     - `MAPPING_SUBSTITUTIONS` → substitutions vs. reference in MAPPING.  
     - `FINAL_SUBSTITUTIONS` → substitutions vs. reference in integrated consensus.  
     - `EXPECTED_SUBSTITUTIONS` → expected number of substitutions, extrapolated from mapping.  
     - `OBS-EXP_SUBSTITUTIONS` → difference between observed and expected substitutions.  
     - `N_INSERTIONS` → number of insertions added back.  
     - `TOTAL_INSERTIONS_LENGTH` → total inserted length.  
     - `INSERTIONS` → list of insertions with their coordinates.  

---

### ▶️ Example run

```bash
python integrate_consensus.py \
  --input /path/to/<sample_name>.aln \
  --ref RSV_BD \
  --prior /path/to/RSVBD_win100_ovlp50_priors.parquet \
  --output_dir results
```
----

This will generate:  

- `results/<sample_name>-INTEGRATED.fasta`  
- `results/windows_trace.csv`  
- `results/qc.json`  

---

## 🛠 Script: build_priors.py

This script creates **empirical priors** (overlapped windows) from a large multiple sequence alignment.  
These priors are later used by `integrate_consensus.py` to evaluate windows.

### 🔑 Inputs

- `-i / --input` → aligned FASTA file with multiple sequences.  
- `-r / --ref` → ID of the reference sequence.  
- `-o / --output` → output file (`.parquet`).  
- `--win` → window size (default: 100).  
- `--overlap` → overlap size (default: 10).  

### ▶️ Example run

```bash
python build_priors.py \
  -i alignment.fasta \
  -r ReferenceID \
  -o priors.parquet \
  --win 100 \
  --overlap 10
```
----

### 📦 Output

A `.parquet` file with one row per window, containing:  

- `start`, `end` → window coordinates.  
- `nLL_p95`, `nLL_p99` → empirical thresholds.  
- `profile` → base probability distributions for each position in the window.  

## 🧮 Methodology (build_priors.py)

### 1. Probability distributions per position

For each window of size `W` bases (e.g., `W = 100`), and for each position `j` within that window, we compute the probability of observing each nucleotide:

![P_j(b)](https://latex.codecogs.com/png.latex?P_j(b)=\frac{c_j(b)+\alpha}{\sum_{x\in\{A,C,G,T\}}(c_j(x)+\alpha)})

Where:  
- ![c_j(b)](https://latex.codecogs.com/png.latex?c_j(b)) = number of sequences with base ![b](https://latex.codecogs.com/png.latex?b) at position ![j](https://latex.codecogs.com/png.latex?j).  
- ![\alpha](https://latex.codecogs.com/png.latex?\alpha) = pseudocount (Laplace smoothing, default ![\alpha=1](https://latex.codecogs.com/png.latex?\alpha=1)) to avoid zero probabilities.  
- Bases `N` are ignored in the counts.  

This gives a **per-position categorical distribution**.

---

### 2. Log-likelihood of a sequence in a window

Given a query sequence ![Q](https://latex.codecogs.com/png.latex?Q), we compute its probability under the window profile.  
For each valid (non-`N`) position ![j](https://latex.codecogs.com/png.latex?j) with observed base ![q_j](https://latex.codecogs.com/png.latex?q_j):

![logL](https://latex.codecogs.com/png.latex?\log%20L(Q\mid%20\text{window})=\sum_{j=1}^{W}\log%20P_j(q_j))

The **normalized negative log-likelihood (nLL)** is:

![nLL](https://latex.codecogs.com/png.latex?\text{nLL}(Q)=-\frac{1}{N_{\text{valid}}}\sum_{j=1}^{W}\log%20P_j(q_j))

Where:  
- ![N_valid](https://latex.codecogs.com/png.latex?N_{\text{valid}}) = number of positions in the window where ![Q](https://latex.codecogs.com/png.latex?Q) has a non-`N` base.  

Smaller nLL values indicate sequences more likely under the empirical profile.


### 3. Empirical priors

To characterize "normal variation" for each window:

1. Score **all sequences** from the alignment against the window profile.  
2. Collect the distribution of nLL values.  
3. Extract percentiles (e.g., 95th and 99th) to serve as thresholds.  

Thus, for each window we store:  
- The **distribution (profile)**.  
- Empirical thresholds: `nLL_p95` and `nLL_p99`.  

A new sequence can later be compared:  
- If `nLL < nLL_p95` → typical.  
- If `nLL > nLL_p99` → unusually variable, possibly unreliable region.

---

---

## � Supporting utils

Several utility scripts provide reusable functions for both processes:  

- **utils.py** → basic alignment and scoring functions:  
  - `load_alignment`, `extract_ref_positions`, `sliding_windows`, `score_window`.  

- **utils_integrate_consensus.py** → additional helpers for consensus integration:  
  - missingness and fragmentation counts,  
  - insertion handling,  
  - QC calculations,  
  - consensus merging,  
  - window evaluation wrapper.  

These modular functions keep the pipeline clean and reusable.

## QC ANALYSIS

This tool allows also an analyis **QC**.

The input is a directory with all the results folders (one for each sample) there are stored the qc files:

-  input:  priorcons_path / <sample> / qc_files

It also need a gtf file and an outdir.

```bash
priorcons qc --input_dir /path/to/results/PRIORCONS/ \
             --gff_file /path/to/rsv.gff \
             --output_dir /path/to/output_dir_plots
```


## Test dataset for integration in nf-core/viralrecon pipeline

https://zenodo.org/records/17454552/files/PriorCons_Test_data.zip?download=1

