burstlink 1.1.7
A user-friendly package for analyzing gene interactions and transcriptional bursting.
License: MIT
Requires Python: >=3.8

<img src="https://raw.githubusercontent.com/LiyingZhou12/burstlink/main/docs/_static/image/logo.png" alt="Logo" width="450"/>            

## Brief introduction
BurstLink is a Python package to infer the coupled dynamics of gene regulatory interactions and transcriptional bursting from single-cell transcriptomics or multi-omics data.
It contains many intuitive visualization and downstream analysis tools, providing a great practical toolbox for biomedical researchers.

### Coupled dynamics of gene regulatory interactions and transcriptional bursting
Transcriptional bursts are inherently dynamic and stochastic processes, which are influenced by gene-gene regulatory interactions through transcription factors from other genes, ultimately driving highly heterogeneous gene expression within cells.  A question is to explore how dynamic gene-gene interaction-constructed regulatory network dictates bursting on a genome-wide scale. 

<img src="https://raw.githubusercontent.com/LiyingZhou12/burstlink/main/docs/_static/image/question.png" alt="question.png" width="900"/>

### Inference workflow 
BurstLink is a user-friendly package without the hyperparameter tuning, which is mainly utilized to infer coupled dynamics of gene regulatory interactions and transcriptional bursting, given scRNA-seq data of any two genes (screened by scATAC-seq data, optional). BurstLink enables gene-pair inference and supports rapid whole-genome inference and a series of downstream analyses.

<img src="https://raw.githubusercontent.com/LiyingZhou12/burstlink/main/docs/_static/image/workflow.png" alt="workflow.png" width="900"/>

## Installation
### System requirements
Recommended operating systems: macOS or Linux. BurstLink was developed and tested on Linux and macOS.
### Python requirements
BurstLink was developed using python 3.10.
### Installation using `pip`
We suggest setting up BurstLink in a separate `mamba` or `conda` environment to prevent conflicts with other software dependencies. Create a new Python environment specifically for BurstLink and install the required libraries within it.

```bash
mamba create -n burstlink_env python=3.10 r-base=4.3.2
mamba activate burstlink_env
pip install burstlink
```
if you use `conda`, `r-base=4.3.2` may not included in the channels. Instead, you can `r-base=4.3.1` in `conda`.

## Documentation, and Tutorials

For more realistic and simulation examples, please see BurstLink documentation that is available through the link https://burstlink.readthedocs.io/en/latest/.

## Quick start
Let's get a quick start on using burstlink to infer gene regulatory interactions and transcriptional bursting by using simulation data generated from the genetic toggle switch dynamic model.

### Import packages
```python
import os, math
import numpy as np
import pandas as pd
import burstlink as bl
```

### Setting work dictionary
To run the examples, you'll need to download the some pre-existing files in `docs/tutorials/simulated_data` folder and change your working directory to the `simulated_data` folder.

```python
os.chdir("your_path/simulated_data")
```

### scRNA-seq data from simulation
```python
import pickle
with open('data/simul_data_example1.pkl', "rb") as f: res = pickle.load(f)
simul_data = res['s_stable']
```
You can also generate new simulation data with `_synthetic_data` :

```python
params = [2, 2, 1, 1, 15, 15, 1, 0.2, 1, 3, 0.01, 2000]
BURST = True; PLOTS = False
res = bl._utils._synthetic_data.genes2_coexpression(params, BURST, PLOTS, None)
simul_data = res['s_stable']
```
### Run the inference procedure

Import the scRNA-seq data and obatin the inference results, including (1) regulatory interactions: regulation types, regulation strengths, and regulation visualization; and (2) transcriptional bursting: burst frequencies, burst sizes, and expression variabilities.
```python
genename = np.array(['gene1', 'gene2'])
rnaseq_data = pd.DataFrame(np.column_stack([np.arange(2), genename, simul_data]))
grn_info = pd.DataFrame([['gene1', 'gene2', -1, -1]], columns=['col1', 'col2', 'col3', 'col4'])
log_path = 'bl.data/outputs.ssa'

r = 0.7; tau = 0.3; TAU = False
rho = 2; tol = 1e-4
max_iter = 100; n_jobs = 1
return_res = False; return_plots = True
res_bursting, res_regulation = bl.tools._bursting_interactions.burst_link(grn_info, rnaseq_data, tau, tol, rho, r, max_iter, n_jobs, TAU, return_plots, log_path, return_res)
```
<img src="https://raw.githubusercontent.com/LiyingZhou12/burstlink/main/docs/_static/image/example.png" alt="example.png" width="900"/>



## Reference
Deciphering global transcriptional dynamics coordinated by gene-gene regulatory interactions using single-cell data.