연구 결과를 재현할 수 있는 자료 묶음을 만드는 방법
데이터, 코드, README와 예상 결과를 하나로 묶고 빈 폴더에서 실행해 검증합니다. 한국어 안내가 포함된 예제와 공유 전 점검표를 제공합니다.
재현성 자료 묶음에는 무엇이 들어가나요?
재현성 자료 묶음(reproducibility package)은 보고한 결과를 다시 계산하는 데 필요한 입력, 코드, 실행 환경 설명, README와 비교용 예상 결과를 모은 것입니다. 논문 파일만 전달하면 동료는 어떤 데이터와 명령으로 표를 만들었는지 추측해야 합니다. 연구 전체를 한꺼번에 정리하기 어렵다면 표 하나를 다시 만드는 작은 묶음부터 시작하세요.
학습 시간 재현성 예제 ZIP 다운로드. 압축을 풀면 study-sessions/ 폴더가 생깁니다. 한국어 설명은 README.ko.md, 한국어 데이터 사전은 data/data-dictionary.ko.md에 있습니다. 기본 README.md는 영어입니다. 네 행의 입력은 계산 연습용 모의 데이터이며 실제 연구 관측값이 아닙니다.
| 파일 | 동료가 확인할 내용 |
|---|---|
README.ko.md | 목적, 실행 위치와 명령, 검증한 환경 |
data/sessions.csv | 분석에 사용한 입력 |
data/data-dictionary.ko.md | 열의 의미, 단위와 결측값 규칙 |
analysis/analyze.py | 소리 환경별 평균을 계산하는 절차 |
expected/means.csv | 실행 결과와 비교할 기준 표 |
results/means.csv는 실행 후 생성됩니다. 입력과 비교 기준을 생성 결과와 구분해 보관하세요. 자신의 연구에서는 데이터 사전과 실행 환경 기록을 실제 파일에 맞게 작성합니다.
공유할 수 있는 자료인지 먼저 확인하기
데이터, 코드, 문서와 그림의 이용 조건을 각각 확인하세요. 저장소에 라이선스가 있다고 모든 외부 자료에 자동으로 같은 조건이 적용되지는 않습니다. 자신의 묶음에는 각 자료의 출처, 적용 라이선스와 접근 조건을 적으세요.
입력을 공개할 수 없다면 권한 있는 연구자가 어디에서 어떤 버전을 신청할 수 있는지 설명하세요. 누구나 실행할 수 있도록 모의 데이터를 제공할 때는 실제 분석과 달라진 점도 표시합니다. 모의 데이터로 성공한 실행이 비공개 원자료의 결과까지 검증한 것은 아닙니다.
배포할 파일에 비밀번호, API 키, 참여자 식별 정보, 비공개 메모가 없는지 살펴보세요. Git 저장소 자체를 공유한다면 과거 커밋도 배포 범위에 포함됩니다. .gitignore에 추가하는 것만으로 이미 기록된 내용이 사라지지는 않습니다.
빈 폴더에서 README만 보고 실행하기
- 이전에 사용한 결과물이 없는 빈 폴더에 ZIP을 새로 풉니다.
README.ko.md를 읽고 터미널에서study-sessions/로 이동합니다.- Python 3 버전을 확인하고 아래 명령을 실행합니다. 외부 패키지는 필요하지 않습니다.
- 새로 생성된 표를
expected/means.csv와 비교합니다.
python --version
python analysis/analyze.py
환경에서 Python 3의 명령이 python3이면 두 명령 모두 바꾸세요. Windows에서 Python 런처를 사용한다면 py -3도 가능합니다. 정상 실행 시 Wrote results/means.csv가 표시되고 결과 표는 다음과 같아야 합니다.
condition,mean_minutes
background-noise,20.0
quiet,25.0
배경 소음 환경은 (15 + 25) ÷ 2 = 20.0분, 조용한 환경은 (20 + 30) ÷ 2 = 25.0분입니다. 다시 실행하면 생성된 표를 덮어씁니다. 이 차이로 소음의 효과를 판단할 수는 없습니다. 다른 분석에서는 난수나 수치 계산 특성에 맞춰 비교 기준과 허용 오차를 정하세요.
실제 연구를 배포할 때는 검증한 코드 커밋 ID, 데이터 버전과 환경을 기록하고 그 버전을 받을 수 있는 링크를 제공하세요. 계속 바뀌는 브랜치의 최신 파일만 가리키면 나중에 같은 상태를 찾기 어렵습니다.
동료에게 5분 인수인계해 보기
동료에게 새로 받은 예제 또는 자신의 작은 프로젝트를 건네며 “README만 보고 이 표를 다시 만들 수 있나요?”라고 물어보세요. 따로 설명하기 전에 동료가 멈추거나 추측한 지점을 기록하고, 그 부분을 README에 보완합니다. 5분은 짧은 점검을 위한 시간이며 모든 연구가 그 안에 실행된다는 뜻은 아닙니다.
혼자 점검한다면?
작업 폴더를 닫고 새로 압축을 푼 사본에서 시작하세요. 파일을 찾지 못하면 프로젝트 최상위에서 실행했는지, data/sessions.csv가 있는지 확인하세요. 출력이 다르면 입력 버전과 수정한 코드부터 비교합니다. 예상 결과를 새 결과로 덮어써서 차이를 숨기지 마세요.
배포 전 최종 점검표
- README에 재현할 결과, 실행 위치와 시작 명령이 적혀 있습니다.
- 입력 데이터 또는 접근 절차와 데이터 사전을 찾을 수 있습니다.
- 코드 커밋 ID, 데이터 버전과 검증한 실행 환경이 기록되어 있습니다.
- 예상 결과와 비교 방법이 있고 빈 폴더에서 실제로 실행했습니다.
- 자료별 라이선스와 접근 조건을 확인하고 비공개 정보를 제외했습니다.
이 다섯 항목을 확인했다면 시리즈의 핵심 과정을 하나로 연결한 것입니다. 자신의 연구에서는 가장 중요한 결과 하나부터 적용하고, 실행하는 사람이 실제로 필요한 정보를 조금씩 보완하세요.
자료에서 결과까지의 흐름을 그림으로 설명하기
단계가 여러 개라면 Miss Formula의 AI Diagram Generator로 입력 데이터 → 분석 스크립트 → 결과 표 → 독립적인 확인 과정을 그려 보세요. 각 상자에 실제 파일 경로를 적으면 동료가 README와 대조하기 쉽습니다. 그림은 실행 가능한 코드와 설명을 보완하며, 분석이 올바르다는 검증을 대신하지는 않습니다.
참고 자료
이 글은 The Turing Way Community가 CC BY 4.0로 공개한 내용을 참고·각색했습니다. Miss Formula는 학습 순서를 재구성하고 설명, 예제 및 연습 문제를 추가했습니다.