README.md

---
title: CreateDataSet
emoji: 🐠
colorFrom: gray
colorTo: green
sdk: gradio
sdk_version: 6.6.0
app_file: app.py
pinned: false
---

# CreateDataSet

나스닥/뉴욕증권거래소(US) 티커의 일봉 데이터를 수집해 Hugging Face Dataset으로 업로드하는 Gradio 앱입니다.

## 버튼 로직 설명

이 앱의 핵심 동작은 아래 2개 버튼으로 실행됩니다.

---

## 1) `👀 티커 목록 미리보기`

UI 연결:

- `preview_btn.click(fn=preview_tickers, inputs=[], outputs=[output_log])`

실행 함수:

- `preview_tickers()`

내부 로직:

1. `get_all_us_tickers()` 호출
2. 야후 스크리너(`yf.screen`)로 거래소별 티커 수집
   - NASDAQ: `NMS`, `NGM`, `NCM`
   - NYSE: `NYQ`
3. 티커 필터 적용
   - `-`, `.`, `$` 포함 티커 제외
   - 5글자이며 마지막이 `W`, `R`, `U`인 파생성 티커 제외
4. 중복 제거 + 정렬
5. 로그 텍스트 반환
   - 나스닥 개수
   - 뉴욕증권거래소 개수
   - 전체 개수
   - 각 거래소 앞 20개 샘플 티커

특징:

- 실제 데이터 수집/업로드는 수행하지 않고, 수집 대상 티커 목록만 빠르게 확인합니다.
- 결과는 오른쪽 `로그 출력` 텍스트박스에 표시됩니다.

---

## 2) `🚀 파이프라인 시작`

UI 연결:

- `start_btn.click(fn=run_pipeline, inputs=[hf_token_input, all_dataset_input, recent_dataset_input, batch_size_input, period_input, checkpoint_batch_input], outputs=[output_log])`

실행 함수:

- `run_pipeline(hf_token, all_dataset_name, recent_dataset_name, batch_size, period, checkpoint_batch_size, progress=gr.Progress())`

사전 조건:

- `HF_TOKEN`이 필요합니다.
- 토큰이 없으면 즉시 실패 메시지를 반환하고 종료합니다.

단계별 로직:

1. **티커 목록 수집**
   - `get_all_us_tickers()` 호출
   - 전체 대상 티커 개수 계산
2. **기존 데이터셋 로드 + 재개 대상 계산**
   - 기존 `all`, `30d` 데이터셋 로드 시도
   - 이미 수집된 티커를 제외하고 이번 실행 대상 티커만 계산
3. **티커별 가격 데이터 수집**
   - 각 티커에 대해 `fetch_ticker_data(ticker)` 실행
   - `yf.Ticker(ticker).history(period=period, interval="1d")` 호출
   - 컬럼 정리: `Ticker`, `Date`, `Open`, `High`, `Low`, `Close`, `Volume`
   - 숫자 컬럼 반올림(소수점 4자리)
   - 장중 미확정 종가 제외 로직 적용
     - 뉴욕 시간 기준
     - 마감 확정 전(today) 데이터는 제외
   - 실패 시 최대 3회 재시도
   - 10티커마다 0.5초 대기(호출 차단 완화)
   - 설정한 간격(`checkpoint_batch_size`)마다 수집 버퍼를 Parquet 청크로 업로드
   - 청크 업로드 후 메모리 버퍼를 즉시 비워 메모리 사용량을 제한
4. **최종 병합 반영**
   - 마지막 미반영 버퍼를 청크 업로드로 반영
5. **최근 30일 데이터셋 갱신**
   - 티커별 최근 30일 데이터 청크를 함께 업로드
6. **Hugging Face 업로드**
   - 내부적으로 `HfApi.upload_file(..., path_in_repo="data/chunks/...parquet")` 방식 사용
   - 대용량 전체 데이터프레임 재업로드를 피해서 메모리 피크를 낮춤
