lamindb

LaminDB

概要

LaminDB は、生物学向けのオープンソースのリネージを基盤とするレイクハウスです。ローカルファイルシステム、S3、GCS、Hugging Face、SQLite、Postgres にまたがってオープンフォーマットでデータを保存しながら、データセットやモデルをクエリ可能、追跡可能、検証可能、再現可能にし、FAIR（Findable、Accessible、Interoperable、Reusable）に準拠させます。

主な価値：

• クエリ可能性：アーティファクト、レコード、実行、特徴量、スキーマ、コレクションを検索およびフィルタリングできます
• 追跡可能性：ノートブック、スクリプト、関数、パイプラインの入力、出力、パラメーター、ソースコード、環境を追跡できます
• 検証：スキーマを使って DataFrame、AnnData、SpatialData、TileDB-SOMA、Parquet、Zarr などの生物学的フォーマットをキュレーションできます
• FAIR 準拠：Bionty によるオントロジーとカスタムレジストリを使って、アノテーションを標準化できます
• 変更管理：プロジェクト、ブランチ、スペース、コレクション、保存したメモや計画を使って作業を整理できます

このスキルを使用する場面

次の場合にこのスキルを使用します。

• 生物学的データセットの管理：scRNA-seq、bulk RNA-seq、空間トランスクリプトミクス、フローサイトメトリー、マルチモーダルデータ、EHR データ
• 計算ワークフローの追跡：ノートブック、スクリプト、関数、シェルスクリプト、パイプラインの実行（Nextflow、Snakemake、Redun）
• データのキュレーションと検証：スキーマ検証、標準化、オントロジーに基づくアノテーション
• 生物学的オントロジーの活用：遺伝子、タンパク質、細胞種、組織、疾患、経路（Bionty 経由）
• データレイクハウスの構築：複数のデータセットにまたがる統一クエリインターフェース
• 再現性の確保：自動バージョン管理、リネージの追跡、環境の記録
• ML パイプラインの統合：Weights & Biases、MLflow、Hugging Face、Lightning、scVI-tools との連携
• データインフラのデプロイ：ローカルまたはクラウドベースのデータ管理システムのセットアップ
• データセットでの共同作業：標準化されたメタデータを備えた、キュレーション済みのアノテーション付きデータの共有

主な機能

LaminDB は、相互に連携する 6 つの機能領域を提供します。それぞれの詳細は references フォルダーに記載されています。

1. コア概念とデータリネージ

主なエンティティ：

• アーティファクト：バージョン管理されたデータセット（DataFrame、AnnData、Parquet、Zarr など）
• レコードと ULabels：実験エンティティ、型付きレコード、シンプルなラベル
• コレクション：バージョン管理された不変のアーティファクト集合
• 実行と変換：計算リネージの追跡（どのコードがどのデータを生成したか）
• 特徴量：アノテーションとクエリ用の型付きメタデータフィールド
• プロジェクト、ブランチ、スペース：プロジェクトのグループ化、変更管理、アクセス境界

主なワークフロー：

• ファイルまたは Python オブジェクトからアーティファクトを作成してバージョン管理する
• ln.track() と ln.finish() でノートブックやスクリプトの実行を追跡する
• @ln.flow() と @ln.step() で関数のワークフローを追跡する
• レコード、ulabel、プロジェクト、型付き特徴量でアーティファクトにアノテーションを付ける
• artifact.view_lineage() でデータリネージグラフを可視化する
• 来歴でクエリする（特定のコードや入力から生成されたすべての出力を検索する）

リファレンス： references/core-concepts.md — アーティファクト、レコード、実行、変換、特徴量、バージョン管理、リネージ追跡の詳細については、こちらをお読みください。

2. データ管理とクエリ

クエリ機能：

• 自動補完によるレジストリの探索と検索
• get()、one()、one_or_none() による単一レコードの取得
• 比較演算子（__gt、__lte、__contains、__startswith）によるフィルタリング
• Feature オブジェクトを使用した式形式のクエリを含む、特徴量ベースのクエリ
• ダブルアンダースコア構文によるレジストリ間のトラバーサル
• レジストリを横断した全文検索
• ln.Q オブジェクトを使用した高度な論理クエリ（AND、OR、NOT）
• メモリに読み込まずに大規模データセットをストリーミング

