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개의 상호 연결된 기능 영역을 제공하며, 각 영역은 참조 폴더에 자세히 문서화되어 있습니다.

1. 핵심 개념 및 데이터 계보

핵심 엔터티:

• 아티팩트: 버전이 있는 데이터셋 (DataFrame, AnnData, Parquet, Zarr 등)
• 레코드 및 ULabel: 실험 엔터티, 타입이 지정된 레코드 및 간단한 레이블
• 컬렉션: 버전이 있는 불변 아티팩트 집합
• 실행 및 변환: 컴퓨테이셔널 계보 추적 (어떤 코드가 어떤 데이터를 생성했는지)
• 기능: 주석 및 쿼리를 위한 타입이 지정된 메타데이터 필드
• 프로젝트, 브랜치 및 공간: 프로젝트 그룹화, 변경 관리 및 액세스 경계

주요 워크플로우:

• 파일 또는 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 데이터셋

배열 저장소:

• 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

# 노트북/스크립트 실행 추적 시작
ln.track(params={"analysis": "scRNA-seq QC and annotation"})

# 세포 유형 온톨로지 가져오기
bt.CellType.import_source()

# 데이터 로드
adata = ad.read_h5ad("raw_counts.h5ad")

# 세포 유형 검증 및 표준화
adata.obs["cell_type"] = bt.CellType.standardize(adata.obs["cell_type"])

# 스키마로 큐레이션
curator = ln.curators.AnnDataCurator(adata, schema)
curator.validate()
artifact = curator.save_artifact(key="scrna/validated.h5ad")

# 쿼리 가능하도록 온톨로지 기반 주석 연결
cell_types = bt.CellType.from_values(adata.obs["cell_type"])
artifact.cell_types.add(*cell_types)

ln.finish()

사용 사례 2: 쿼리 가능한 데이터 레이크하우스 구축

import lamindb as ln

# 여러 실험 등록
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()

    # 기능으로 주석 달기
    artifact.features.set_values({
        "batch": i,
        "tissue": tissues[i],
        "condition": conditions[i]
    })

# 주석이 달린 기능으로 모든 실험 쿼리
immune_datasets = ln.Artifact.filter(
    key__startswith="scrna/",
    tissue="PBMC",
    condition="treated"
).to_dataframe()

# 특정 데이터셋 로드
for artifact in immune_datasets:
    adata = artifact.load()
    # 분석

사용 사례 3: W&B 통합을 사용한 ML 파이프라인

import lamindb as ln
import wandb

# 두 시스템 초기화
wandb.init(project="drug-response", name="exp-42")
ln.track(params={"model": "random_forest", "n_estimators": 100})

# LaminDB에서 훈련 데이터 로드
train_artifact = ln.Artifact.get(key="datasets/train.parquet")
train_data = train_artifact.load()

# 모델 훈련
model = train_model(train_data)

# W&B에 로깅
wandb.log({"accuracy": 0.95})

# W&B 링크와 함께 LaminDB에 모델 저장
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 파이프라인 통합

# Nextflow 프로세스 스크립트 내
import lamindb as ln

ln.track()

# 입력 아티팩트 로드
input_artifact = ln.Artifact.get(key="raw/batch_${batch_id}.fastq.gz")
input_path = input_artifact.cache()

# 처리 (정렬, 정량화 등)
# ... Nextflow 프로세스 로직 ...

# 출력 저장
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)

   • 아티팩트, 레코드, 실행, 변환 이해
   • 아티팩트 생성 및 검색 연습
   • 워크플로우에 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. 온톨로지를 사용하십시오: 표준화된 주석을 위해 공용 생물학적 온톨로지를 활용하십시오