Skip to content

Commit 07167f2

Browse files
MihinPMihinP
committed
Initial Docusaurus setup for GH-Pages
1 parent 60e3108 commit 07167f2

39 files changed

Lines changed: 21346 additions & 283 deletions

‎README.md‎

Lines changed: 108 additions & 283 deletions
Large diffs are not rendered by default.

‎docs/.gitignore‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

‎docs/docs/getting-started.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
5+
# Getting Started
6+
7+
This guide walks you through your first PartiNet analysis using the three-stage pipeline. We'll process cryo-EM micrographs from start to finish.
8+
9+
## Prerequisites
10+
11+
Before starting, ensure you have:
12+
- PartiNet installed (see [Installation](installation.md))
13+
- Motion-corrected micrographs in a source directory
14+
- A project directory where outputs will be saved
15+
- GPU access for optimal performance
16+
17+
## Directory Structure
18+
19+
PartiNet expects and creates the following directory structure:
20+
21+
```
22+
project_directory/
23+
├── motion_corrected/ # 📁 Your input micrographs
24+
│ ├── micrograph1.mrc
25+
│ ├── micrograph2.mrc
26+
│ └── ...
27+
├── denoised/ # 🧹 Created by denoise stage
28+
│ ├── micrograph1.mrc
29+
│ ├── micrograph2.mrc
30+
│ └── ...
31+
├── exp/ # 🎯 Created by detect stage
32+
│ ├── labels/ # 📋 Detection coordinates
33+
│ │ ├── micrograph1.txt
34+
│ │ ├── micrograph2.txt
35+
│ │ └── ...
36+
│ ├── micrograph1.png # 🖼️ Micrographs with detections drawn
37+
│ ├── micrograph2.
38+
│ └── ...
39+
└── partinet_particles.star # ⭐ Final STAR file (created by star stage)
40+
```
41+
42+
**Pipeline Flow:**
43+
1. **Input** → `motion_corrected/` (your micrographs)
44+
2. **Stage 1** → `denoised/` (cleaned micrographs)
45+
3. **Stage 2** → `exp*/` (detections + visualizations)
46+
4. **Stage 3** → `*.star` (final particle coordinates)
47+
48+
## Stage 1: Denoise
49+
50+
The first stage removes noise from your micrographs and improves signal-to-noise ratios:
51+
52+
<div class="container-tabs">
53+
54+
```shell title="Local Installation"
55+
partinet denoise \
56+
--source /data/my_project/motion_corrected \
57+
--project /data/my_project
58+
```
59+
60+
</div>
61+
62+
**What this does:**
63+
- Reads micrographs from `motion_corrected/` directory
64+
- Applies denoising algorithms
65+
- Saves cleaned micrographs to `denoised/` directory in your project folder
66+
67+
## Stage 2: Detect
68+
69+
The detection stage identifies particles in your denoised micrographs:
70+
71+
<div class="container-tabs">
72+
73+
```shell title="Local Installation"
74+
partinet detect \
75+
--weight /path/to/downloaded/model_weights.pt \
76+
--source /data/partinet_picking/denoised \
77+
--device 0,1,2,3 \
78+
--project /data/partinet_picking
79+
```
80+
81+
</div>
82+
83+
**What this creates:**
84+
- `exp/` directory in your project folder
85+
- `exp/labels/` directory containing detection coordinates for each micrograph
86+
- Micrographs with detection boxes drawn on top (saved in `exp/`)
87+
88+
**Key parameters:**
89+
- `--backbone-detector`: Neural network architecture to use
90+
- `--weight`: Path to trained model weights
91+
- `--conf-thres`: Confidence threshold for detections (0.0 = accept all)
92+
- `--iou-thres`: Intersection over Union threshold for filtering overlapping detections
93+
- `--device`: GPU devices to use (0,1,2,3 = use 4 GPUs)
94+
95+
## Stage 3: Star
96+
97+
The final stage converts detections to STAR format and applies confidence filtering:
98+
99+
<div class="container-tabs">
100+
101+
```shell title="Local Installation"
102+
partinet star \
103+
--labels /data/my_project/exp/labels \
104+
--images /data/my_project/denoised \
105+
--output /data/my_project/partinet_particles.star \
106+
--conf 0.1
107+
```
108+
109+
</div>
110+
111+
**What this does:**
112+
- Reads detection labels from `exp/labels/`
113+
- Filters particles based on confidence threshold (0.1 in this example)
114+
- Creates a STAR file ready for further processing in RELION or other software
115+
116+
## Output Files
117+
118+
After running all three stages, you'll have:
119+
120+
1. **Denoised micrographs** (`denoised/`) - Cleaned input for particle detection
121+
2. **Detection visualizations** (`exp/*.mrc`) - Micrographs with particle boxes drawn
122+
3. **Detection coordinates** (`exp/labels/*.txt`) - Raw detection data
123+
4. **STAR file** (`*.star`) - Final particle coordinates ready for downstream processing
124+
125+
126+
## Next Steps
127+
128+
- Learn more about individual stages: [Denoise](stages/denoise.md), [Detect](stages/detect.md), [STAR](stages/star.md)
129+
130+
## Troubleshooting
131+
132+
If you encounter issues:
133+
- Ensure all paths exist and are accessible
134+
- Check GPU availability with `nvidia-smi`
135+
- Verify container mounting with `-B` flags includes all necessary paths

