octopi

Octopi Pretrained Checkpoints

Pretrained model weights for Octopi, a deep learning framework for automated 3D particle picking in cryo-electron tomography (cryo-ET).

Model Details

Cryo-electron tomograms typically contain large regions of vacuum or embedding medium surrounding the biological specimen. These regions carry no useful signal and can introduce false positives during downstream particle picking. The checkpoints in this repo are 3D segmentation models trained with Octopi to identify the specimen region within a tomogram, so it can be masked out before particle picking runs.

Each checkpoint is a 3D convolutional segmentation network (architecture and training hyperparameters vary by checkpoint) trained on the tomogram/segmentation-mask pairs described in the config bundled with it. Every checkpoint's own config.yaml records its exact architecture (e.g. U-Net, SegResNet, DynUNet, SwinUNETR), input dimensions, and training configuration.

Repo layout. each checkpoint lives in its own subfolder containing both the trained weights and the model config needed to rebuild the architecture:

<checkpoint-name>/
├── weights.pth   # trained model state_dict
└── config.yaml   # architecture + training config used to build the model

Available Models

This table will grow as new models are added.

Usage

From the octopi CLI

Pass the checkpoint name directly as --model-weights — no --model-config needed, it's bundled and downloaded automatically. The first run downloads and caches the checkpoint; subsequent runs reuse the local cache.

octopi segment \
    --config config.json \
    --tomo-uri [email protected] \
    --model-weights tomogram-boundary \
    --seg-uri predict:octopi/1

From the Octopi Python API

from octopi.workflows import segment

segment(
    config="config.json",
    model_weights="tomogram-boundary",
    tomo_uri="[email protected]",
    seg_uri="predict:octopi/1",
)

Directly via huggingface_hub

Provide just the checkpoint name and download the whole subfolder — weights and config together — in a single call:

from huggingface_hub import snapshot_download

checkpoint = "tomogram-boundary"
local_dir = snapshot_download(repo_id="biohub/octopi", allow_patterns=f"{checkpoint}/*")

weights_path = f"{local_dir}/{checkpoint}/weights.pth"
config_path = f"{local_dir}/{checkpoint}/config.yaml"

Or with the hf CLI:

hf download biohub/octopi --include "tomogram-boundary/*" --local-dir ./tomogram-boundary

Training Data

tomogram-boundary

Predicts both sample and vacuum regions, useful for masking before downstream particle picking. For post-processing after inference, refer to copick's sample_boundaries tutorial. Trained on 300 tomograms (77 held out for validation) spanning 21 datasets (see details below).

<details> <summary>Full per-dataset breakdown, training details.</summary>

Ground-truth masks were built by annotating the top/bottom sample-boundary surfaces as picks, then fitting and rasterizing the sample slab (interior) and its vacuum complement (exterior) into a 3-class mask. All tomograms were Fourier-downsampled to 20 Å before training.

Training configuration: octopi train with SegResNet architecture and FocalLoss AdamW (lr = 3.21×10⁻⁴) for 1000 epochs, checkpoint selected on validation avg_f1 (evaluated every 100 epochs).

Performance metrics: avg_f1 on the 77-run validation split was used only to select the best checkpoint during training, not as a reported benchmark.

</details>

Frontier Safety

These models perform segmentation of cryo-ET tomograms, distinguishing specimen from vacuum/embedding medium, and do not generate, design, or predict biological sequences, structures, or novel compounds. They have no capability that could be used to create or enhance harmful biological agents, and we are not aware of a dual-use risk associated with their release. We are releasing the source code, training configuration, and model weights for these checkpoints in that context.

Biases, Risks, and Limitations

Potential Biases

This model was trained exclusively on cryo-ET tomograms and learned signal characteristics specific to that modality (contrast, noise, reconstruction artifacts). It carries no guarantee of working on other volumetric imaging domains — other electron microscopy modalities, medical CT/MRI, or light microscopy volumes — since those have fundamentally different signal properties. Within cryo-ET, segmentation quality may still degrade on unusual preparations or reconstruction methods not resembling the training distribution.

Risks

As with any learned segmentation model, predictions can fail silently without any indication that the output is wrong. Treat predicted masks as a proposal to mask/filter downstream particle picking, not as ground truth; incorrectly discarding sample-adjacent regions as "vacuum" could bias subsequent analysis.

Limitations

• Not intended for clinical, diagnostic, or any patient-facing use, or for non-cryo-ET imaging modalities.
• Questions or reports of unexpected behavior are welcome via GitHub Issues.

Acknowledgments

The training dataset for the tomogram-boundary checkpoint was annotated by Utz Ermel, who also trained this model.