`res-`, `ppr-` (연구/논문) Repository README 작성 가이드

res-* (research) 또는 ppr-* (paper) 접두사가 붙은 저장소는 특정 학술 연구나 논문의 실험 코드를 관리합니다. README의 핵심 목표는 제3자가 해당 연구의 실험 결과를 정확하게 재현(reproduce)하고, 나아가 확장(extend)할 수 있도록 상세하고 명확한 가이드를 제공하는 것입니다.

1. 연구 개요 (Research Overview)

논문 정보 (Citation):
- 제목: 연구 논문의 전체 제목
- 저자: 모든 저자 목록
- 학회/저널: 논문이 발표된 학회나 저널 정보 (예: NeurIPS 2023)
- 링크: 논문 PDF나 arXiv 링크를 반드시 포함합니다.
- BibTeX 인용: 다른 연구자가 쉽게 인용할 수 있도록 BibTeX 형식을 제공합니다.
연구 배경 및 가설 (Background and Hypothesis):
- 이 연구가 해결하고자 하는 문제가 무엇인지 간략히 설명합니다.
- 연구를 통해 검증하고자 했던 핵심 가설을 명확히 기술합니다.

2. 실험 환경 설정 (Setup for Reproducibility)

목적: 논문에 기술된 실험 결과를 그대로 재현하는 데 필요한 모든 환경 정보를 제공합니다.
필수 구성 요소:
- 하드웨어 요구사항: GPU 종류(예: NVIDIA A100), 메모리(RAM, VRAM) 등 실험에 사용된 하드웨어 스펙을 명시합니다.
- 소프트웨어 의존성:
  - requirements.txt (Python), environment.yml (Conda) 등 패키지 목록을 제공합니다.
  - CUDA, cuDNN 버전과 같이 시스템 레벨의 의존성을 명확히 표기합니다.
  - Docker를 사용한 경우, Dockerfile과 빌드 및 실행 방법을 안내하는 것이 가장 좋습니다.
- 데이터셋 준비:
  - 원본 데이터셋을 다운로드하는 링크와 스크립트를 제공합니다.
  - 데이터 전처리가 필요한 경우, bash scripts/preprocess_data.sh 와 같이 실행 명령어를 안내하고, 예상 소요 시간을 명시합니다.

3. 실험 재현 스크립트 (Reproduction Scripts)

목적: 논문에 보고된 주요 실험 결과를 재현하는 스크립트와 실행 방법을 안내합니다.

핵심 실험별 가이드:

모델 학습 (Training):

# Table 1의 ResNet-50 모델 학습 재현
python train.py --config configs/resnet50_cifar10.yaml --output_dir results/resnet50

모델 평가 (Evaluation):

# 사전 학습된 모델 가중치로 Figure 2의 정확도 평가 재현
python evaluate.py --checkpoint_path pretrained_models/resnet50.pth --config configs/resnet50_cifar10.yaml

사전 학습된 모델 (Pre-trained Models):
- 논문에서 사용한 모델의 가중치 파일을 다운로드할 수 있는 링크(예: Google Drive, Hugging Face Hub)를 제공합니다. 이는 전체 학습 과정을 생략하고 평가만 진행하려는 사용자에게 매우 유용합니다.

4. 코드 구조 (Codebase Structure)

목적: 전체 코드베이스의 디렉토리 구조와 각 파일의 역할을 설명하여, 다른 연구자가 코드를 이해하고 수정하거나 확장하기 용이하게 만듭니다.

예시:

/
├── configs/          # 실험 설정 파일 (YAML, JSON)
├── data/             # 데이터 로더 및 전처리 코드
├── models/           # 모델 아키텍처 정의
├── scripts/          # 데이터 준비, 실험 실행 쉘 스크립트
├── src/ or lib/      # 핵심 로직 및 유틸리티 함수
├── train.py          # 모델 학습 스크립트
└── evaluate.py       # 모델 평가 스크립트

5. 기대 결과 (Expected Results)

목적: 사용자가 스크립트를 올바르게 실행했는지 확인할 수 있도록, 논문에 보고된 결과(예: 정확도, 손실 값)를 명시합니다.
팁: 특정 실험 스크립트 실행 후 출력되는 로그 예시나, 생성되는 결과 파일의 형태를 보여주면 좋습니다.

4.1 KiB Raw Blame History

res-*, ppr-* (연구/논문) Repository README 작성 가이드