Cytellect
Get your microscopy publication-ready.
プロダクト LP · 公開デモ · Windows · Docker · 統計解析手法 · ドキュメント
Cytellect は、顕微鏡画像の解析から統計処理、グラフ出力までを一貫して引き受ける生命科学研究者のための解析基盤である。インスタンスセグメンテーションには深層学習モデルの StarDist と Cellpose-SAM（SAM ViT-L）、定量と統計的推論には NumPy・SciPy・statsmodels による共通実装を用いる。
開発に参加する方へ
開発に参加するときは次の 3 つを順に読み、作業のたびに関係する節を確認すること。AI エージェントも同じ文書に従う。
- チーム開発ルール：開発の進め方、Git とレビュー、研究データの扱い
- CONTRIBUTING：開発環境の構築と起動、PR を出す前の検査
- 開発の原則：計算・統計・データ・画面・リリースで守る原則
そのほかの文書はドキュメントにまとめている。
アーキテクチャ
画像の登録から論文の図までを研究室の PC で完結させ、GPU 推論と LLM だけを外部に切り出す構成。測定値と統計は、どの実行環境でも packages/analysis の同じ実装が生成する。
解析ジョブ
apps/web Next.js。画像・測定表・統計・図を一つの画面で編集
→ services/api FastAPI。設定のバージョニングと、ジョブの永続化（SQLite）
→ services/worker リース（実行権）による排他実行。ジョブ単位のプロセス分離
→ engines/fiji 核の検出（StarDist · TensorFlow Java）
→ engines/cellpose 核小体・細胞質の検出（Cellpose-SAM · PyTorch）。CPU、またはクラウド中継経由で Modal の GPU
→ packages/analysis 測定・統計・作図（NumPy · SciPy · statsmodels · Matplotlib）
AI による解析設定
services/api → services/proposal-worker（Cloudflare Workers · D1）→ OpenAI Responses API
→ API で検証 → 設定に反映し、選んだ視野でプレビュー → 手動設定と同じジョブ
実行環境
| 環境 | 実行場所 | 構成 | 外部に送るデータ |
|---|
| Windows 版 | 研究室の PC | 専用の Python・Fiji 環境。127.0.0.1 で待ち受け | — |
| Docker 版 | 研究室の PC | Web・API・ワーカーを別コンテナで実行。ワーカーはネットワークから隔離 | — |
| GPU 推論 | Modal（L4 優先、A10 を予備候補） | GHCR の digest 固定イメージ。クラウド中継を経由して呼び出し、アイドル 20 秒でスケールダウン（infra/modal_cellpose.py） | 検出対象の 1 チャンネル、核マスク、検出の条件 |
| クラウド中継 | Cloudflare Workers · D1 | LLM と GPU 推論の中継。認証と、利用量・費用の管理（services/proposal-worker） | LLM へは、指示文・染色とチャンネルの対応・実験デザイン（視野・群・実験回の数）・画像の寸法と画素サイズ・現在の設定 |
| 公開サイト | Vercel | LP と公開デモ。main へのマージで自動デプロイ | 研究画像は受け付けない |
ディレクトリ構成
画像認識
StarDist で検出した核を親領域として、核小体・細胞質を Cellpose-SAM で検出する階層的インスタンスセグメンテーション。
1. 原画像 SHA-256 で固定。測定は常に原画素から計算
2. 核の検出 StarDist（Fiji · TensorFlow Java）
3. 背景の正規化 親領域ごとに推定し、検出用の複製にのみ適用
4. 推論 Cellpose-SAM（SAM ViT-L）。親領域による条件付き推論
5. 候補の棄却 親領域全体を覆う候補、核の境界をまたぐ候補、局所コントラストの低い候補を棄却
6. 境界の精緻化 Multi-Otsu · 距離変換 · Watershed
→ 原画像座標系の整数ラベル。核小体は親核の ID を保持
- 検出パスと測定パスの分離。前処理は検出用の複製に限定し、定量は原画素に対して行う
- 親領域による条件付き推論。基盤モデルの過検出（核全体・核外構造）を抑制する
- 実行環境の分離と固定。Fiji／TensorFlow Java と Cellpose-SAM／PyTorch を別の環境で実行し、依存パッケージとモデルの SHA-256 を読み込み前に照合する。実行時のネットワークアクセスを遮断
- CPU／GPU 間の再現性。GPU 推論は PC と同じ
runner.py とモデルを、ハッシュで固定した依存パッケージの上で、float32・TF32 無効・決定的アルゴリズムで実行する。応答に含まれる runner.py・モデル・依存のハッシュを照合し、一致しなければ採用しない。CI は、リモート推論のラベルが PC と完全に一致することを検証する
追加学習
研究者が修正した輪郭 → 教師データ → 追加学習（Cellpose-SAM）→ 評価 → 版管理（Hugging Face）
| 項目 | 内容 |
|---|
| 教師データ | 染色画像と、研究者が修正したインスタンスマスク |
| 対象 | 核小体・細胞質ごとに Cellpose-SAM を追加学習 |
| 評価 | 試料・撮影バッチ単位で分割し、境界精度・過分割・過少分割を評価 |
| 公開 | 学習データ・重み・推論条件を一組で版管理し、重みを Hugging Face で公開 |
AI による解析設定
研究目的の一文を、LLM（GPT-6.1 Sol）が検出・測定・選別・統計・図の構造化設定に変換する。LLM の責務は設定の生成に限定し、数値計算は決定的な共通実装（packages/analysis）が行う。
- データ最小化。送信するのは指示文・染色とチャンネルの対応・実験デザイン（視野・群・実験回の数）・画像の寸法と画素サイズ・現在の設定のみ。原画像・測定値・ファイル名は送信しない
- スキーマ検証。応答は Structured Outputs で受け、API 側で型・値域・チャンネルの整合性を再検証する。検証を通った設定は、選んだ視野でのプレビューを経て、手動設定と同じジョブで実行する
- コスト制御。利用額は Workers と D1 で管理し、呼び出し前に最大の費用を原子的に予約、完了後に精算する。未精算の予約も上限に算入し、障害時にも上限を超えない
統計と論文の図
- 実験単位に基づく推論。細胞・視野・試料・独立した実験を区別し、独立した実験を n として検定する。細胞を n とする擬似反復（pseudoreplication）を排除する
- 来歴（provenance）の追跡。設定・マスク・測定値・統計・図を版で関連付け、上流（輪郭）の変更は、依存する測定・統計・図を無効化する
- トレーサビリティ。図の各データ点から、算出元の画像と領域へ遡及できる
- 計算と描画の分離。体裁（色・軸）の変更は再描画のみで、測定と検定は再実行しない
- 再現可能な出力。図は SVG（文字を編集可能）・PDF（フォント埋め込み）・PNG（300 dpi）、値は CSV で出力する。論文用パッケージには、入力ハッシュ・マスク・設定・環境・再計算スクリプトを同梱する
結果の整合性
同じ入力と設定からは同じ結果を出し、古い計算が新しい結果を上書きしない。
| 性質 | 実装 |
|---|
| 冪等性 | ジョブを DB に永続化。解析の実行・図の描画・画像の登録は、要求 ID で重複を排除 |
| 排他制御 | リース（実行権）をトランザクションで直列に付与し、heartbeat と結果の確定を compare-and-swap で検証 |
| 楽観的並行性制御 | 設定・チャンネルの割り当て・採用状態の更新時に版を照合し、競合時は 409 Conflict |
| 表示の一貫性 | 結果を、視野・版・採用状態・実験デザインの識別子と結び付け、識別子が変わった結果は再描画の対象から外す。遅れて届いた応答は破棄 |
| 障害の分離 | ジョブ単位の作業ディレクトリとプロセス |
セキュリティと研究データの扱い
Cytellect は、未発表の研究データという秘匿性の高い情報を扱う。そのうえでコードを OSS として公開し、研究室の利用者がいるクラウドの機能を運用しているため、研究データの扱いとセキュリティを明文化している。
研究データはクラウドに置かず、更新は署名で検証する。そのため、クラウドのサービスやリポジトリが侵害されても、保存された研究データと利用者の PC には届かない。設計の詳細と脆弱性の報告方法は SECURITY.md にまとめている。
開発
開発環境の構築と起動の手順は CONTRIBUTING にまとめている。
This is the beginning of the README. Read the rest at the original. Read the full README ↗
