Metadata-Version: 2.4
Name: pinpoint-sig
Version: 0.1.2
Summary: Personalized Integrated Nanopore Profiling of Individual (Copy-)Number Trajectories
Author-email: Nir Lavi <NirLavi@mail.huji.ac.il>
License: MIT License
        
        Copyright (c) 2026 Nir Lavi
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        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 conditions:
        
        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/nir-lavi/pinpoint
Project-URL: Issues, https://github.com/nir-lavi/pinpoint/issues
Keywords: cancer,liquid biopsy,CSF,nanopore,copy number,pediatric,ichorCNA
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: matplotlib>=3.7
Dynamic: license-file

# PINPOINT
**Personalized Integrated Nanopore Profiling Of Individual (Copy-)Number Trajectories**

A Python tool for personalized cancer monitoring from pediatric CSF liquid biopsies,
based on nanopore sequencing → ichorCNA → personalized CNA signal tracking over time.

---

## What it does
- Finds a **patient-specific CNA fingerprint** from a reference tumor sample
- Tracks this signal longitudinally across follow-up CSF samples
- Scores each sample using a **sign concordance score** against the reference
- Visualizes results as **temporal graphs** and **per-chromosome heatmaps**
- Highlights **suspected driver genes** (COSMIC Cancer Gene Census) in altered regions

## Installation
```bash
pip install pinpoint-sig
```

Or from source:
```bash
git clone https://github.com/nir-lavi/pinpoint.git
cd pinpoint
pip install -e .
```

## Quick Start
```python
import pinpoint
import datetime

# Add samples for a patient (first sample becomes reference automatically)
pinpoint.add_sample(
    patient        = "Patient_1",
    sample_name    = "CSF-001",
    sample_date    = datetime.datetime(2023, 1, 15),
    ichor_location = "/path/to/ichorCNA/CSF-001/",
    tumor_fraction = 0.42,
    coverage       = 1.8,
    disease_status = "AD",
    diagnosis      = "Medulloblastoma",
)

pinpoint.add_sample(
    patient        = "Patient_1",
    sample_name    = "CSF-002",
    sample_date    = datetime.datetime(2023, 4, 10),
    ichor_location = "/path/to/ichorCNA/CSF-002/",
    tumor_fraction = 0.05,
    coverage       = 0.5,
    disease_status = "NED",
    diagnosis      = "Medulloblastoma",
)

# Plot
pinpoint.plot_temporal("Patient_1", save=True)
pinpoint.plot_heatmap("Patient_1", genes=True, save=True)
```

## Tutorial

A full worked example using a pediatric Pinealoblastoma case (9 longitudinal CSF samples over 17 months) is available in [`tutorial/PINPOINT_tutorial.ipynb`](tutorial/PINPOINT_tutorial.ipynb).

The notebook covers:
- Adding samples and setting up a patient directory
- How the reference tumor fingerprint is selected
- Interpreting the `signf` score
- Generating and reading the temporal plot and heatmap

> **Note:** The tutorial notebook is provided without raw data for patient privacy reasons.  
> To run it, point `ICHOR_BASE` to your own ichorCNA output directory.

## Example Output

### Temporal Score Trajectory
Longitudinal `signf` scores across 9 CSF samples. The patient transitions from Active Disease (red) to No Evidence of Disease (green), with scores dropping below the 0.2 threshold in remission.

![Temporal plot](images/timeline.jpeg)

### Per-Chromosome Heatmap with Suspected Driver Genes
Per-chromosome sign concordance scores across all samples. Red columns indicate chromosomes with strong tumor signal. The gene panel below highlights COSMIC driver genes in altered regions — red = amplified oncogenes, blue = deleted tumor suppressors.

![Heatmap](images/heatmap.jpeg)

## Input Requirements
Each sample requires ichorCNA output files in `ichor_location/`:
- `{sample_name}.correctedDepth.txt`
- `{sample_name}.seg`

## Patient Directory Structure
```
Patient_1/
    info.tsv          # sample metadata + scores (auto-generated)
    reference.tsv     # reference CNA profile with informative mask
    plots/            # saved figures
```

## API Reference

| Function | Description |
|---|---|
| `add_sample(patient, sample_name, ...)` | Add a sample and compute scores |
| `set_reference(patient, sample_name)` | Change the reference sample |
| `plot_temporal(patient, save=True)` | Plot score + coverage timeline |
| `plot_heatmap(patient, genes=True, save=True)` | Plot per-chromosome heatmap |

## Citation
If you use PINPOINT in your research, please cite: *(coming soon)*

## License
MIT
