Merge pull request #67 from boostcampaitech7/feat-062/write-readme

feat-062/write-readme #62

README.md

@@ -0,0 +1,52 @@
+# 수도권 아파트 전세가 예측 AI 대회
+
+## 💡Team (사진)
+
+|강현구|서동준|이도걸|이수미|최윤혜|
+|:---:|:---:|:---:|:---:|:---:|
+|<img src="" width="150" height="150"/>|<img src="" width="150" height="150"/>|<img src="" width="150" height="150"/>|<img src="" width="150" height="150"/>|<img src="" width="150" height="150"/>|
+|각자 한 것|각자 한 것|각자 한 것|각자 한 것|각자 한 것|
+
+</br>
+
+## 💻Introduction
+아파트는 한국에서 중요한 자산이며, 가계 자산의 70% 이상을 차지합니다. 특히 전세 시장은 매매 시장과 밀접하게 연관되어 부동산 정책 수립과 시장 예측의 중요한 지표가 됩니다. 이번 대회의 목표는 단순한 가격 예측을 넘어, 부동산 시장의 정보 비대칭성을 해소하는 것입니다.
+
+대회의 성능 평가는 **Mean Absolute Error (MAE)** 지표로 진행되며, 리더보드와 최종 순위는 MAE를 기준으로 결정됩니다.
+
+</br>
+
+## 💾Datasets
+제공된 데이터셋은 아파트 전세 실거래가 예측을 목표로 합니다. 학습 데이터는 모델 훈련에 사용되며, 테스트 데이터는 모델 성능 평가 및 실제 예측에 사용됩니다.
+- **train.csv**: 대회 훈련용 데이터 (1,801,228개의 행)
+- **test.csv**: 대회 추론용 데이터 (150,172개의 행)
+- **sample_submission.csv**: 정답 제출용 샘플 데이터 (150,172개의 행)
+- **subwayInfo.csv**: 위도와 경도로 이루어진 지하철 위치 정보 (700개의 행)
+- **interestRate.csv**: 연월로 이루어진 금리 정보 (66개의 행)
+- **schoolInfo.csv**: 위도와 경도로 이루어진 학교 정보 (11,992개의 행)
+- **parkInfo.csv**: 위도, 경도, 면적으로 이루어진 공원 정보 (17,564개의 행)
+
+
+</br>
+
+## ⭐Project Summary
+
+
+</br>
+
+## 📑Wrap-up Report
+[RecSys_Level2_RecSys_팀 리포트(02조).pdf]()
+
+
+</br>
+
+## 📂Architecture
+```
+
+            
+```
+
+## ⚒️Development Environment
+- 서버 스펙 : AI Stage GPU (Tesla V100)
+- 협업 툴 : Github / Zoom / Slack / Google Drive 
+- 기술 스택 : Python / Scikit-Learn / Scikit-Optimize / Pandas / Numpy / MySQL

dataloader/README.md

@@ -0,0 +1,7 @@
+# dataloader 폴더 설명서
+이 폴더에는 학습, 검증에 사용할 데이터 셋을 불러오는 함수가 포함되어 있습니다. 각 스크립트의 용도와 내부 함수는 아래와 같습니다.
+
+## dataloader.py
+데이터 셋을 불러옵니다.
+- **함수 목록**
+  - data_loader : 주어진 데이터셋 이름에 따라 학습 및 테스트 데이터를 로드합니다. 데이터 로드 후 전처리 작업으로, 특정 열을 제거하고, 결측치를 처리하며, 열 이름에서 특수 문자를 제거합니다.

dataset/README.md

@@ -0,0 +1,36 @@
+# dataset 폴더 설명서
+이 폴더에는 데이터 셋에 새로운 feature를 추가하는 다양한 함수들이 포함되어 있습니다. 각 스크립트의 용도와 내부 함수는 아래와 같습니다.
+
+## merge_data.py
+- **함수 목록**
+  - _type: train/test
+  - contract_date: 계약 날짜
+  - contract_year: 계약 연도
+  - contract_month: 계약 월
+  - transaction_count: 거래량
+  - nearest_park_distance: 가장 가까운 공원까지의 거리
+  - park_count_500m: 500m 반경 내 공원 수
+  - total_park_area_500m: 500m 반경 내 공원 총 면적
+  - park_count_1000m: 1000m 반경 내 공원 수
+  - total_park_area_1000m: 1000m 반경 내 공원 총 면적
+  - park_count_2000m: 2000m 반경 내 공원 수
+  - total_park_area_2000m: 2000m 반경 내 공원 총 면적
+  - weighted_park_score: 가중 공원 점수
+  - avg_distance_5_parks: 5개의 가장 가까운 공원까지의 평균 거리
+  - park_distance_skewness: 공원 거리의 왜도(NaN 값 1127개)
+  - park_distance_kurtosis: 공원 거리의 첨도(NaN 값 1127개)
+  - nearest_large_park_distance: 가장 가까운 대형 공원까지의 거리
+  - large_park_count_3km: 3km 반경 내 대형 공원 수
+  - large_park_count_5km: 5km 반경 내 대형 공원 수
+  - large_park_count_10km: 10km 반경 내 대형 공원 수
+  - total_large_park_area_10km: 10km 반경 내 대형 공원 총 면적
+  - nearest_subway_distance_km: 가장 가까운 지하철까지의 거리
+  - nearest_subway_latitude: 가장 가까운 지하철의 위도
+  - nearest_subway_longitude: 가장 가까운 지하철의 경도
+  - school_count_within_1km: 1km 반경 내 학교 수
+  - closest_elementary_distance: 가장 가까운 초등학교까지의 거리
+  - closest_middle_distance: 가장 가까운 중학교까지의 거리
+  - closest_high_distance: 가장 가까운 고등학교까지의 거리
+  - deposit_mean: 전세가 월별 평균(이자율 반영)
+  - interest_rate: 이자율
+  - interest_rate_diff: 이자율 변화량