‎docs/docs/installation.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
# Installation
6+
7+
PartiNet can be installed using several methods. Choose the option that best fits your environment and requirements.
8+
9+
## Prerequisites
10+
11+
- Python 3.8 or higher
12+
- CUDA-compatible GPU (recommended for optimal performance)
13+
- Git (for source installation)
14+
15+
## Method 1: Install from Source (Recommended)
16+
17+
This method gives you the latest version and full control over the installation:
18+
19+
```shell
20+
# Create new python environment
21+
conda create -n partinet python=3.9
22+
conda activate partinet
23+
# or using venv
24+
python -m venv partinet-env
25+
source partinet-env/bin/activate
26+
27+
# Install PartiNet
28+
git clone git@github.com:WEHI-ResearchComputing/PartiNet.git
29+
cd PartiNet
30+
pip install .
31+
```
32+
33+
## Method 2: Apptainer/Singularity Container
34+
35+
For users who prefer containerized environments or have limited system permissions:
36+
37+
**Option A: Pull and store locally**
38+
```shell
39+
apptainer pull partinet.sif oras://ghcr.io/wehi-researchcomputing/partinet:main-singularity
40+
apptainer exec --nv --no-home -B /vast partinet.sif partinet --help
41+
```
42+
43+
**Option B: Run directly from registry**
44+
```shell
45+
apptainer exec --nv --no-home \
46+
-B /vast oras://ghcr.io/wehi-researchcomputing/partinet:main-singularity \
47+
partinet --help
48+
```
49+
50+
**Container options explained:**
51+
- `--nv`: Enables NVIDIA GPU support
52+
- `--no-home`: Prevents mounting your home directory
53+
- `-B /vast`: Mounts the `/vast` directory (adjust path as needed for your data directory)
54+
55+
## Method 3: Docker Container
56+
57+
For Docker users:
58+
59+
```shell
60+
docker pull ghcr.io/wehi-researchcomputing/partinet:main
61+
docker run --gpus all -v /path/to/your/data:/data \
62+
ghcr.io/wehi-researchcomputing/partinet:main partinet --help
63+
```
64+
65+
**Docker options explained:**
66+
- `--gpus all`: Enables GPU support (requires nvidia-docker)
67+
- `-v /path/to/your/data:/data`: Mounts your data directory
68+
69+
70+
## Verification
71+
72+
After installation, verify that PartiNet is working correctly:
73+
74+
```shell
75+
partinet --help
76+
```
77+
78+
You should see version information and available commands.
79+
80+
## GPU Support
81+
82+
PartiNet is designed to leverage GPU acceleration for optimal performance. Ensure you have:
83+
84+
- NVIDIA GPU with CUDA compute capability 3.5+ (e.g., NVIDIA A30, A100, H100)
85+
- CUDA drivers installed
86+
- For containers: nvidia-docker (Docker) or `--nv` flag (Apptainer)
87+
88+
## Model Weights
89+
PartiNet model weights are available on [HuggingFace](https://huggingface.co/MihinP/PartiNet).
90+
Weights can be downloaded through the browser or through CLI via Git LFS
91+
92+
```shell
93+
# Verify Git LFS is installed
94+
git lfs --help
95+
mkdir PartiNet_weights
96+
cd PartiNet_weights
97+
git clone git@hf.co:MihinP/PartiNet
98+
```
99+
100+
You will see two `.pt` files available: `denoised_micrographs.pt` and `raw_micrographs.pt`.
101+
102+
## Next Steps
103+
104+
Once installed, proceed to [Getting Started](getting-started.md) to run your first PartiNet analysis.

‎docs/docs/intro.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# Introduction
6+
7+
PartiNet is a powerful command-line tool for particle picking on cryo-EM micrographs. It provides a comprehensive three-stage pipeline designed to clean, identify, and prepare particles from experimental data for subsequent processing.
8+
9+
## The Three-Stage Pipeline
10+
11+
PartiNet processes data through three sequential stages, each building on the output of the previous stage:
12+
13+
### 1. Denoise
14+
The first stage removes noise and artifacts from your raw data using fast heuristic denoising algorithms. This stage improves signal-to-noise ratios and prepares micrographs for accurate particle detection.
15+
16+
### 2. Detect
17+
The detection stage identifies and locates individual particles within your cleaned data. Using a dynamic adaptive architecture, it quickly and accurately identifies particles within micrographs.
18+
19+
### 3. Star
20+
The final stage prepares particle data for further processing and provides reports on particle populations in your dataset.
21+
22+
## Key Features
23+
24+
- **Fast picking** - Leverages state-of-the-art dynamic deep learning models for accurate particle processing
25+
- **Accurate picking** - PartiNet accurately identifies proteins in your micrographs and filters junk prior to further processing
26+
- **Overcome orientation bias** - PartiNet identifies rare views of proteins in your dataset
27+
- **Multi-species identification** - PartiNet can identify and pick heterogeneous samples without requiring prior estimation of box sizes
28+
- **Batch processing** - Process multiple files efficiently with parallel processing capabilities
29+
30+
## Use Cases
31+
32+
PartiNet is ideal for:
33+
- Identifying rare views
34+
- Picking on heterogeneous datasets
35+
- Reporting on particle populations
36+
37+
## Next Steps
38+
39+
- **New to PartiNet?** Start with [Installation](installation.md) to get up and running
40+
- **Ready to begin?** Follow our [Getting Started](getting-started.md) guide for your first analysis
41+
- **Need specific details?** Check the individual stage documentation: [Denoise](stages/denoise.md), [Detect](stages/detect.md), [Star](stages/star.md)
42+
43+
<!-- ## Getting Help
44+
45+
If you encounter issues or need assistance:
46+
- Check the [Troubleshooting](reference/troubleshooting.md) guide
47+
- Review the complete [CLI Reference](reference/cli-reference.md)
48+
- Look at our [Examples](examples/) for common use cases -->

‎docs/docs/stages/_category_.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "Picking",
3+
"position": 4,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "PartiNet processes cryo-EM micrographs through a carefully designed three-stage pipeline. Each stage builds upon the previous one, transforming raw motion-corrected micrographs into clean, accurately picked particle coordinates ready for downstream processing."
7+
}
8+
}

‎docs/docs/stages/assets/denoise_workflow_stacked.png‎

4.46 MB
Loading

0 commit comments

Comments
 (0)