7. **완료 로그 반환**
   - 시작/종료 시간, 성공/실패 개수, 업로드 결과를 텍스트로 반환

진행률(Progress Bar):

- 수집 시작: `0`
- 데이터 병합: `0.9`
- 30일 필터링: `0.93`
- 업로드: `0.95`
- 완료: `1.0`

---

## 3) `⚡ 실시간 시작`

UI 연결:

- `realtime_btn.click(fn=run_realtime_update, inputs=[hf_token_input, all_dataset_input, recent_dataset_input], outputs=[output_log])`

실행 함수:

- `run_realtime_update(hf_token, all_dataset_name, recent_dataset_name, progress=gr.Progress())`

핵심 목적:

- 데이터셋에 이미 등록된 티커들을 기준으로 TradingView Screener에서 오늘 데이터를 일괄 조회
- `all` 데이터셋: 오늘 데이터 **추가만(append-only)**
- `30d` 데이터셋: 오래된 데이터 제거 후 오늘 데이터 반영

단계별 로직:

1. **장중 여부 확인 (썸머타임 자동 반영)**
   - `America/New_York` 기준 시간으로 정규장(09:30~16:00) 여부 판단
   - 장중이면 로그에 **`장중입니다.`** 출력
2. **기존 데이터셋 로드**
   - HF Hub에서 `all`, `30d` 데이터셋 로드
   - 조회 티커는 우선 `30d`의 `Ticker` 목록 사용 (없으면 `all` 사용)
3. **오늘 데이터 중복 수집 체크**
   - `all` 데이터셋에서 오늘 날짜(뉴욕 기준) 행 확인
   - 대상 티커가 모두 오늘 날짜로 이미 존재하면 **`이미 수집했습니다`** 출력 후 종료
4. **TradingView 일괄 조회**
   - Yahoo가 아닌 `https://scanner.tradingview.com/america/scan` 사용
   - 티커별 `NASDAQ/NYSE/AMEX` 심볼을 함께 조회
   - 수신 컬럼: `close/open/high/low/volume`
5. **`all` 업데이트 (추가만)**
   - 오늘 데이터가 없는 티커만 신규 행으로 추가
6. **`30d` 업데이트 (교체+정리)**
   - 같은 티커의 오늘 행은 최신 값으로 교체
   - 티커별 최근 30일만 유지하도록 필터링
7. **HF 업로드**
   - `all`, `30d` 두 데이터셋을 각각 push

---

## 입력값 설명

- `허깅페이스 토큰 (HF_TOKEN)`
  - 데이터셋 업로드 인증용
- `전체기간 데이터셋 이름 (all)`
  - 예: `username/us-stocks-daily-all`
- `최근 30일 데이터셋 이름 (30d)`
  - 예: `username/us-stocks-daily-30d`
- `로그 출력 배치 크기`
  - 몇 개 티커마다 중간 진행 로그를 남길지 설정
- `조회 기간 (Yahoo period)`
  - 예: `max`, `10y`, `5y`, `2y`, `1y`, `6mo`, `3mo`, `1mo`
  - 파이프라인 실행 시간을 줄이고 싶다면 `max` 대신 더 짧은 기간을 선택
- `중간 업로드 간격 (티커 수)`
  - 예: `100`이면 100개 티커 처리마다 중간 업로드
  - `0`이면 중간 업로드 없이 마지막에 한 번만 업로드

재실행(Resume) 동작:

- 이미 데이터셋에 존재하는 티커는 자동으로 스킵합니다.
- 이전 실행에서 중간에 실패해도, 다음 실행 시 남은 티커 위주로 이어서 수집합니다.
- 체크포인트 간격(예: 100) 기준으로 저장되므로, 실패 시 최근 체크포인트 이후 구간만 재수집됩니다.

---

## 참고

- Hugging Face Spaces 설정 레퍼런스:
  - https://huggingface.co/docs/hub/spaces-config-reference