재현 가능한 분석 패키지

이 토픽을 마치면

환경 lock, seed, input hash, schema, source accession, 실행 로그를 하나의 manifest로 연결할 수 있습니다. “코드가 있다”와 “같은 분석을 다시 확인할 수 있다”를 구분합니다.

분석은 코드 하나가 아니다

재현 가능한 분석에는 코드뿐 아니라 입력 데이터, 버전, 변환 규칙, 실행 환경, 출력과 provenance가 필요합니다. Python packaging 문서의 환경·의존성 관리 원칙을 프로젝트에 맞게 적용하되, lock 파일 하나가 데이터 권리와 연구설계를 해결한다고 쓰지 않습니다.

manifest 구조

analysis_id
topic_id
input_sha256
schema_version
requirements_lock
random_seed
source_accession
transformations
output_path
verification_status

seed는 난수 예시를 다시 만들기 위한 정보이고, 입력·라이브러리·하드웨어·코드 전체의 동일성을 보장하는 단독 증거가 아닙니다. raw input은 덮어쓰지 않고 변환 출력과 hash를 별도로 보존합니다.

권장 패키지 구조

analysis-package/
├── README.md
├── manifest.tsv
├── requirements-lock.txt
├── data/
│   ├── provenance/
│   └── normalized/
├── src/
├── tests/
└── outputs/

README에는 실행 순서와 입력 요구사항을 적고, manifest는 파일별 hash와 상태를 기록합니다. src에는 변환·분석 코드를, tests에는 핵심 API와 결과 계약을 둡니다. output을 손으로 수정했다면 코드 실행 결과와 구분할 수 있도록 별도 기록이 필요합니다.

재현과 검증의 차이

같은 코드가 같은 결과를 만들면 계산 재현성은 확인할 수 있습니다. 그러나 입력의 측정 타당성, 연구설계의 적절성, 결과의 생물학적 해석까지 검증된 것은 아닙니다. 재현 가능한 패키지는 검토 가능한 경로를 제공하며, 과학적 판단을 대신하지 않습니다.

패키지를 동결할 때에는 manifest 자체의 hash도 기록합니다. 이후 파일이 바뀌면 새 버전을 만들고, 이전 승인본을 조용히 덮어쓰지 않습니다.

권리와 citation

GEO·ENCODE 같은 repository를 사용할 때 accession과 공식 citation을 기록합니다. 공개 접근과 재배포 권한은 분리하며, 권리가 불명확한 원본은 파일을 콘텐츠에 포함하지 않고 공식 접근 경로만 안내할 수 있습니다.

연구 질문으로 돌아가 해석하기

manifest는 결과를 더 과학적으로 만드는 마법이 아니라, 결과가 어떤 입력과 가정에 의존했는지 검토하게 하는 전달 구조입니다. 실행이 재현돼도 측정의 타당성과 인과가 자동 증명되지는 않습니다.

핵심 정리

• 환경·입력·변환·출력·출처를 함께 기록합니다.
• seed만으로 재현성이 완성되지 않습니다.
• accession·citation·license·redistribution을 구분합니다.

다음 토픽으로

마지막 편에서는 결과·한계·윤리·접근성을 독자에게 전달합니다.

참고 자료

• Python Packaging User Guide: https://packaging.python.org/en/latest/
• NCBI GEO: https://www.ncbi.nlm.nih.gov/geo/info/
• ENCODE citing guidance: https://www.encodeproject.org/help/citing-encode/

본 편의 manifest와 예시는 BioStatPy가 독립적으로 작성했습니다.