63 lines
3.6 KiB
Markdown
63 lines
3.6 KiB
Markdown
# `anl-*` (데이터 분석) Repository README 작성 가이드
|
|
|
|
`anl-*` 접두사가 붙은 저장소는 특정 데이터셋에 대한 분석 과정과 결과를 기록하는 공간입니다. README의 목표는 분석의 재현성을 보장하고, 다른 사람이 분석의 맥락, 과정, 결론을 쉽게 이해할 수 있도록 만드는 것입니다.
|
|
|
|
---
|
|
|
|
### 1. 분석 개요 (Analysis Overview)
|
|
- **연구 질문 (Research Question)**: 이 분석을 통해 답하고자 하는 핵심 질문이 무엇인지 명확하게 제시합니다.
|
|
- **주요 결과 요약 (Executive Summary)**: 분석을 통해 얻은 핵심적인 인사이트나 결론을 2~3 문장으로 요약하여 서두에 배치합니다.
|
|
- **데이터 출처 (Data Source)**: 분석에 사용된 데이터가 어디에서 왔는지 출처를 밝히고, 데이터에 접근할 수 있는 링크를 제공합니다.
|
|
|
|
### 2. 환경 설정 (Setup)
|
|
- **목적**: 다른 분석가가 동일한 환경에서 코드를 실행하고 결과를 재현할 수 있도록 안내합니다.
|
|
- **필수 정보**:
|
|
- **의존성 설치**: `requirements.txt` 또는 `environment.yml` 파일을 제공하고, 설치 방법을 안내합니다.
|
|
```bash
|
|
# pip 사용 시
|
|
pip install -r requirements.txt
|
|
|
|
# Conda 사용 시
|
|
conda env create -f environment.yml
|
|
conda activate my-analysis-env
|
|
```
|
|
- **데이터 다운로드**: 원본 데이터를 다운로드하거나, 특정 디렉토리(`data/raw/`)에 위치시키는 방법을 설명합니다.
|
|
- **환경 변수**: API 키나 데이터베이스 접속 정보 등 민감한 정보를 `.env` 파일에 설정하는 방법을 안내합니다.
|
|
|
|
### 3. 분석 과정 (Analysis Workflow)
|
|
- **목적**: 데이터 전처리부터 모델링, 시각화에 이르는 전체 분석 단계를 순서대로 설명합니다.
|
|
- **단계별 설명**:
|
|
1. **데이터 전처리 (Data Preprocessing)**:
|
|
- 스크립트: `notebooks/01_data_cleaning.ipynb`
|
|
- 설명: 결측치 처리, 이상치 제거, 변수 파생 등 수행한 작업을 간략히 기술합니다.
|
|
2. **탐색적 데이터 분석 (EDA)**:
|
|
- 스크립트: `notebooks/02_exploratory_data_analysis.ipynb`
|
|
- 설명: 데이터의 분포, 변수 간 상관관계를 파악하기 위해 수행한 분석을 설명합니다.
|
|
3. **모델링 (Modeling)**:
|
|
- 스크립트: `notebooks/03_modeling.ipynb`
|
|
- 설명: 적용한 통계 모델이나 머신러닝 알고리즘을 설명하고, 선택 이유를 기술합니다.
|
|
|
|
### 4. 주요 결과 및 시각화 (Key Results & Visualizations)
|
|
- **목적**: 분석의 핵심 결과를 시각 자료와 함께 제시하여 직관적인 이해를 돕습니다.
|
|
- **팁**:
|
|
- `matplotlib`나 `seaborn`으로 생성된 주요 그래프(예: 상관관계 히트맵, 변수 중요도 플롯) 이미지를 README에 직접 삽입합니다.
|
|
- 각 시각화 자료에 대한 해석을 덧붙여, 그래프가 의미하는 바를 설명합니다.
|
|
- **예시**:
|
|
> 아래는 피처 A와 B의 관계를 나타낸 산점도입니다. 양의 상관관계가 뚜렷하게 나타났습니다.
|
|
>
|
|
> 
|
|
|
|
### 5. 결과 재현 방법 (How to Reproduce)
|
|
- **목적**: 다른 사람이 저장소의 코드를 처음부터 끝까지 실행하여 동일한 결과를 얻는 방법을 안내합니다.
|
|
- **스크립트 실행 순서**:
|
|
```bash
|
|
# 1. 데이터 전처리 실행
|
|
python src/preprocess.py
|
|
|
|
# 2. 모델 학습 실행
|
|
python src/train_model.py
|
|
|
|
# 3. 결과 리포트 생성
|
|
# 혹은 Jupyter Notebook/Quarto를 실행하여 전체 분석을 재현
|
|
jupyter lab notebooks/
|
|
``` |