主なワークフロー：

• フィルターと並べ替えを使ったアーティファクトの参照
• 特徴量、作成日、作成者、サイズなどによるクエリ
• チャンク単位または配列スライスによる大規模ファイルのストリーミング
• 階層キーによるデータの整理
• アーティファクトのコレクションへのグループ化

リファレンス： references/data-management.md — 包括的なクエリパターン、フィルタリングの例、ストリーミング戦略、データ整理のベストプラクティスについては、こちらをお読みください。

3. アノテーションと検証

キュレーションのプロセス：

1. 検証：データセットが目的のスキーマに適合していることを確認します
2. 標準化：誤字を修正し、同義語を正規の用語に対応付けます
3. アノテーション：クエリ可能にするため、データセットをメタデータエンティティに関連付けます

スキーマの種類：

• 柔軟なスキーマ：既知の列のみを検証し、追加のメタデータを許可します
• 最小必須スキーマ：必須の列を指定し、追加の列を許可します
• 厳密なスキーマ：構造と値を完全に制御します

対応するデータ型：

• DataFrame（Parquet、CSV）
• AnnData（シングルセルゲノミクス）
• MuData（マルチモーダル）
• SpatialData（空間トランスクリプトミクス）
• TileDB-SOMA（スケーラブルな配列）

主なワークフロー：

• データ検証用の特徴量とスキーマを定義します
• 検証には DataFrameCurator、AnnDataCurator、SpatialDataCurator、または TiledbsomaExperimentCurator を使用します
• .cat.standardize() で値を標準化します
• .cat.add_ontology() でオントロジーに対応付けます
• スキーマとの関連付けを保持してキュレーション済みアーティファクトを保存します
• 特徴量で検証済みデータセットをクエリします

リファレンス： references/annotation-validation.md — 詳細なキュレーションワークフロー、スキーマ設計パターン、検証エラーへの対処、ベストプラクティスについては、こちらをお読みください。

4. 生物学的オントロジー

利用可能なオントロジー（Bionty 経由）：

• 遺伝子（Ensembl）、タンパク質（UniProt）
• 細胞型（CL）、細胞株（CLO）
• 組織（Uberon）、疾患（Mondo、DOID）
• 表現型（HPO）、経路（GO）
• 実験因子（EFO）、発生段階
• 生物（NCBItaxon）、薬剤（DrugBank）

主なワークフロー：

• bt.CellType.import_source() で公開オントロジーをインポートします
• キーワードまたは完全一致でオントロジーを検索します
• 同義語の対応付けを使用して用語を標準化します
• 階層関係（親、子、祖先）を探索します
• オントロジー用語に照らしてデータを検証します
• オントロジーレコードでデータセットにアノテーションを付けます
• カスタム用語と階層を作成します
• 複数の生物種のコンテキスト（ヒト、マウスなど）に対応します

リファレンス： references/ontologies.md — 包括的なオントロジー操作、標準化戦略、階層のナビゲーション、アノテーションワークフローについては、こちらをお読みください。

5. インテグレーション

ワークフローマネージャー：

• Nextflow：パイプラインのプロセスと出力を追跡します
• Snakemake：Snakemake のルールに統合します
• Redun：Redun のタスク追跡と組み合わせます
• Lightning：チェックポイントとトレーニングメタデータを永続化します

MLOps プラットフォーム：

• Weights & Biases：実験とデータアーティファクトを紐付けます
• MLflow：モデルと実験を追跡します
• Hugging Face：モデルのファインチューニングを追跡します
• scVI-tools：シングルセル解析のワークフロー

ストレージシステム：

• ローカルファイルシステム、AWS S3、Google Cloud Storage
• S3 互換（MinIO、Cloudflare R2）
• HTTP/HTTPS エンドポイント（読み取り専用）
• HuggingFace datasets

