Skip to content

Commit 063f632

Browse files
lzj1769lzj1769
committed
update docs
1 parent e96b039 commit 063f632

1 file changed

Lines changed: 170 additions & 9 deletions

File tree

‎docs/tutorials/pbmc/03_train_cell2net.ipynb‎

Lines changed: 170 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,25 @@
11
{
22
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"id": "2e4b1fbe",
6+
"metadata": {},
7+
"source": [
8+
"# Cell2Net Training Tutorial: PBMC Dataset\n",
9+
"\n",
10+
"This tutorial demonstrates how to train Cell2Net models for gene expression prediction using peripheral blood mononuclear cell (PBMC) data. \n",
11+
"\n",
12+
"## Workflow Summary\n",
13+
"\n",
14+
"1. **Data Loading**: Load prepared multiome data with peak-to-gene associations\n",
15+
"2. **Model Initialization**: Create Cell2Net models with pre-trained sequence encoders\n",
16+
"3. **Training**: Train individual models for each target gene using paired RNA/ATAC data\n",
17+
"4. **Validation**: Evaluate model performance on held-out validation set\n",
18+
"5. **Results**: Generate predictions and visualize training metrics\n",
19+
"\n",
20+
"This approach enables Cell2Net to learn complex regulatory relationships between chromatin accessibility patterns, DNA sequence motifs, and gene expression in immune cells."
21+
]
22+
},
323
{
424
"cell_type": "code",
525
"execution_count": 1,
@@ -21,6 +41,16 @@
2141
"import torch"
2242
]
2343
},
44+
{
45+
"cell_type": "markdown",
46+
"id": "3f819107",
47+
"metadata": {},
48+
"source": [
49+
"### Check Cell2Net Version\n",
50+
"\n",
51+
"Verify the installed version of Cell2Net to ensure compatibility with this tutorial."
52+
]
53+
},
2454
{
2555
"cell_type": "code",
2656
"execution_count": 2,
@@ -42,6 +72,21 @@
4272
"cn.__version__"
4373
]
4474
},
75+
{
76+
"cell_type": "markdown",
77+
"id": "13451c19",
78+
"metadata": {},
79+
"source": [
80+
"## 2. Setup Output Directory\n",
81+
"\n",
82+
"Create the output directory structure for storing:\n",
83+
"- **model/**: Trained Cell2Net models for each gene (saved as .pt files)\n",
84+
"- **plot/**: Training visualization plots showing loss curves and prediction scatter plots\n",
85+
"- **prediction/**: Numerical results including predictions and performance metrics\n",
86+
"\n",
87+
"This organized structure facilitates result analysis and model deployment."
88+
]
89+
},
4590
{
4691
"cell_type": "code",
4792
"execution_count": null,
@@ -50,7 +95,27 @@
5095
"outputs": [],
5196
"source": [
5297
"out_dir = './03_train_cell2net'\n",
53-
"os.makedirs(out_dir, exist_ok=True)"
98+
"\n",
99+
"os.makedirs(out_dir, exist_ok=True)\n",
100+
"os.makedirs(f\"{out_dir}/model\", exist_ok=True)\n",
101+
"os.makedirs(f\"{out_dir}/plot\", exist_ok=True)\n",
102+
"os.makedirs(f\"{out_dir}/prediction\", exist_ok=True)"
103+
]
104+
},
105+
{
106+
"cell_type": "markdown",
107+
"id": "5e6f7389",
108+
"metadata": {},
109+
"source": [
110+
"## 3. Load Prepared Data\n",
111+
"\n",
112+
"Load the multiome dataset prepared in the previous tutorial step. This MuData object contains:\n",
113+
"- **RNA modality**: Gene expression counts for immune cell populations\n",
114+
"- **ATAC modality**: Chromatin accessibility peaks across the genome\n",
115+
"- **Peak-to-gene associations**: Regulatory links between accessible regions and target genes\n",
116+
"- **Sequence information**: DNA sequences around regulatory peaks for motif analysis\n",
117+
"\n",
118+
"The `genes` list contains all target genes with sufficient peak-to-gene associations for training reliable Cell2Net models."
54119
]
55120
},
56121
{
@@ -64,6 +129,20 @@
64129
"genes = mdata.uns['peak_to_gene']['gene'].unique().tolist()"
65130
]
66131
},
132+
{
133+
"cell_type": "markdown",
134+
"id": "1ac1747b",
135+
"metadata": {},
136+
"source": [
137+
"### Inspect the Data Structure\n",
138+
"\n",
139+
"Examine the loaded MuData object to understand:\n",
140+
"- **Number of cells**: Metacells representing cell type populations\n",
141+
"- **Number of genes**: Target genes for expression prediction\n",
142+
"- **Number of peaks**: Accessible chromatin regions from ATAC-seq\n",
143+
"- **Data modalities**: RNA and ATAC measurements integrated in single object"
144+
]
145+
},
67146
{
68147
"cell_type": "code",
69148
"execution_count": 5,
@@ -122,6 +201,16 @@
122201
"mdata"
123202
]
124203
},
204+
{
205+
"cell_type": "markdown",
206+
"id": "930b4a03",
207+
"metadata": {},
208+
"source": [
209+
"### Number of Target Genes\n",
210+
"\n",
211+
"Display the total number of genes that will be modeled. Each gene requires sufficient peak-to-gene associations to train a robust Cell2Net model. Typically, this includes highly expressed genes with well-characterized regulatory regions in the PBMC dataset."
212+
]
213+
},
125214
{
126215
"cell_type": "code",
127216
"execution_count": 6,
@@ -143,6 +232,21 @@
143232
"len(genes)"
144233
]
145234
},
235+
{
236+
"cell_type": "markdown",
237+
"id": "a7eb4a0e",
238+
"metadata": {},
239+
"source": [
240+
"## 4. Train-Validation Split\n",
241+
"\n",
242+
"Divide the data into training (80%) and validation (20%) sets using stratified random sampling. This ensures:\n",
243+
"- **Training set**: Used for model parameter optimization and learning regulatory patterns\n",
244+
"- **Validation set**: Independent evaluation to assess model generalization and prevent overfitting\n",
245+
"- **Reproducibility**: Fixed random seed (42) ensures consistent splits across runs\n",
246+
"\n",
247+
"The split is performed at the cell level, maintaining the integrity of multiome measurements within each metacell."
248+
]
249+
},
146250
{
147251
"cell_type": "code",
148252
"execution_count": 7,
@@ -156,6 +260,21 @@
156260
" random_state=42)"
157261
]
158262
},
263+
{
264+
"cell_type": "markdown",
265+
"id": "5fd61424",
266+
"metadata": {},
267+
"source": [
268+
"## 5. Load Pre-trained Sequence Encoder\n",
269+
"\n",
270+
"Initialize the pre-trained sequence encoder that was trained in the previous tutorial step. This encoder:\n",
271+
"- **Processes DNA sequences**: Converts nucleotide sequences to dense embeddings\n",
272+
"- **Captures motif patterns**: Learns transcription factor binding site preferences\n",
273+
"- **Transfer learning**: Pre-trained weights provide strong initialization for gene-specific training\n",
274+
"\n",
275+
"The pre-trained model significantly improves training efficiency and final model performance by leveraging sequence-level patterns learned across the entire genome."
276+
]
277+
},
159278
{
160279
"cell_type": "code",
161280
"execution_count": null,
@@ -164,11 +283,38 @@
164283
"outputs": [],
165284
"source": [
166285
"pretrained_model_path = \"./pretrained_seq2acc.pth\"\n",
167-
"pretrained_state_dict = torch.load(pretrained_model_path, map_location=\"cpu\")\n",
286+
"pretrained_state_dict = torch.load(pretrained_model_path, map_location=\"cpu\")"
287+
]
288+
},
289+
{
290+
"cell_type": "markdown",
291+
"id": "716b9d78",
292+
"metadata": {},
293+
"source": [
294+
"## 6. Train Cell2Net Models\n",
168295
"\n",
169-
"os.makedirs(f\"{out_dir}/model\", exist_ok=True)\n",
170-
"os.makedirs(f\"{out_dir}/plot\", exist_ok=True)\n",
171-
"os.makedirs(f\"{out_dir}/prediction\", exist_ok=True)"
296+
"This is the main training loop that creates and trains individual Cell2Net models for each target gene. The process includes:\n",
297+
"\n",
298+
"### Model Architecture\n",
299+
"- **Cell2Net Framework**: Integrates sequence and accessibility information for gene expression prediction\n",
300+
"- **Sequence Encoder**: Pre-trained transformer that processes DNA sequences around regulatory peaks\n",
301+
"- **Accessibility Encoder**: Neural network that processes ATAC-seq peak intensities\n",
302+
"- **Covariates**: Include total RNA/ATAC counts to account for technical variation\n",
303+
"\n",
304+
"### Training Configuration\n",
305+
"- **Epochs**: 40 training epochs with early stopping based on validation performance\n",
306+
"- **Batch Size**: 32 metacells per batch for efficient GPU utilization\n",
307+
"- **Learning Rate**: 1e-4 with adaptive optimization\n",
308+
"- **Device**: GPU acceleration for faster training (cuda:1)\n",
309+
"\n",
310+
"### Model Outputs\n",
311+
"For each gene, the training produces:\n",
312+
"1. **Saved Model**: Best checkpoint saved as .pt file for future use\n",
313+
"2. **Performance Plots**: Training/validation loss curves and prediction scatter plots\n",
314+
"3. **Predictions**: Numerical results including correlation metrics and raw predictions\n",
315+
"\n",
316+
"### Biological Interpretation\n",
317+
"Each model learns how chromatin accessibility patterns and DNA sequence motifs around regulatory peaks contribute to gene expression in different immune cell types. The integration of sequence and accessibility enables Cell2Net to capture complex regulatory logic governing immune cell gene programs."
172318
]
173319
},
174320
{
@@ -1382,11 +1528,26 @@
13821528
]
13831529
},
13841530
{
1385-
"cell_type": "code",
1386-
"execution_count": null,
1387-
"id": "b8603ef8",
1531+
"cell_type": "markdown",
1532+
"id": "51ab7e8d",
1533+
"metadata": {},
1534+
"source": [
1535+
"## Training Complete\n",
1536+
"\n",
1537+
"The Cell2Net training process is now complete! You have successfully:\n",
1538+
"\n",
1539+
"### Generated Outputs\n",
1540+
"1. **Trained Models**: Individual Cell2Net models for each target gene stored in `./03_train_cell2net/model/`\n",
1541+
"2. **Performance Visualizations**: Training plots showing loss curves and prediction accuracy in `./03_train_cell2net/plot/`\n",
1542+
"3. **Prediction Results**: Numerical predictions and performance metrics in `./03_train_cell2net/prediction/`\n",
1543+
"\n",
1544+
"The trained models capture the complex regulatory landscape of immune cells, enabling prediction of gene expression from chromatin accessibility and sequence information alone."
1545+
]
1546+
},
1547+
{
1548+
"cell_type": "markdown",
1549+
"id": "7e6988e4",
13881550
"metadata": {},
1389-
"outputs": [],
13901551
"source": []
13911552
}
13921553
],

0 commit comments

Comments
 (0)