<img src="image.png" alt="Logo generated by DALLE-3" width="80" height="90" style="float: right;"/>

# HiScanner (HIgh-resolution Single-Cell Allelic copy Number callER)
[![PyPI version](https://badge.fury.io/py/hiscanner.svg)](https://badge.fury.io/py/hiscanner)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

HiScanner is a lightweight python package for high-resolution single-cell copy number analysis.

## Content
- [Installation](#installation)
- [Requirements](#requirements)
- [Quick Start](#quick-start)
- [Operating System](#operating-system)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [Support](#support)
- [LICENSE](#license)

## Installation

It is recommended to install HiScanner in a virtual environment. Here's how to create one using conda:
```bash
conda create -n hiscanner_env python=3.8
conda activate hiscanner_env
```
To install HiScanner, simply use pip:
```bash
pip install hiscanner
```
## Requirements
HiScanner requires [`bcftools`](https://samtools.github.io/bcftools/bcftools.html), which must be included in `PATH`. All other dependencies should be installed automatically with pip.


## Quick Start
To get started with HiScanner, please refer to our [tutorial](https://github.com/parklab/hiscanner/blob/main/image.png). Here's a quick example:
```python
import hiscanner
# define your json file path
path = "your/dir/to/json"
# preprocess
hiscanner.pp.preprocess(path)
# segment
hiscanner.tl.segment(path)
# infer copy number
hiscanner.tl.infer_copy_number(path)
# visualize 
hiscanner.pl.plot_whole_genome_track(path)
```

## Command line interface
For advanced users interested in multi-sample segmentation (e.g., repurposing for bulk samples), HiScanner provides a command line interface. In bash, simply run:
```bash
hiscanner-segment -i {input_file} -l {LAMBDA} -o {output_file}
```
For more details, please refer to our [documentation](https://github.com/parklab/hiscanner/tree/main/docs).

## Required input
### 1) JSON 
HiScanner requires a json file as input. Here's an example:
```
{
    "bin_path": "/Users/yifan/dev/scanner_tutorial/tests/data/bins",
    "phase_file": "/Users/yifan/dev/scanner_tutorial/tests/data/hsnps/samplename_phased_hsnps.vcf",
    "germline": "bulkname",
    "gatk_vcf": "/Users/yifan/dev/scanner_tutorial/tests/data/hsnps/samplename_gatk.vcf",
    "stem": "/Users/yifan/dev/scanner_tutorial/tests/data/output/",
    "j": 20,
    "singlecell":"cellA,cellB",
    "MAX_WGD": 1,
    "LAMBDA":200
}

```
### 2) BAM
The BAM file should be indexed and sorted.
### 3) Unphased VCF 
output from GATK  or SCAN-SNV;
The VCF file should be indexed and sorted.
### 4) Phased VCF 
output from Eagle or other phasing tools;
### 5) Bins
The bins file should be a bed file (output from BIC-seq2)



## Operating System
HiScanner was tested in the following operating systems:
- macOS Ventura 13.5.2
- CentOS Linux 7.9
- Windows 11

## Documentation
For more detailed information and advanced usage, please refer to our [documentation](https://github.com/parklab/hiscanner/tree/main/docs).

## Support
HiScanner is currently under active development. For support or questions, please open an issue on our [GitHub repository](github.com/parklab/hiscanner).

## Contributing
Contributions to HiScanner are welcome. Please refer to our [contribution guidelines](https://github.com/parklab/hiscanner/tree/main/docs/contribution_guidelines.md) for more information.

## LICENSE
HiScanner is released under the MIT License, and is freely available for non-commercial use.