配列ストア：

• TileDB-SOMA（cellxgene をサポート）
• Parquet ファイルに対する SQL クエリ用の DuckDB

可視化：

• インタラクティブな空間／シングルセル可視化用の Vitessce

バージョン管理：

• ソースコード追跡のための Git 統合

参考資料： references/integrations.md - サードパーティシステムとのインテグレーションパターン、コード例、トラブルシューティングについては、こちらをお読みください。

6. セットアップとデプロイ

インストール：

• 現在の安定版ベースライン：lamindb==2.5.1（2026-06-01 リリース；Python >=3.10、<=3.14）
• 基本：uv pip install 'lamindb==2.5.1'
• 追加機能付き：uv pip install 'lamindb[gcp,zarr-v2,fcs]==2.5.1'
• 最小限の名前空間のみ：uv pip install 'lamindb-core==2.5.1'
• Bionty モジュール：LaminDB のドキュメントに含まれており、uv pip install 'bionty==2.4.0' で利用できます
• オプションモジュール：wetlab または clinical スキーマモジュールをインストールする場合は、最新の浮動バージョンではなく、レビュー済みのリリースを固定してください

インスタンスタイプ：

• ローカル SQLite（開発）
• クラウドストレージ + SQLite（小規模チーム）
• クラウドストレージ + PostgreSQL（本番環境）

ストレージオプション：

• ローカルファイルシステム
• リージョンと権限を設定可能な AWS S3
• Google Cloud Storage
• S3 互換エンドポイント（MinIO、Cloudflare R2）

設定：

• クラウドファイルのキャッシュ管理
• マルチユーザーシステムの設定
• Git リポジトリの同期
• 認証情報と接続 URL 用の名前付き環境変数

デプロイパターン：

• ローカル開発環境からクラウド本番環境への移行
• マルチリージョンデプロイ
• 個人用インスタンスでの共有ストレージ

参考資料： references/setup-deployment.md - 詳細なインストール、設定、ストレージのセットアップ、データベース管理、セキュリティのベストプラクティス、トラブルシューティングについては、こちらをお読みください。

安全性とセキュリティのデフォルト設定

LaminDB のセットアップやインテグレーションを支援する際は、次の点に注意してください。

• 実際の API キー、クラウド認証情報、データベースのパスワード、またはシークレットを含む完全な接続文字列を表示、ログ記録、送信しないでください。
• IAM ロール、ワークロードアイデンティティ、シークレットマネージャー、または LAMIN_DB_URL、AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、GOOGLE_APPLICATION_CREDENTIALS などの名前付き環境変数を優先してください。確認するのは名前付き変数の有無のみとし、値は確認しないでください。
• REST API、外部データベース、またはユーザー提供のファイルからコンテンツを保存する前に、明示的なスキーマまたはキュレーターを使用して検証し、サニタイズしてください。
• 再現可能なインストールには、パッケージのバージョンを固定するか、ロックファイルを使用してください。浮動バージョンでのインストールが許容されるのは、ユーザーが明示的に最新のアップストリームリリースを希望している場合のみです。

一般的なユースケースのワークフロー

ユースケース 1：オントロジー検証を伴うシングルセル RNA-seq 解析

import lamindb as ln
import bionty as bt
import anndata as ad

# Start tracking a notebook/script run
ln.track(params={"analysis": "scRNA-seq QC and annotation"})

# Import cell type ontology
bt.CellType.import_source()

# Load data
adata = ad.read_h5ad("raw_counts.h5ad")

# Validate and standardize cell types
adata.obs["cell_type"] = bt.CellType.standardize(adata.obs["cell_type"])

# Curate with schema
curator = ln.curators.AnnDataCurator(adata, schema)
curator.validate()
artifact = curator.save_artifact(key="scrna/validated.h5ad")

# Link ontology-backed annotations for queryability
cell_types = bt.CellType.from_values(adata.obs["cell_type"])
artifact.cell_types.add(*cell_types)

ln.finish()

