MultiFactor 0.2.5__tar.gz → 0.2.6__tar.gz

{multifactor-0.2.5 → multifactor-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MultiFactor
-Version: 0.2.5
+Version: 0.2.6
 Summary: 멀티팩터 기반 주식 데이터 수집 패키지
 Author-email: HANHO <hanhoman@gmail.com>
 Classifier: Programming Language :: Python :: 3
@@ -17,8 +17,8 @@ Requires-Dist: yfinance
 
 # MultiFactor 📈
 
-**MultiFactor**는 국내상장주식(코스피/코스닥)을 대상으로 멀티팩터(Multi-Factor) 전략을 손쉽게 적용하고, 팩터별 점수 및 종합 순위를 산출해 주는 파이썬 패키지입니다. 
-종목별 주가와 재무 데이터 수집은 `FinanceDataReader`를 기반으로 구동됩니다. 
+**MultiFactor**는 국내상장주식(코스피/코스닥)뿐만 아니라 미국주식(NYSE, NASDAQ)을 대상으로 멀티팩터(Multi-Factor) 전략을 손쉽게 적용하고, 팩터별 점수 및 종합 순위를 산출해 주는 파이썬 패키지입니다. 
+종목별 주가와 재무 데이터 수집은 FinanceDataReader와 yfinance를 기반으로 구동됩니다. 
 
 <br>
 
@@ -36,15 +36,14 @@ Requires-Dist: yfinance
 <br>
 
 ## ✨ 주요 기능
-* **국내 주식 멀티팩터 데이터 제공:** 가치, 모멘텀, 퀄리티 지표 및 이를 합산한 종합 점수 산출
+* **국내 및 미국 주식 멀티팩터 데이터 제공:** 가치, 모멘텀, 퀄리티 지표 및 이를 합산한 종합 점수 산출
 
 | 구분 | 주요 기능 | 함수명 |
 | -------- | -------- | -------- |
-| 종목 정보 수집     | 시가총액 기준 상위 종목들의 기본 정보(종목코드, 종목명, 시가총액, 업종, 최근 종가 등)를 수집합니다. | get_stockinfo()  |
+| 종목 정보 수집     | 지정한 시장(KR/US)의 시가총액 기준 상위 종목들의 기본 정보(종목코드, 종목명, 시가총액, 업종, 최근 종가 등)를 수집합니다. | get_stockinfo()  |
 | 멀티팩터 종합점수    | 종목별 멀티팩터 세부 지표 점수와 종합 점수, 그리고 전체 순위를 산출합니다. | get_score()  |
 | 투자스타일별 종합점수    | 3가지 투자 스타일(안정추구, 추세성장, 역발상 등)에 맞춰 가중치가 조정된 멀티팩터 종합 점수를 제공합니다. | get_score_adj_weight()  |
 | 종합점수 그룹화    | 산출된 종합 점수를 바탕으로 전체 종목을 N개의 그룹으로 분류하고, 그룹별 종목명을 출력합니다.| get_Ngroup()  |
-| 특정 종목 팩터 조회  | 단일 종목에 대한 개별 팩터(모멘텀, 밸류, 퀄리티) 값을 빠르게 조회합니다. | get_momentum_one() <br> get_value_one() <br>  get_quality_one()  |
 
 
 * **투자 유형별 가중치 조절한 멀티팩터 데이터 제공 :** 투자 스타일에 맞춘 3가지 모델 제공
@@ -73,28 +72,35 @@ Requires-Dist: yfinance
 ### 1. 패키지 불러오기 
 다음 코드로 멀티팩터 패키지를 불러옵니다. 
 ```python
-from MultiFactor import MultiFactorKR
+# 국내주식 
+from MultiFactor import MultiFactorKR 
+
+# 미국주식
+from MultiFactor import MultiFactorUS
 ```
 
 <br>
 
 ### 2. 멀티팩터 객체 생성  
-멀티팩터 객체 생성 시, 수집 대상 종목 수(N)를 반드시 지정해야 합니다. N은 시가총액 상위 순으로 N개까지 종목을 수집함을 의미합니다. N이 커질수록 데이터 수집 시간이 길어지므로, 초기 테스트에는 종목수(N)를 5~50 사이로 지정한 후 차츰 늘려가기를 권장합니다. 
+멀티팩터 객체 생성 시 수집 대상 종목 수(`N`)를 지정합니다. N이 커질수록 데이터 수집 시간이 길어지므로, 초기 테스트에는 5~50 사이로 지정한 후 차츰 늘려가기를 권장합니다. 
 ```python
-mf = MultiFactorKR(N=50)  # 시가총액 상위 50개 종목 
+# 국내 시가총액 상위 50개 종목
+mf_kr = MultiFactorKR(N=50)
+  
+# 미국 시가총액 상위 50개 종목 
+mf_us = MultiFactorUS(N=50)  
 ```
 <br>
 
 ### 3. 종목 정보 수집 
-멀티팩터 객체에서 지정한 종목수(N) 만큼 종목 정보 데이터를 생성합니다. 반환되는 데이터 형식은 데이터프레임(기본값) 또는 딕셔너리로 지정할 수 있습니다. 
+멀티팩터 객체에서 지정한 종목수(N) 만큼 종목 정보 데이터를 생성합니다. 
 
+(1) 국내주식
 ```python
-# 종목 코드 정보 생성 (데이터프레임)
-df = mf.get_stockinfo() 
-
-# 종목코드, 종목명, 시가총액 출력 (최초 5건) 
+df = mf_kr.get_stockinfo() 
 df[['Code', 'Name', 'Marcap']].head()   
 ```
+
 <table border="1" class="dataframe">
   <thead>
     <tr style="text-align: right;">
@@ -139,41 +145,82 @@ df[['Code', 'Name', 'Marcap']].head()
 </table>
 
 
+2. 미국 주식
 ```python
-# 종목 코드 정보 생성 (딕셔너리) 
-stock_list = mf.get_stockinfo(dtype='dic')  # {'종목코드': '종목명'}
-print(stock_list)
+df = mf_us.get_stockinfo() 
+df[['Code', 'Name', 'MarketCap']].head()   
+```
 
-# {'005930': '삼성전자', '000660': 'SK하이닉스', '005380': '현대차', ... }
-``` 
+<table border="1" class="dataframe">
+  <thead>
+    <tr style="text-align: right;">
+      <th></th>
+      <th>Code</th>
+      <th>Name</th>
+      <th>MarketCap</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <th>0</th>
+      <td>NVDA</td>
+      <td>NVIDIA</td>
+      <td>4819905000000</td>
+    </tr>
+    <tr>
+      <th>1</th>
+      <td>GOOGL</td>
+      <td>Alphabet Inc. (Class A) Communication</td>
+      <td>4064833940000</td>
+    </tr>
+    <tr>
+      <th>2</th>
+      <td>GOOG</td>
+      <td>Alphabet Inc. (Class C) Communication</td>
+      <td>4025518690000</td>
+    </tr>
+    <tr>
+      <th>3</th>
+      <td>AAPL</td>
+      <td>Apple Inc.</td>
+      <td>3867012276000</td>
+    </tr>
+    <tr>
+      <th>4</th>
+      <td>MSFT</td>
+      <td>Microsoft</td>
+      <td>3120694875480</td>
+    </tr>
+  </tbody>
+</table>
 
-<br>
 
+<br>
 
-### 4.멀티팩터 종합 점수 데이터 수집
-```get_score```함수로 멀티팩터 종합점수 데이터를 간단하게 생성할 수 있습니다. 다음 코드는 시가총액 상위 10개 종목의 종합 점수를 추출하여 파이썬 데이터프레임(df)에 저장합니다.
 
-```python 
-from MultiFactor import MultiFactorKR
-mf = MultiFactorKR(N=10) 
-df = mf.get_score()
-```
+### 4. 멀티팩터 종합 점수 데이터 수집
+`get_score` 함수로 멀티팩터 종합점수 데이터를 간단하게 생성할 수 있습니다. 동일한 함수로 한국과 미국 시장 모두 분석이 가능합니다.
 
-이 데이터프레임 안에는 분석에 필요한 총 23개의 컬럼(열)이 담겨 있습니다. 컬럼은 크게 4개 유형을 구분할 수 있습니다. 
+이 데이터프레임 안에는 분석에 필요한 총 23개의 컬럼(열)이 담겨 있습니다. 컬럼은 크게 4개 유형으로 구분됩니다. 
 
-- 종목정보 : 종목코드, 종목명
+- 종목정보 : 종목코드(티커), 종목명
 - 종합지표 원본 : 모멘텀 주가, 모멘텀 거래량, PER, PBR, 매출 증가율, 영업이익 증가율, 순이익 증가율, ROE 
-- 종합지표 순위 :종합 지표 원본 데이터를 추출된 N개 종목 내에서의 상대 순위로 환산한 값
+- 종합지표 순위 : 종합 지표 원본 데이터를 추출된 N개 종목 내에서의 상대 순위로 환산한 값
 - 종합점수/순위 : 종합 지표 순위들의 평균값 및 이를 바탕으로 매긴 최종 순위
 
+<br>
 
 <b>① 종합지표 원본 추출 예시</b>
 
-종합지표 원본 데이터를 출력하여 결과를 해석합니다. 
+(1) 국내주식
 
 ```python
+mf_kr = MultiFactorKR(N=10) 
+df = mf_kr.get_score()
+
 cols = ['scode', 'sname', 'mom_price', 'mom_vol', 'PER', 'PBR', 
         'revenue_rate', 'oper_income_rate', 'net_income_rate', 'ROE']
+
 df[cols].head()
 ```
 
@@ -263,12 +310,114 @@ df[cols].head()
 </table>
 
 
- 
-<b>② 종합지표 순위 추출 예시</b>
+(2) 미국주식
 
 ```python
+mf_us = MultiFactorUS(N=10) 
+df = mf_us.get_score()
+
+cols = ['scode', 'sname', 'mom_price', 'mom_vol', 'PER', 'PBR', 
+        'revenue_rate', 'oper_income_rate', 'net_income_rate', 'ROE']
+
+df[cols].head()
+```
+<table border="1" class="dataframe">
+  <thead>
+    <tr style="text-align: right;">
+      <th></th>
+      <th>scode</th>
+      <th>sname</th>
+      <th>mom_price</th>
+      <th>mom_vol</th>
+      <th>PER</th>
+      <th>PBR</th>
+      <th>revenue_rate</th>
+      <th>oper_income_rate</th>
+      <th>net_income_rate</th>
+      <th>ROE</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <th>0</th>
+      <td>MSFT</td>
+      <td>Microsoft</td>
+      <td>7</td>
+      <td>17</td>
+      <td>26</td>
+      <td>8</td>
+      <td>17</td>
+      <td>0</td>
+      <td>60</td>
+      <td>34</td>
+    </tr>
+    <tr>
+      <th>1</th>
+      <td>NVDA</td>
+      <td>Nvidia</td>
+      <td>28</td>
+      <td>-6</td>
+      <td>41</td>
+      <td>31</td>
+      <td>73</td>
+      <td>1</td>
+      <td>96</td>
+      <td>101</td>
+    </tr>
+    <tr>
+      <th>2</th>
+      <td>AVGO</td>
+      <td>Broadcom</td>
+      <td>42</td>
+      <td>-4</td>
+      <td>79</td>
+      <td>24</td>
+      <td>30</td>
+      <td>0</td>
+      <td>32</td>
+      <td>33</td>
+    </tr>
+    <tr>
+      <th>3</th>
+      <td>GOOGL</td>
+      <td>Alphabet Inc. (Class A)</td>
+      <td>31</td>
+      <td>-20</td>
+      <td>32</td>
+      <td>10</td>
+      <td>18</td>
+      <td>0</td>
+      <td>31</td>
+      <td>36</td>
+    </tr>
+    <tr>
+      <th>4</th>
+      <td>GOOG</td>
+      <td>Alphabet Inc. (Class C)</td>
+      <td>30</td>
+      <td>-22</td>
+      <td>31</td>
+      <td>10</td>
+      <td>18</td>
+      <td>0</td>
+      <td>31</td>
+      <td>36</td>
+    </tr>
+  </tbody>
+</table>
+
+<br>
+
+<b>② 종합지표 순위 예시</b>
+
+(1) 국내주식 
+```python
+mf_kr = MultiFactorKR(N=10) 
+df = mf_kr.get_score()
+
 cols = ['scode', 'sname', '모멘텀_주가', '모멘텀_거래량', '밸류_PER', '밸류_PBR', 
         '퀄리티_ROE', '퀄리티_매출증가', '퀄리티_영업이익증가', '퀄리티_순이익증가']
+
 df[cols].head()
 ```
 <table border="1" class="dataframe">
@@ -357,10 +506,111 @@ df[cols].head()
 </table>
 
 
+(2) 미국주식 
+```python
+mf_us = MultiFactorUS(N=10) 
+df = mf_us.get_score()
+
+cols = ['scode', 'sname', '모멘텀_주가', '모멘텀_거래량', '밸류_PER', '밸류_PBR', 
+        '퀄리티_ROE', '퀄리티_매출증가', '퀄리티_영업이익증가', '퀄리티_순이익증가']
+
+df[cols].head()
+```
+<table border="1" class="dataframe">
+  <thead>
+    <tr style="text-align: right;">
+      <th></th>
+      <th>scode</th>
+      <th>sname</th>
+      <th>모멘텀_주가</th>
+      <th>모멘텀_거래량</th>
+      <th>밸류_PER</th>
+      <th>밸류_PBR</th>
+      <th>퀄리티_ROE</th>
+      <th>퀄리티_매출증가</th>
+      <th>퀄리티_영업이익증가</th>
+      <th>퀄리티_순이익증가</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <th>0</th>
+      <td>MSFT</td>
+      <td>Microsoft</td>
+      <td>90</td>
+      <td>10</td>
+      <td>20</td>
+      <td>40</td>
+      <td>50</td>
+      <td>60</td>
+      <td>20</td>
+      <td>20</td>
+    </tr>
+    <tr>
+      <th>1</th>
+      <td>NVDA</td>
+      <td>Nvidia</td>
+      <td>40</td>
+      <td>70</td>
+      <td>80</td>
+      <td>90</td>
+      <td>20</td>
+      <td>10</td>
+      <td>10</td>
+      <td>10</td>
+    </tr>
+    <tr>
+      <th>2</th>
+      <td>AVGO</td>
+      <td>Broadcom</td>
+      <td>10</td>
+      <td>60</td>
+      <td>90</td>
+      <td>80</td>
+      <td>60</td>
+      <td>20</td>
+      <td>30</td>
+      <td>30</td>
+    </tr>
+    <tr>
+      <th>3</th>
+      <td>GOOGL</td>
+      <td>Alphabet Inc. (Class A)</td>
+      <td>20</td>
+      <td>80</td>
+      <td>50</td>
+      <td>60</td>
+      <td>35</td>
+      <td>45</td>
+      <td>75</td>
+      <td>45</td>
+    </tr>
+    <tr>
+      <th>4</th>
+      <td>GOOG</td>
+      <td>Alphabet Inc. (Class C)</td>
+      <td>30</td>
+      <td>90</td>
+      <td>40</td>
+      <td>50</td>
+      <td>35</td>
+      <td>45</td>
+      <td>75</td>
+      <td>45</td>
+    </tr>
+  </tbody>
+</table>
+
+<br>
 
 <b>③ 종합점수/순위 추출 예시</b>
 
+(1) 국내주식 
+
 ```python
+mf_kr = MultiFactorKR(N=10) 
+df = mf_kr.get_score()
+
 cols = ['scode', 'sname', '종합점수', '종합순위', '종합순위_퍼센트']
 df[cols].head()
 ```
@@ -420,25 +670,89 @@ df[cols].head()
 </table>
 
 
-<br>
+(2) 미국주식 
+```python
+mf_us = MultiFactorUS(N=10) 
+df = mf_us.get_score()
 
-### 5. 투자 스타일별 종합점수 출력 
+cols = ['scode', 'sname', '종합점수', '종합순위', '종합순위_퍼센트']
+df[cols].head()
+```
+<table border="1" class="dataframe">
+  <thead>
+    <tr style="text-align: right;">
+      <th></th>
+      <th>scode</th>
+      <th>sname</th>
+      <th>종합점수</th>
+      <th>종합순위</th>
+      <th>종합순위_퍼센트</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <th>0</th>
+      <td>MSFT</td>
+      <td>Microsoft</td>
+      <td>39</td>
+      <td>1</td>
+      <td>10</td>
+    </tr>
+    <tr>
+      <th>1</th>
+      <td>NVDA</td>
+      <td>Nvidia</td>
+      <td>41</td>
+      <td>2</td>
+      <td>20</td>
+    </tr>
+    <tr>
+      <th>2</th>
+      <td>AVGO</td>
+      <td>Broadcom</td>
+      <td>48</td>
+      <td>3</td>
+      <td>30</td>
+    </tr>
+    <tr>
+      <th>3</th>
+      <td>GOOGL</td>
+      <td>Alphabet Inc. (Class A)</td>
+      <td>51</td>
+      <td>4</td>
+      <td>45</td>
+    </tr>
+    <tr>
+      <th>4</th>
+      <td>GOOG</td>
+      <td>Alphabet Inc. (Class C)</td>
+      <td>51</td>
+      <td>4</td>
+      <td>45</td>
+    </tr>
+  </tbody>
+</table>
 
-3가지로 분류된 투자 유형별로 멀티팩터 종합 점수 데이터를 생성할 수 있습니다. 
+<br>
 
-```python
-# 시가총액 상위 100 종목 멀티팩터 종합점수 추출 
-mf = MultiFactorKR(N=100)  
-df = mf.get_score()  
-``` 
+### 5. 투자 스타일별 종합점수 출력 
 
+3가지로 분류된 투자 유형별로 가중치를 조절한 멀티팩터 점수를 산출합니다. 국내와 미국 시장 모두 동일하게 적용 가능합니다.
 
-① 가치 성장 전략 : 밸류 + 퀄리티 조합
+<b>① 가치 성장 전략 : 밸류 + 퀄리티 조합</b>
 
+(1) 국내주식 
 ```python
+# 시가총액 상위 100종목 
+mf_kr = MultiFactorKR(N=100)  
+df = mf_kr.get_score()
+
+# 가치성장 전략 적용
 df = mf.get_score_adj_weight(df, weight='가치성장') 
+
 df[['scode', 'sname', '종합점수', '종합순위']].head()  
 ```
+
 <table border="1" class="dataframe">
   <thead>
     <tr style="text-align: right;">
@@ -489,12 +803,83 @@ df[['scode', 'sname', '종합점수', '종합순위']].head()
 </table>
 
 
-② 추세 성장 전략 : 모멘텀 + 퀄리티 조합
+(2) 미국주식
+```python
+# 시가총액 상위 100종목 
+mf_us = MultiFactorUS(N=100)  
+df = mf_us.get_score()
+
+# 가치성장 전략 적용
+df = mf.get_score_adj_weight(df, weight='가치성장') 
+
+df[['scode', 'sname', '종합점수', '종합순위']].head()  
+```
+<table border="1" class="dataframe">
+  <thead>
+    <tr style="text-align: right;">
+      <th></th>
+      <th>scode</th>
+      <th>sname</th>
+      <th>종합점수</th>
+      <th>종합순위</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <th>0</th>
+      <td>MU</td>
+      <td>Micron Technology</td>
+      <td>19</td>
+      <td>1</td>
+    </tr>
+    <tr>
+      <th>1</th>
+      <td>MS</td>
+      <td>Morgan Stanley</td>
+      <td>30</td>
+      <td>2</td>
+    </tr>
+    <tr>
+      <th>2</th>
+      <td>BLK</td>
+      <td>BlackRock</td>
+      <td>30</td>
+      <td>3</td>
+    </tr>
+    <tr>
+      <th>3</th>
+      <td>NVDA</td>
+      <td>Nvidia</td>
+      <td>32</td>
+      <td>4</td>
+    </tr>
+    <tr>
+      <th>4</th>
+      <td>SCHW</td>
+      <td>Charles Schwab Corporation</td>
+      <td>33</td>
+      <td>5</td>
+    </tr>
+  </tbody>
+</table>
+
+<br>
+
+<b>② 추세 성장 전략 : 모멘텀 + 퀄리티 조합</b>
 
+
+(1) 국내주식 
 ```python
+# 시가총액 상위 100종목 
+mf_kr = MultiFactorKR(N=100)  
+df = mf_kr.get_score()
+
+# 추세성장 전략 적용
 df = mf.get_score_adj_weight(df, weight='추세성장') 
-df[['scode', 'sname', '종합점수', '종합순위']].head()   
+
+df[['scode', 'sname', '종합점수', '종합순위']].head()  
 ```
+
 <table border="1" class="dataframe">
   <thead>
     <tr style="text-align: right;">
@@ -545,11 +930,17 @@ df[['scode', 'sname', '종합점수', '종합순위']].head()
 </table>
 
 
-③ 역발상 전략 : 밸류 + 모멘텀 조합
 
+(2) 미국주식
 ```python
-df = mf.get_score_adj_weight(df, weight='역발상') 
-df[['scode', 'sname', '종합점수', '종합순위']].head()   
+# 시가총액 상위 100종목 
+mf_us = MultiFactorUS(N=100)  
+df = mf_us.get_score()
+
+# 추세성장 전략 적용
+df = mf.get_score_adj_weight(df, weight='추세성장') 
+
+df[['scode', 'sname', '종합점수', '종합순위']].head()  
 ```
 <table border="1" class="dataframe">
   <thead>
@@ -564,190 +955,216 @@ df[['scode', 'sname', '종합점수', '종합순위']].head()
   <tbody>
     <tr>
       <th>0</th>
-      <td>000880</td>
-      <td>한화</td>
-      <td>16</td>
+      <td>APP</td>
+      <td>AppLovin</td>
+      <td>14</td>
       <td>1</td>
     </tr>
     <tr>
       <th>1</th>
-      <td>039490</td>
-      <td>키움증권</td>
-      <td>19</td>
+      <td>NVDA</td>
+      <td>Nvidia</td>
+      <td>16</td>
       <td>2</td>
     </tr>
     <tr>
       <th>2</th>
-      <td>006800</td>
-      <td>미래에셋증권</td>
-      <td>19</td>
+      <td>MU</td>
+      <td>Micron Technology</td>
+      <td>21</td>
       <td>3</td>
     </tr>
     <tr>
       <th>3</th>
-      <td>047040</td>
-      <td>대우건설</td>
-      <td>20</td>
+      <td>PLTR</td>
+      <td>Palantir Technologies</td>
+      <td>23</td>
       <td>4</td>
     </tr>
     <tr>
       <th>4</th>
-      <td>071050</td>
-      <td>한국금융지주</td>
-      <td>22</td>
-      <td>6</td>
+      <td>ORCL</td>
+      <td>Oracle Corporation</td>
+      <td>26</td>
+      <td>5</td>
     </tr>
   </tbody>
 </table>
 
 <br>
 
-### 6. 종합점수별 그룹화 출력
-get_Ngroup() 함수를 사용하면 전체 종목을 원하는 개수의 그룹으로 깔끔하게 묶어 요약할 수 있습니다.
+<b>③ 역발상 전략 : 밸류 + 모멘텀 조합</b>
 
-```python
-mf = MultiFactorKR(N=100)
-df = mf.get_score()  
-mf.get_Ngroup(df, Ngroup=10)  # 종합점수 상위 순 10개 그룹으로 분류
-
-# [출력 결과]
-# 1 : SK스퀘어, SK하이닉스, 삼성E&A, HD현대, 에이피알, 한국금융지주, 삼성전자, LG이노텍, 키움증권, LS ELECTRIC
-# 2 : 효성중공업, NH투자증권, 이수페타시스, 삼성물산, 삼성증권, HD현대일렉트릭, LG씨엔에스, LS, HD한국조선해양, 현대건설
-# 3 : 코오롱티슈진, 한화, 고려아연, 하나금융지주, JB금융지주, 미래에셋증권, KB금융, 삼천당제약, 기업은행, 엘앤에프
-# 4 : DB손해보험, 기아, 한전기술, 셀트리온, 우리금융지주, 펩트론, BNK금융지주, 대우건설, 한국항공우주, 현대글로비스
-# 5 : 삼성생명, 신한지주, HD현대중공업, 한화에어로스페이스, 현대모비스, 한화솔루션, 현대차, 삼양식품, 삼성카드, 에이비엘바이오
-# 6 : SK바이오팜, LG유플러스, 한미약품, S-Oil, GS, KT, 한화오션, 삼성화재, 두산, 삼성전기
-# 7 : SK텔레콤, 카카오뱅크, 한국전력, 한국타이어앤테크놀로지, HMM, 삼성중공업, 포스코인터내셔널, SK, 현대로템, 카카오페이
-# 8 : 대한항공, 현대오토에버, CJ, LIG넥스원, 삼성SDI, HD건설기계, HD현대마린솔루션, 두산에너빌리티, 크래프톤, 하이브
-# 9 : HLB, 삼성에스디에스, KT&G, 아모레퍼시픽, 유한양행, 한화시스템, SK이노베이션, LG전자, 삼성에피스홀딩스, NAVER
-# 10 : LG, 레인보우로보틱스, 한미반도체, POSCO홀딩스, LG에너지솔루션, 카카오, LG화학, 삼성바이오로직스, 한진칼, 포스코퓨처엠
-```
-
-<br>
-
-### 7. 개별 지표 데이터 수집
-특정 팩터의 데이터만 개별적으로 추출할 수 있습니다.
 
+(1) 국내주식 
 ```python
-# 개별 팩터 데이터 추출 (인자로 stock_list 딕셔너리 주입)
-data_mom = mf.get_momentum(stock_list)
-data_val = mf.get_value(stock_list)
-data_fin = mf.get_quality(stock_list)
+# 시가총액 상위 100종목 
+mf_kr = MultiFactorKR(N=100)  
+df = mf_kr.get_score()
 
-# 추출한 개별 팩터 데이터를 조합하여, 종합 점수 산정
-data_mast_custom = mf.get_score_by_data(data_mom, data_val, data_fin)
-```
-
-<br>
-
-
-### 8. 특정 종목 팩터 값 조회
-개별 종목(예: 삼성전자 '005930')의 팩터 점수만 빠르게 확인하고 싶을 때 활용합니다.
+# 역발상 전략 적용
+df = mf.get_score_adj_weight(df, weight='역발상') 
 
-```python
-# 삼성전자의 모멘텀 데이터
-mf.get_momentum_one('005930')
+df[['scode', 'sname', '종합점수', '종합순위']].head()  
 ```
 <table border="1" class="dataframe">
   <thead>
     <tr style="text-align: right;">
       <th></th>
       <th>scode</th>
-      <th>mom_price</th>
-      <th>mom_vol</th>
+      <th>sname</th>
+      <th>종합점수</th>
+      <th>종합순위</th>
     </tr>
   </thead>
   <tbody>
     <tr>
       <th>0</th>
-      <td>005930</td>
-      <td>62.531321</td>
-      <td>-40.739685</td>
+      <td>000880</td>
+      <td>한화</td>
+      <td>16</td>
+      <td>1</td>
     </tr>
-  </tbody>
-</table>
-
-```python
-# 삼성전자의 밸류 데이터
-mf.get_value_one('005930')
-```
-<table border="1" class="dataframe">
-  <thead>
-    <tr style="text-align: right;">
-      <th></th>
-      <th>scode</th>
-      <th>PER</th>
-      <th>PBR</th>
+    <tr>
+      <th>1</th>
+      <td>039490</td>
+      <td>키움증권</td>
+      <td>19</td>
+      <td>2</td>
     </tr>
-  </thead>
-  <tbody>
     <tr>
-      <th>0</th>
-      <td>005930</td>
-      <td>17.89</td>
-      <td>1.82</td>
+      <th>2</th>
+      <td>006800</td>
+      <td>미래에셋증권</td>
+      <td>19</td>
+      <td>3</td>
+    </tr>
+    <tr>
+      <th>3</th>
+      <td>047040</td>
+      <td>대우건설</td>
+      <td>20</td>
+      <td>4</td>
+    </tr>
+    <tr>
+      <th>4</th>
+      <td>071050</td>
+      <td>한국금융지주</td>
+      <td>22</td>
+      <td>6</td>
     </tr>
   </tbody>
 </table>
 
+(2) 미국주식
 ```python
-# 삼성전자의 퀄리티 데이터
-mf.get_quality_one('005930') 
+# 시가총액 상위 100종목 
+mf_us = MultiFactorUS(N=100)  
+df = mf_us.get_score()
+
+# 역발상 전략 적용
+df = mf.get_score_adj_weight(df, weight='역발상') 
+
+df[['scode', 'sname', '종합점수', '종합순위']].head()  
 ```
 <table border="1" class="dataframe">
   <thead>
     <tr style="text-align: right;">
       <th></th>
       <th>scode</th>
-      <th>revenue_rate</th>
-      <th>oper_income_rate</th>
-      <th>net_income_rate</th>
-      <th>ROE</th>
+      <th>sname</th>
+      <th>종합점수</th>
+      <th>종합순위</th>
     </tr>
   </thead>
   <tbody>
     <tr>
       <th>0</th>
-      <td>005930</td>
-      <td>9.03503</td>
-      <td>64.997</td>
-      <td>60.659103</td>
-      <td>10.78</td>
+      <td>GS</td>
+      <td>Goldman Sachs</td>
+      <td>17</td>
+      <td>1</td>
+    </tr>
+    <tr>
+      <th>1</th>
+      <td>BAC</td>
+      <td>Bank of America</td>
+      <td>19</td>
+      <td>2</td>
+    </tr>
+    <tr>
+      <th>2</th>
+      <td>MS</td>
+      <td>Morgan Stanley</td>
+      <td>20</td>
+      <td>3</td>
+    </tr>
+    <tr>
+      <th>3</th>
+      <td>C</td>
+      <td>Citigroup</td>
+      <td>20</td>
+      <td>4</td>
+    </tr>
+    <tr>
+      <th>4</th>
+      <td>WFC</td>
+      <td>Wells Fargo</td>
+      <td>22</td>
+      <td>5</td>
     </tr>
   </tbody>
 </table>
 
 <br>
 
-## 🌎 미국 주식 분석 (US Stocks) 🇺🇸
-
-**MultiFactorUS** 클래스를 사용하면 미국 주식(S&P 500, NASDAQ, NYSE 등)에 대해서도 국내 주식과 동일한 인터페이스로 멀티팩터 분석을 수행할 수 있습니다. 미국 주식 분석은 `yfinance` 라이브러리를 기반으로 구동됩니다.
+### 6. 종합점수별 그룹화 출력
+`get_Ngroup()` 함수를 사용하면 전체 종목을 원하는 개수의 그룹으로 깔끔하게 묶어 요약할 수 있습니다.
 
-### 1. 미국 주식 분석 시작하기
+(1) 국내주식
 ```python
-from MultiFactor import MultiFactorUS
+# 시가총액 상위 100종목
+mf_kr = MultiFactorKR(N=100)
+df = mf_kr.get_score()  
 
-# 미국 시가총액 상위 100개 종목 분석 객체 생성 (기본값 500)
-mf_us = MultiFactorUS(N=100)
+# 종합점수 상위 순 10개 그룹으로 분류
+mf.get_Ngroup(df, Ngroup=10)  
 
-# 멀티팩터 종합 점수 및 순위 계산
-df_us = mf_us.get_score()
+# [출력 결과]
+# 1 : SK스퀘어, SK하이닉스, 삼성E&A, HD현대, 에이피알, 한국금융지주, 삼성전자, LG이노텍, 키움증권, LS ELECTRIC
+# 2 : 효성중공업, NH투자증권, 이수페타시스, 삼성물산, 삼성증권, HD현대일렉트릭, LG씨엔에스, LS, HD한국조선해양, 현대건설
+# 3 : 코오롱티슈진, 한화, 고려아연, 하나금융지주, JB금융지주, 미래에셋증권, KB금융, 삼천당제약, 기업은행, 엘앤에프
+# 4 : DB손해보험, 기아, 한전기술, 셀트리온, 우리금융지주, 펩트론, BNK금융지주, 대우건설, 한국항공우주, 현대글로비스
+# 5 : 삼성생명, 신한지주, HD현대중공업, 한화에어로스페이스, 현대모비스, 한화솔루션, 현대차, 삼양식품, 삼성카드, 에이비엘바이오
+# 6 : SK바이오팜, LG유플러스, 한미약품, S-Oil, GS, KT, 한화오션, 삼성화재, 두산, 삼성전기
+# 7 : SK텔레콤, 카카오뱅크, 한국전력, 한국타이어앤테크놀로지, HMM, 삼성중공업, 포스코인터내셔널, SK, 현대로템, 카카오페이
+# 8 : 대한항공, 현대오토에버, CJ, LIG넥스원, 삼성SDI, HD건설기계, HD현대마린솔루션, 두산에너빌리티, 크래프톤, 하이브
+# 9 : HLB, 삼성에스디에스, KT&G, 아모레퍼시픽, 유한양행, 한화시스템, SK이노베이션, LG전자, 삼성에피스홀딩스, NAVER
+# 10 : LG, 레인보우로보틱스, 한미반도체, POSCO홀딩스, LG에너지솔루션, 카카오, LG화학, 삼성바이오로직스, 한진칼, 포스코퓨처엠
 ```
 
-### 2. 주요 특징
-* **실시간 데이터**: `yfinance`를 활용하여 미국 시장의 최신 주가 및 재무 지표를 수집합니다.
-* **티커 호환성**: `BRK-B`와 같이 슬래시나 마침표가 포함된 특수 티커들을 내부적으로 자동 변환하여 데이터 수집 오류를 최소화합니다.
-* **동일한 환경**: 국내 주식과 동일한 함수명(`get_score`, `get_Ngroup` 등)을 사용하므로 기존 코드를 쉽게 재사용할 수 있습니다.
 
-### 3. 스타일별 가중치 및 그룹화 활용
+(2) 미국주식 
 ```python
-# '추세성장' 스타일 가중치 적용
-df_adj = mf_us.get_score_adj_weight(df_us, weight='추세성장')
+# 시가총액 상위 100종목
+mf_us = MultiFactorUS(N=100)
+df = mf_us.get_score()  
 
-# 종합 순위에 따라 10개 그룹으로 분류 및 종목 출력
-mf_us.get_Ngroup(df_adj, Ngroup=10)
-```
+# 종합점수 상위 순 10개 그룹으로 분류
+mf.get_Ngroup(df, Ngroup=10)  
 
+# [출력 결과]
+#1 : Micron Technology, Morgan Stanley, Goldman Sachs, BlackRock, Citigroup, Nvidia, AppLovin, Microsoft, Dell Technologies, Charles Schwab Corporation
+#2 : Sandisk, Oracle Corporation, Bank of America, JPMorgan Chase, Netflix, Western Digital, Palantir Technologies, Lilly (Eli), Arista Networks, Broadcom
+#3 : Newmont, Prologis, Amphenol, Lam Research, Apple Inc., Merck & Co., IBM, Wells Fargo, AbbVie, Chubb Limited
+#4 : KLA Corporation, Analog Devices, McDonald's, Booking Holdings, Philip Morris International, Bristol Myers Squibb, Alphabet Inc. (Class A), Alphabet Inc. (Class C), Amgen, Meta Platforms
+#5 : Gilead Sciences, Union Pacific Corporation, PepsiCo, Mastercard, Advanced Micro Devices, Uber, GE Aerospace, NextEra Energy, Progressive Corporation, Johnson & Johnson
+#6 : Seagate Technology, Vertiv, Visa Inc., nan, American Express, S&P Global, Applied Materials, Stryker Corporation, Lowe's, Texas Instruments
+#7 : TJX Companies, Amazon, Cisco, Caterpillar Inc., Verizon, Corning Inc., Eaton Corporation, Thermo Fisher Scientific, Boeing, AT&T
+#8 : Salesforce, Costco, Capital One, Intuitive Surgical, Pfizer, Intel, GE Vernova, Lockheed Martin, Abbott Laboratories, T-Mobile US
+#9 : Walt Disney Company (The), Coca-Cola Company (The), RTX Corporation, Parker Hannifin, Danaher Corporation, Deere & Company, Procter & Gamble, ConocoPhillips, Accenture, Linde plc
+#10 : Palo Alto Networks, Qualcomm, Welltower, ExxonMobil, Home Depot (The), Walmart, Honeywell, Chevron Corporation, UnitedHealth Group, Tesla, Inc.
+```
 <br>
 
 ## ⚠️ 투자자 유의사항 (Disclaimer)