# bs-cpg


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

This is the main documentation homepage for bs-cpg. For comprehensive
module-specific documentation, API references, and examples, see the
sections below. For development guidance, see the [Developer
Guide](04_developers.ipynb).

## Module Documentation

Detailed documentation for each module is available in separate
notebooks:

- **[Setup & Configuration](01_setup.ipynb)**: Data path management and
  sample data access
- **[Data Acquisition](00_download_processed_geo.ipynb)**: Downloading
  RRBS data from GEO
- **[Reference Management](02_download_ref.ipynb)**: Reference genomes
  and liftover chain files
- **[Coordinate Processing](03_liftover_pos.ipynb)**: Genomic liftover
  and CpG validation
- **[Examples & Tutorials](05_examples.ipynb)**: Practical examples and
  workflows
- **[Developer Guide](04_developers.ipynb)**: Contributing to bs-cpg and
  development workflows

## Quick Start

### Basic Workflow Example

Here’s a simple workflow to get started with bs-cpg:

``` python
from bs_cpg.setup import read_sample_cpg, get_base_data_path
from bs_cpg.liftover_ps import cpg_reads, cpg_percent, liftover_positions

# 1. Load sample CpG data
df = read_sample_cpg(["chromosome", "pos"])

# 2. Validate CpG sites
reads = cpg_reads(df["chromosome"], df["pos"], "hg19", index_base=1)
percent_valid = cpg_percent(reads)
print(f"Valid CpG sites: {percent_valid:.1f}%")

# 3. Perform liftover to hg38
new_chroms, new_pos = liftover_positions(
    chromosomes=df["chromosome"],
    positions=df["pos"],
    genome_from="hg19",
    genome_to="hg38",
    index_base_from=1,
    index_base_to=1
)
```

## Installation & Setup

## Installation

Install latest from the GitHub
[repository](https://github.com/magistak/bs-cpg):

``` sh
$ pip install git+https://github.com/magistak/bs-cpg.git
```

or from [pypi](https://pypi.org/project/bs-cpg/)

``` sh
$ pip install bs_cpg
```

*Note: Ensure you have `htslib` (specifically `bgzip`) installed and in
your PATH for reference genome processing.*

### Documentation

Documentation can be found hosted on this GitHub
[repository](https://github.com/magistak/bs-cpg)’s
[pages](https://magistak.github.io/bs-cpg/). Package releases are
available on [pypi](https://pypi.org/project/bs-cpg/).

``` python
from bs_cpg.download_processed import Geofetcher
geo = Geofetcher(just_metadata=True)
projects = geo.get_projects('GSE51239')
```

    2

### Liftover & Validation (`bs_cpg.liftover_ps`)

Perform genomic liftover while explicitly handling 0-based or 1-based
indexing:

``` python
from bs_cpg.liftover_ps import liftover_positions
new_chroms, new_pos = liftover_positions(
    chromosomes=["chr1"], 
    positions=[100001], 
    genome_from="hg19", 
    genome_to="hg38", 
    index_base_from=1
)
```

You can also validate CpG site integrity using `cpg_percent(reads)`.