ユースケース 2：クエリ可能なデータレイクハウスの構築

import lamindb as ln

# Register multiple experiments
for i, file in enumerate(data_files):
    artifact = ln.Artifact.from_anndata(
        ad.read_h5ad(file),
        key=f"scrna/batch_{i}.h5ad",
        description=f"scRNA-seq batch {i}"
    ).save()

    # Annotate with features
    artifact.features.set_values({
        "batch": i,
        "tissue": tissues[i],
        "condition": conditions[i]
    })

# Query across all experiments by annotated features
immune_datasets = ln.Artifact.filter(
    key__startswith="scrna/",
    tissue="PBMC",
    condition="treated"
).to_dataframe()

# Load specific datasets
for artifact in immune_datasets:
    adata = artifact.load()
    # Analyze

ユースケース 3：W&B 統合を伴う ML パイプライン

import lamindb as ln
import wandb

# Initialize both systems
wandb.init(project="drug-response", name="exp-42")
ln.track(params={"model": "random_forest", "n_estimators": 100})

# Load training data from LaminDB
train_artifact = ln.Artifact.get(key="datasets/train.parquet")
train_data = train_artifact.load()

# Train model
model = train_model(train_data)

# Log to W&B
wandb.log({"accuracy": 0.95})

# Save model in LaminDB with W&B linkage
import joblib
joblib.dump(model, "model.pkl")
model_artifact = ln.Artifact("model.pkl", key="models/exp-42.pkl").save()
model_artifact.features.set_values({"wandb_run_id": wandb.run.id})

ln.finish()
wandb.finish()

ユースケース 4：Nextflow パイプラインの統合

# In Nextflow process script
import lamindb as ln

ln.track()

# Load input artifact
input_artifact = ln.Artifact.get(key="raw/batch_${batch_id}.fastq.gz")
input_path = input_artifact.cache()

# Process (alignment, quantification, etc.)
# ... Nextflow process logic ...

# Save output
output_artifact = ln.Artifact(
    "counts.csv",
    key="processed/batch_${batch_id}_counts.csv"
).save()

ln.finish()

ネイティブの Nextflow プロジェクトでは、利用可能な場合は nf-lamin プラグインと最新の nextflow.config パターンを優先してください。小規模なパイプラインステップやカスタムのパイプラインステップでは、インライン Python による追跡を使用してください。

はじめに確認するチェックリスト

LaminDB を効果的に使い始めるには、次の手順に従ってください。

1. インストールとセットアップ（references/setup-deployment.md）

   • バージョンを固定した LaminDB と必要な追加パッケージをインストールします
   • lamin login で認証します
   • lamin init --storage ... でインスタンスを初期化します

2. 基本概念を学ぶ（references/core-concepts.md）

   • Artifact、Record、Run、Transform を理解します
   • Artifact の作成と取得を練習します
   • ワークフローに ln.track()/ln.finish() または @ln.flow()/@ln.step() を実装します

3. クエリを使いこなす（references/data-management.md）

   • レジストリのフィルタリングと検索を練習します
   • 特徴量ベースのクエリと式形式のフィルタについて学びます
   • 大容量ファイルのストリーミングを試します

4. バリデーションを設定する（references/annotation-validation.md）

   • 研究分野に関連する特徴量を定義します
   • データ型のスキーマを作成します
   • キュレーションワークフローを練習します

5. オントロジーを統合する（references/ontologies.md）

   • 関連する生物学的オントロジー（遺伝子、細胞型など）をインポートします
   • 既存のアノテーションを検証します
   • オントロジーの用語を使ってメタデータを標準化します

6. ツールを接続する（references/integrations.md）

   • 既存のワークフローマネージャーと統合します
   • 実験の追跡用に ML プラットフォームを連携します
   • クラウドストレージとコンピューティング環境を設定します

主要な原則

LaminDB を使うときは、次の原則に従ってください。

1. すべてを追跡する：解析のたびに最初に ln.track() を使い、リネージを自動的に記録します

