# Getting Started

Tutorials for using single-cell data with PyTorch. These materials are aimed
at two groups: machine learning practitioners new to genomics, and genomics
researchers wanting to use deep learning.

## Tutorials

| Tutorial | Audience | Duration | Open in Colab | What it covers |
| --- | --- | --- | --- | --- |
| [Basics: Single-cell Data in AnnData format](notebooks/basics/genomics_anndata_basics.ipynb) | ML practitioners new to single-cell data | 30-45 min | [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/DaminK/AnnData_Pytorch_Tutorials/blob/main/notebooks/basics/genomics_anndata_basics.ipynb) | What scRNA-seq data is and how it differs from typical ML datasets |
| [Basics: Machine Learning with PyTorch](notebooks/basics/ml_pytorch_basics.ipynb) | Genomics researchers new to ML | 45-60 min | [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/DaminK/AnnData_Pytorch_Tutorials/blob/main/notebooks/basics/ml_pytorch_basics.ipynb) | PyTorch basics explained using genomics examples |
| [Single-cell data in PyTorch](notebooks/tutorials/anndata_pytorch_tutorial.ipynb) | All participants | 45-60 min | [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/DaminK/AnnData_Pytorch_Tutorials/blob/main/notebooks/tutorials/anndata_pytorch_tutorial.ipynb) | Use AnnData's `AnnLoader` for per-cell classification and regression |
| [Patient-level learning](notebooks/tutorials/patient_level_learning.ipynb) | Participants interested in sample-level prediction | 30-45 min | [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/DaminK/AnnData_Pytorch_Tutorials/blob/main/notebooks/tutorials/patient_level_learning.ipynb) | Model patient-level cell populations with PyTorch datasets and `ggml-ot` |

**Suggested workshop flow:** Choose the primer for the domain that is less
familiar to you. In a mixed workshop, participants can work through the two
primers in parallel, then regroup for **Single-cell data in PyTorch**. Continue
with **Patient-level learning** as an optional advanced tutorial.

## Local installation

Google Colab requires no local setup. To run the tutorials locally on macOS or Linux:

```bash
git clone https://github.com/DaminK/AnnData_Pytorch_Tutorials.git
cd AnnData_Pytorch_Tutorials
python -m venv .venv && .venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m jupyter lab
```

The third line creates the virtual environment and installs the dependencies
into it in one shell command. Activation is not required. On Windows, replace
`.venv/bin/python` with `.venv\Scripts\python.exe`.

## What you'll learn

These tutorials show you how to:

- Load scRNA-seq data with Scanpy and inspect AnnData objects
- Build supervised models with PyTorch
- Handle sparse, high-dimensional biological data
- Batch cells with AnnData's `AnnLoader` and model patient-level data with `ggml-ot`
- Evaluate classification and regression workflows

The tutorials include notes explaining genomics concepts for ML practitioners
and ML concepts for genomics researchers.

## Acknowledgments

These tutorials use [Scanpy](https://scanpy.readthedocs.io/), [AnnData](https://anndata.readthedocs.io/), [PyTorch](https://pytorch.org/), and [ggml-ot](https://github.com/DaminK/ggml-ot). Documentation is built with [Jupyter Book](https://jupyterbook.org/).

## Additional Resources

Useful links:
- [Single-cell best practices](https://www.sc-best-practices.org/)
- [Scanpy tutorials](https://scanpy-tutorials.readthedocs.io/)
- [PyTorch tutorials](https://pytorch.org/tutorials/)
- [AnnLoader documentation](https://anndata.readthedocs.io/en/stable/generated/anndata.experimental.AnnLoader.html) - PyTorch batches from AnnData
- [ggml-ot](https://github.com/DaminK/ggml-ot) - Patient-level distribution learning

## License

This project is available under the [MIT License](https://github.com/DaminK/AnnData_Pytorch_Tutorials/blob/main/LICENSE).