fithia2/dev/phase3_deliverables/feature_catalog.md

Feature Catalog

1. 원칙

1. feature는 반드시 point-in-time safe 해야 한다.
2. 각 feature는 as_of_ts, source, feature_version을 가진다.
3. 미래 데이터를 암묵적으로 쓰는 rolling 통계는 금지한다.
4. missing value는 명시적으로 처리하고, silent fill 금지.

2. Feature 그룹

2.1 Event features

feature	타입	설명	계산/정의	null 처리
event_type	categorical	taxonomy 기반 이벤트 종류	parser output	불가
event_direction	categorical	bullish/bearish/mixed	parser output	unknown 허용
guidance_direction	categorical	raised/inline/lowered/...	parser output	unknown 허용
quality_assessment	categorical	high/mixed/low/unknown	parser output	unknown 허용
oneoff_suspicion	categorical	none/possible/likely	parser output	unknown 허용
confidence_overall	float	parser 종합 confidence	parser output	불가
document_count	int	event에 연결된 문서 수	count	0 불가
evidence_span_count	int	핵심 필드 evidence 수	count	0 허용

2.2 Document text features

feature	타입	설명
demand_strength_score	float	backlog/bookings/orders/customers 관련 점수
pricing_power_score	float	pricing / ASP / price realization 점수
margin_strength_score	float	margin expansion 관련 점수
tone_score	float	management tone ordinal 매핑
oneoff_keyword_count	int	일회성 관련 키워드 출현 수
guidance_statement_count	int	guidance 관련 문장 수
doc_length_tokens	int	정규화 문서 토큰 수
qa_risk_flag	bool	ambiguous language 또는 parser disagreement 여부

권장 ordinal mapping 예시:

• strong_positive = +2
• mild_positive = +1
• neutral = 0
• mild_negative = -1
• strong_negative = -2
• mixed = 0

2.3 Numeric issuer features

XBRL 또는 rule parser에서 추출:

• revenue_yoy_pct
• gross_margin_yoy_delta
• operating_margin_yoy_delta
• free_cash_flow_yoy_pct
• debt_to_cash_delta
• prior_company_guidance_surprise_pct

주의:

• 컨센서스 surprise는 v1에 없음
• 회사 가이던스 대비 actual만 허용
• 분모 0 또는 누락 시 null

2.4 Market reaction features

반응일 기준:

• reaction_day_return_pct
• reaction_gap_pct
• reaction_volume_ratio_20d
• reaction_close_location
• reaction_intraday_range_pct
• reaction_close_vs_vwap (가능한 경우)
• reaction_close_vs_20d_ma
• reaction_sector_relative_return

정의:

• reaction_close_location = (close - low) / (high - low)
• reaction_volume_ratio_20d = volume / avg_volume_20d_prior

주의:

• moving average / ATR은 반드시 entry 이전 데이터만 사용

2.5 Regime features

• spy_trend_20d
• qqq_trend_20d
• sector_etf_trend_20d
• vix_level
• vix_change_1d
• fred_rate_regime_bucket

2.6 Attention features

Phase 3에서는 ingestion이 아니라 결합/정규화만 구현:

• yahoo_headline_burst_6h
• yahoo_unique_publishers_24h
• wiki_pageview_zscore_1d
• youtube_influence_score_24h
• finra_short_volume_ratio
• finra_short_ratio_zscore_20d

주의:

• attention feature는 core trigger 아님
• missing source가 있어도 학습 레코드는 유지

3. Feature naming 규칙

• snake_case
• 단위 포함 (_pct, _ratio, _count, _score)
• 날짜창 포함 (_1d, _3d, _20d)
• categorical은 값 집합 문서화 필수

4. Leakage 금지 규칙

금지 예시:

• reaction day close 후 생성되어야 하는 feature를 same-day open entry 모델에 사용
• future bar를 포함한 ATR/MA
• 거래 종료 후 게시되는 FINRA data를 당일 시초 진입 feature로 사용

필수 메타데이터:

• feature_as_of_ts
• feature_available_ts
• entry_convention

5. Feature availability by entry convention

next_open_entry

허용:

• event filing timestamp까지 공개된 정보
• reaction day 종가까지의 가격/거래량
• previous day까지의 FINRA/FRED/attention

금지:

• entry day 장중 가격
• entry day 종가

dayplus1_close_entry

허용:

• entry day 종가까지의 정보

6. Feature export 형식

Canonical feature record는 최소 아래를 포함:

• ids: event_instance_id, filing_id, symbol, reaction_date
• parser summary
• all feature columns
• availability metadata
• schema_version

Parquet 저장 시:

• 파티션: reaction_year=YYYY/reaction_month=MM
• row group은 심볼 기준보다 날짜 기준 우선