2. 早い段階で検証する：大規模な解析に着手する前に、スキーマを定義してデータを検証します

3. オントロジーを使う：公開されている生物学的オントロジーを活用し、アノテーションを標準化します

4. キーで整理する：Artifact のキーを階層的に構成します（例：project/experiment/batch/file.h5ad）

5. まずメタデータをクエリする：大容量ファイルを読み込む前に、フィルタリングと検索を行います

6. 重複させずにバージョン管理する：変更のたびに新しいキーを作成するのではなく、組み込みのバージョン管理を使います

7. 特徴量でアノテーションする：型付きの特徴量を定義し、クエリ可能なメタデータには artifact.features.set_values() を使います

8. 十分にドキュメント化する：Artifact、スキーマ、Transform に説明を追加します

9. リネージを活用する：view_lineage() を使ってデータの来歴を把握します

10. ローカルから始め、クラウドへ拡張する：SQLite でローカル開発し、PostgreSQL を使ってクラウドにデプロイします

リファレンスファイル

このスキルには、機能別に整理された包括的なリファレンスドキュメントが含まれています。

• references/core-concepts.md - Artifact、Record、Run、Transform、特徴量、バージョン管理、リネージ
• references/data-management.md - クエリ、フィルタリング、検索、ストリーミング、データ整理
• references/annotation-validation.md - スキーマ設計、キュレーションワークフロー、検証戦略
• references/ontologies.md - 生物学的オントロジーの管理、標準化、階層構造
• references/integrations.md - ワークフローマネージャー、MLOps プラットフォーム、ストレージシステム、ツール
• references/setup-deployment.md - インストール、設定、デプロイ、トラブルシューティング

作業に必要な LaminDB の機能に応じて、関連するリファレンスファイルを読んでください。

その他のリソース

• 公式ドキュメント：https://docs.lamin.ai
• API リファレンス：https://docs.lamin.ai/api
• GitHub リポジトリ：https://github.com/laminlabs/lamindb
• チュートリアル：https://docs.lamin.ai/tutorial
• FAQ：https://docs.lamin.ai/faq

エージェントの作業手順

1. 環境を確認します。 Python 環境とライブラリのバージョン（python -c "import pkg; print(pkg.__version__)"）を確認し、データの形状、型、欠損値を調べます。
2. 入力を明確にします。 データまたはユーザーに確認し、形式、識別子、パラメーターを確定します。結果を左右する値は推測せず、質問してください。
3. まず小規模に実行します。 まずサンプルまたは単一のフォールドで実行し、実行時間とメモリ使用量を確認します。
4. 上記の指示と参考情報を使用して、タスク全体を実行します。
5. 結果を検証します。 ホールドアウトデータ、固定した乱数シード、適切な指標を使用し、データリークを確認して、不確実性（信頼区間、シード間の標準偏差）を報告します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確定の事項を明記します。

このような場合	対応
メモリ不足、または実行が非常に遅い	サブサンプリング、チャンク処理や遅延計算の利用、モデルサイズの縮小を行い、変更内容をユーザーに伝えます。
インストール済みバージョンに、この指示に記載された関数、フラグ、エンドポイントがない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して対応し、ユーザーに伝えます。API を決して捏造しないでください。
必須の入力、識別子、パラメーターが曖昧	ユーザーに質問するか、実行前に仮定を明示します。

誠実性に関するルール

• 結果、パラメーター、識別子、引用、統計値を決して捏造しないでください。実行または検証できない場合は、その旨を明確に伝えます。
• このセッションで計算していない指標は決して報告しないでください。すべての数値について、その算出に使ったコードの経路を示します。
• ここに記載されたバージョン固有の詳細は古くなっている可能性があるものとして扱い、インストール済みバージョンの公式ドキュメントで確認します。
• 費用が発生する、共有 GPU やクラウドのクォータを消費する、個人情報や患者データを扱う、または元に戻せない操作を行う場合は、事前に許可を求めます。

関連スキル

• qdrant-vector-search：RAG とセマンティック検索向けの高性能なベクトル類似性検索エンジン。