octopi 1.0__tar.gz → 1.2.0__tar.gz

octopi-1.2.0/.github/workflows/deploy-docs.yaml

@@ -0,0 +1,72 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+      - docs
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/deploy-docs.yaml'
+  pull_request:
+    branches:
+      - main
+      - docs
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/deploy-docs.yaml'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.8'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs-material
+          pip install mkdocs-git-revision-date-localized-plugin
+          pip install mkdocs-git-committers-plugin-2
+          pip install mkdocs-git-authors-plugin
+          pip install mkdocs-awesome-pages-plugin
+          pip install mkdocs-minify-plugin
+          pip install mkdocs-redirects
+    
+      - name: Build documentation
+        run: mkdocs build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+  deploy:
+    needs: build
+    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/docs'
+    runs-on: ubuntu-latest    
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4 

octopi-1.2.0/.github/workflows/publish-docker.yml

@@ -0,0 +1,98 @@
+name: Docker
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+on:
+  push:
+    branches: [ "main" ]
+    # Publish semver tags as releases.
+    tags: [ 'v*.*.*' ]
+
+env:
+  # Use docker.io for Docker Hub if empty
+  REGISTRY: ghcr.io
+  # github.repository as <account>/<repo>
+  IMAGE_NAME: ${{ github.repository }}
+
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      # This is used to complete the identity challenge
+      # with sigstore/fulcio when running outside of PRs.
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # Install the cosign tool except on PR
+      # https://github.com/sigstore/cosign-installer
+      - name: Install cosign
+        if: github.event_name != 'pull_request'
+        uses: sigstore/cosign-installer@59acb6260d9c0ba8f4a2f9d9b48431a222b68e20 #v3.5.0
+        with:
+          cosign-release: 'v2.2.4'
+
+      # Set up BuildKit Docker container builder to be able to build
+      # multi-platform images and export cache
+      # https://github.com/docker/setup-buildx-action
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@f95db51fddba0c2d1ec667646a06c2ce06100226 # v3.0.0
+
+      - name: Clean up unused Docker resources
+        run: docker system prune --all --force --volumes
+
+      # Login against a Docker registry except on PR
+      # https://github.com/docker/login-action
+      - name: Log into registry ${{ env.REGISTRY }}
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@343f7c4344506bcbf9b4de18042ae17996df046d # v3.0.0
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      # Extract metadata (tags, labels) for Docker
+      # https://github.com/docker/metadata-action
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@96383f45573cb7f253c731d3b3ab81c87ef81934 # v5.0.0
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: type=sha
+
+      # Build and push Docker image with Buildx (don't push on PR)
+      # https://github.com/docker/build-push-action
+      - name: Build and push Docker image
+        id: build-and-push
+        uses: docker/build-push-action@0565240e2d4ab88bba5387d719585280857ece09 # v5.0.0
+        with:
+          context: .
+          file: ./Dockerfile
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      # Sign the resulting Docker image digest except on PRs.
+      # This will only write to the public Rekor transparency log when the Docker
+      # repository is public to avoid leaking data.  If you would like to publish
+      # transparency data even for private images, pass --force to cosign below.
+      # https://github.com/sigstore/cosign
+      - name: Sign the published Docker image
+        if: ${{ github.event_name != 'pull_request' }}
+        env:
+          # https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-an-intermediate-environment-variable
+          TAGS: ${{ steps.meta.outputs.tags }}
+          DIGEST: ${{ steps.build-and-push.outputs.digest }}
+        # This step uses the identity token to provision an ephemeral certificate
+        # against the sigstore community Fulcio instance.
+        run: echo "${TAGS}" | xargs -I {} cosign sign --yes {}@${DIGEST}

octopi-1.2.0/.github/workflows/release-please.yml

@@ -0,0 +1,79 @@
+name: Release Please
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+  pull_request:
+
+# cancel in-progress runs that use the same workflow and branch
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  release-please:
+    name: Create Release PRs
+    runs-on: ubuntu-latest
+    # Only run release-please on pushes to main, not on PRs
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+    steps:
+      # Generate token using your organization's GitHub App
+      - name: Generate token
+        id: generate_token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.GH_ACTIONS_HELPER_APP_ID }}
+          private-key: ${{ secrets.GH_ACTIONS_HELPER_PK }}
+
+      - name: Release Please
+        uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          manifest-file: ".release-please-manifest.json"
+          config-file: "release-please-config.json"
+          target-branch: "main"
+          token: ${{ steps.generate_token.outputs.token }}  # ← Changed from secrets.GITHUB_TOKEN
+    outputs:
+      paths_released: ${{ steps.release.outputs.paths_released }}
+      release_created: ${{ steps.release.outputs.release_created }}
+
+  publish-pypi:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    needs: release-please
+    # Only publish when a release is actually created
+    if: needs.release-please.outputs.release_created == 'true'
+    environment:
+      name: pypi
+      url: https://pypi.org/p/octopi  # ← Make sure this matches your PyPI package name
+    permissions:
+      id-token: write # Required for trusted publishing
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install -U pip
+          python -m pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist

octopi-1.2.0/.gitignore

@@ -0,0 +1,168 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Mac stuff
+.DS_Store
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# Ignore all the example notebooks
+notebooks/*.ipynb
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

octopi-1.2.0/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+repos:
+- repo: https://github.com/psf/black-pre-commit-mirror
+  rev: 23.9.1
+  hooks:
+  - id: black
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.0.292
+  hooks:
+  - id: ruff
+    args:
+    - --fix
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v4.5.0
+  hooks:
+  - id: check-toml
+  - id: check-yaml
+  - id: check-json
+  - id: check-merge-conflict
+  - id: end-of-file-fixer
+  - id: trailing-whitespace

octopi-1.2.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+    ".": "1.2.0"
+}

octopi-1.2.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## [1.2.0](https://github.com/chanzuckerberg/octopi/compare/octopi-v1.1.0...octopi-v1.2.0) (2025-08-07)
+
+
+### ✨ Features
+
+* add release-please configuration for automated releases ([#13](https://github.com/chanzuckerberg/octopi/issues/13)) ([afc2a49](https://github.com/chanzuckerberg/octopi/commit/afc2a49e972c6f2225d01b58712d9bb1da6673db))
+* model soup ([#20](https://github.com/chanzuckerberg/octopi/issues/20)) ([81e45c7](https://github.com/chanzuckerberg/octopi/commit/81e45c7b2a3422132d936ad04ba971d8e16eef90))
+
+
+### 🐞 Bug Fixes
+
+* Add docs extra for docs dependencies. ([#16](https://github.com/chanzuckerberg/octopi/issues/16)) ([14a5b65](https://github.com/chanzuckerberg/octopi/commit/14a5b655050529d5094d3eb2ebd48856ebfe2c34))
+* dynamic versioning ([#21](https://github.com/chanzuckerberg/octopi/issues/21)) ([def60ab](https://github.com/chanzuckerberg/octopi/commit/def60ab403b9c8a7b8bd5a51b8f9c079a85b38e1))
+* improvements in cli experience and localize command ([52ee7ac](https://github.com/chanzuckerberg/octopi/commit/52ee7ac2f001ffbb096fac320ab9610ca1673855))
+* setup automated releases with organization secrets ([#15](https://github.com/chanzuckerberg/octopi/issues/15)) ([a3b04cf](https://github.com/chanzuckerberg/octopi/commit/a3b04cfca8d161953b310b2a18a61995628734ec))
+
+
+### 🧹 Miscellaneous Chores
+
+* CCIE-4984 conform to open sourcing guidelines ([#19](https://github.com/chanzuckerberg/octopi/issues/19)) ([bd59cde](https://github.com/chanzuckerberg/octopi/commit/bd59cdeee4e85d6bc29e7d4151885e9a9344e508))
+
+
+### ♻️ Code Refactoring
+
+* Modularize utilities for parsing, I/O, and configuration ([#17](https://github.com/chanzuckerberg/octopi/issues/17)) ([ff54f15](https://github.com/chanzuckerberg/octopi/commit/ff54f1559077a1ef5655fb2d34c7eaf328be2caf))

octopi-1.2.0/Dockerfile

@@ -0,0 +1,19 @@
+FROM nvidia/cuda:11.8.0-runtime-ubuntu22.04
+
+# Setting working directory
+WORKDIR /usr/app
+
+# Base utilities
+RUN apt update && \
+    apt install -y python3.10-venv python3-pip git &&\
+    apt-get clean
+RUN ln -s /usr/bin/python3 /usr/bin/python
+
+# Install pip and the package
+# for now pip 25 is not supported 
+RUN pip install --upgrade "pip<25" 
+COPY . ./
+RUN pip install .
+
+#RUN python octopi/entry_points/run_optuna.py
+ENTRYPOINT ["python3", "octopi/entry_points/run_optuna.py"]

{octopi-1.0 → octopi-1.2.0}/LICENSE

@@ -17,15 +17,15 @@ copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
 The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+copies or substantial portions of the "Software".
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+OUT OF OR IN CONNECTION WITH THE "SOFTWARE" OR THE USE OR OTHER DEALINGS IN THE
+"SOFTWARE".
 ```
 
 ## License Notice for Dependencies

octopi-1.2.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: octopi
+Version: 1.2.0
+Summary: Model architecture exploration for cryoET particle picking
+Project-URL: Homepage, https://github.com/chanzuckerberg/octopi
+Project-URL: Documentation, https://chanzuckerberg.github.io/octopi/
+Project-URL: Issues, https://github.com/chanzuckerberg/octopi/issues
+Author: Jonathan Schwartz, Kevin Zhao, Daniel Ji, Utz Ermel
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.9
+Requires-Dist: copick
+Requires-Dist: copick-utils
+Requires-Dist: ipywidgets
+Requires-Dist: kaleido
+Requires-Dist: matplotlib
+Requires-Dist: mlflow
+Requires-Dist: monai
+Requires-Dist: mrcfile
+Requires-Dist: multiprocess
+Requires-Dist: nibabel
+Requires-Dist: optuna
+Requires-Dist: optuna-integration[botorch,pytorch-lightning]
+Requires-Dist: pandas
+Requires-Dist: python-dotenv
+Requires-Dist: requests
+Requires-Dist: torch-ema
+Requires-Dist: tqdm
+Provides-Extra: dev
+Requires-Dist: black>=24.8.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.8.0; extra == 'dev'
+Requires-Dist: pytest>=6.2.3; extra == 'dev'
+Requires-Dist: ruff>=0.6.4; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == 'docs'
+Requires-Dist: mkdocs-awesome-pages-plugin; extra == 'docs'
+Requires-Dist: mkdocs-git-authors-plugin; extra == 'docs'
+Requires-Dist: mkdocs-git-committers-plugin-2; extra == 'docs'
+Requires-Dist: mkdocs-git-revision-date-localized-plugin; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocs-minify-plugin; extra == 'docs'
+Requires-Dist: mkdocs-redirects; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# OCTOPI 🐙🐙🐙
+
+[![License](https://img.shields.io/pypi/l/octopi.svg?color=green)](https://github.com/chanzuckerberg/octopi/raw/main/LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/octopi.svg?color=green)](https://pypi.org/project/octopi)
+[![Python Version](https://img.shields.io/pypi/pyversions/octopi.svg?color=green)](https://www.python.org/)
+
+**O**bject dete**CT**ion **O**f **P**rote**I**ns. A deep learning framework for Cryo-ET 3D particle picking with autonomous model exploration capabilities.
+
+## 🚀 Introduction
+
+octopi addresses a critical bottleneck in cryo-electron tomography (cryo-ET) research: the efficient identification and extraction of proteins within complex cellular environments. As advances in cryo-ET enable the collection of thousands of tomograms, the need for automated, accurate particle picking has become increasingly urgent.
+
+Our deep learning-based pipeline streamlines the training and execution of 3D autoencoder models specifically designed for cryo-ET particle picking. Built on [copick](https://github.com/copick/copick), a storage-agnostic API, octopi seamlessly accesses tomograms and segmentations across local and remote environments. 
+
+## 🧩 Core Features
+
+- **3D U-Net Training**: Train and evaluate custom 3D U-Net models for particle segmentation
+- **Automatic Architecture Search**: Explore optimal model configurations using Bayesian optimization via Optuna
+- **Flexible Data Access**: Seamlessly work with tomograms from local storage or remote data portals
+- **HPC Ready**: Built-in support for SLURM-based clusters
+- **Experiment Tracking**: Integrated MLflow support for monitoring training and optimization
+- **Dual Interface**: Use via command-line or Python API
+
+## 🚀 Quick Start
+
+### Installation
+
+Octopi is availableon PyPI and can be installed using pip:
+```bash
+pip install octopi
+```
+
+⚠️ **Note**: One of the current dependencies is currently not working with pip 25. To temporarily reduce the pip version, run:
+```bash
+pip install --upgrade "pip<25"
+```
+
+### Basic Usage
+
+octopi provides two main command-line interfaces:
+
+```bash
+# Main CLI for training, inference, and data processing
+octopi --help
+
+# HPC-specific CLI for submitting jobs to SLURM clusters
+octopi-slurm --help
+```
+
+## 📚 Documentation
+
+For detailed documentation, tutorials, CLI and API reference, visit our [documentation](https://chanzuckerberg.github.io/octopi/).
+
+## 🤝 Contributing
+
+## Code of Conduct
+
+This project adheres to the Contributor Covenant [code of conduct](https://github.com/chanzuckerberg/.github/blob/master/CODE_OF_CONDUCT.md).
+By participating, you are expected to uphold this code. 
+Please report unacceptable behavior to [opensource@chanzuckerberg.com](mailto:opensource@chanzuckerberg.com).
+
+## 🔒 Security
+
+If you believe you have found a security issue, please responsibly disclose by contacting us at security@chanzuckerberg.com.
+
+