models/README.md

@@ -0,0 +1,84 @@
+# 모델 구현 가이드
+
+이 저장소는 여러 모델 클래스를 포함하고 있으며, 각각은 공통된 구조를 따릅니다. 이 가이드는 모든 모델이 동일한 패턴을 따르도록 하여, 모델을 쉽게 교체하거나 앙상블 할 수 있도록 돕기 위해 작성되었습니다.
+
+## 기본 모델 클래스 구조
+
+각 모델 클래스는 아래에 설명된 동일한 구조를 따라야 합니다. 클래스는 초기화 시 파라미터를 받아들이고, 학습, 예측 라벨, 예측 확률을 위한 메서드를 포함합니다.
+
+### 클래스 템플릿
+
+```python
+class ModelName:
+    def __init__(self, model_type, params):
+        self.model = None  # 모델 객체를 저장할 변수
+        self.model_type = model_type # 모델 타입
+        self.params = params  # 전달받은 파라미터 저장
+
+    def train(self, x_train, y_train, x_valid=None, y_valid=None):
+        """
+        주어진 학습 데이터를 이용해 모델을 학습합니다.
+        
+        Args:
+            x_train: 학습 데이터 특징(feature)들
+            y_train: 학습 데이터 라벨(label)
+            x_valid: 검증 데이터 특징
+            y_valid: 검증 데이터 라벨
+        
+        Returns:
+            없음
+        """
+        if self.model_type == "classifier":
+            model = Classifier(**self.params)
+        elif self.model_type == "regressor":
+            model = Regressor(**self.params)
+        if x_valid is None or y_valid is None:
+            model.fit(x_train, y_train)
+        else:
+            model.fit(x_train, y_train, eval_set=[(x_valid, y_valid)])
+        self.model = model
+
+    def predict_proba(self, x_valid):
+        """
+        주어진 검증 데이터에 대해 클래스 확률을 예측합니다.
+        
+        Args:
+            x_valid: 검증 데이터 특징
+        
+        Returns:
+            각 클래스에 대한 예측 확률 값
+        """
+        if self.model is None:
+            raise ValueError("먼저 모델을 학습시키세요.")
+
+        y_valid_pred = self.model.predict_proba(x_valid)
+        return y_valid_pred
+
+    def predict(self, x_valid):
+        """
+        주어진 검증 데이터에 대해 클래스 라벨을 예측합니다.
+        
+        Args:
+            x_valid: 검증 데이터 특징
+        
+        Returns:
+            예측된 클래스 라벨
+        """
+        if self.model is None:
+            raise ValueError("먼저 모델을 학습시키세요.")
+
+        pred = self.model.predict(x_valid)
+        return pred
+
+    def feature_importance(self):
+        """
+        모델에 대한 feature importance 결과를 Return 합니다..
+        
+        Args:
+        
+        Returns:
+            모델 feature importance
+        """
+        if self.model is None:
+            raise ValueError("Train first")
+        return self.model.feature_importances_

utils/README.md

@@ -0,0 +1,38 @@
+# Utils 폴더 설명서
+
+이 폴더에는 프로젝트 전반에 걸쳐 사용되는 다양한 유틸리티 함수들이 포함되어 있습니다. 각 스크립트의 용도와 내부 함수는 아래와 같습니다.
+
+
+
+## clustering.py
+클러스터링 방법(DBSCAN, K-means++) 및 그 결과를 시각화하는 도구를 제공합니다.
+- **함수 목록**
+  - check_k_distances: DBSCAN을 위한 최적의 epsilon 값을 k-거리 그래프를 사용하여 탐색.
+  - check_silhouette_score: DBSCAN 클러스터링 결과에 대한 실루엣 점수를 계산.
+  - apply_dbscan: 주어진 DataFrame에 DBSCAN 클러스터링 적용.
+  - initialize_centroids: 데이터에서 랜덤하게 k개의 센트로이드를 초기화.
+  - assign_clusters: 각 데이터 포인트를 가장 가까운 센트로이드에 할당.
+  - update_centroids: 현재 클러스터 할당을 기반으로 새로운 센트로이드를 업데이트.
+  - k_means_plus: K-means++ 알고리즘 실행.
+  - visualize_result: 위도와 경도를 기반으로 클러스터링 결과를 2D로 시각화.
+
+
+## data_split.py
+데이터셋을 무작위 또는 시간 기반으로 학습 및 검증 세트로 분할하는 기능을 제공합니다.
+- **함수 목록**
+  - data_split: 지정된 방식에 따라 학습 및 검증 세트로 데이터 분할.
+
+
+## load_params.py
+특정 모델과 유형에 맞는 하이퍼파라미터를 YAML 파일에서 불러오는 기능을 제공합니다.
+- **함수 목록**
+  - load_params: 모델 이름과 유형에 따라 하이퍼파라미터를 불러옴.
+
+
+## mysql.py
+MySQL 데이터베이스와의 연결 및 데이터 삽입을 관리하는 클래스를 제공합니다.
+- **함수 목록**
+  - db_connect: MySQL 데이터베이스에 연결.
+  - db_disconnect: MySQL 데이터베이스 연결을 종료.
+  - db_insert: 특정 테이블에 데이터를 삽입.
+