hossam 0.3.19__tar.gz → 0.4__tar.gz

{hossam-0.3.19/hossam.egg-info → hossam-0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hossam
-Version: 0.3.19
+Version: 0.4
 Summary: Hossam Data Helper
 Author-email: Lee Kwang-Ho <leekh4232@gmail.com>
 License-Expression: MIT
@@ -35,6 +35,10 @@ Requires-Dist: pmdarima
 Requires-Dist: prophet
 Requires-Dist: plotly
 Requires-Dist: jenkspy
+Requires-Dist: flask
+Requires-Dist: xgboost
+Requires-Dist: lightgbm
+Requires-Dist: catboost
 Dynamic: license-file
 
 ---
@@ -61,7 +65,6 @@ title: 🎓 Hossam Data Helper
 - 🤖 **MCP 서버**: VSCode/Copilot과 통합 가능한 Model Context Protocol 지원
 - 📈 **교육용 최적화**: 데이터 분석 교육에 특화된 설계
 
----
 
 ## 📦 설치
 
@@ -71,72 +74,6 @@ pip install hossam
 
 **요구사항**: Python 3.8 이상
 
----
-
-## 🚀 빠른 시작
-
-### 샘플 데이터 로드
-
-```python
-from hossam import load_data, load_info
-
-# 사용 가능한 데이터셋 확인
-datasets = load_info()
-
-# 데이터 로드
-df = load_data('AD_SALES')
-```
-
-### 간단한 시각화
-
-```python
-from hossam import hs_plot
-import pandas as pd
-import numpy as np
-
-df = pd.DataFrame({
-    'x': np.random.randn(100),
-    'y': np.random.randn(100),
-    'category': np.random.choice(['A', 'B', 'C'], 100)
-})
-
-# 산점도
-hs_plot.scatterplot(df=df, xname='x', yname='y', hue='category')
-
-# 박스플롯
-hs_plot.boxplot(df=df, xname='category', yname='x')
-```
-
----
-
-## 🤖 MCP Server
-
-Hossam은 **Model Context Protocol(MCP)** 기반 서버로도 작동하며, VSCode Copilot/Cline과 통합하여 데이터 분석 코드를 자동 생성할 수 있습니다.
-
-### 빠른 시작
-
-```bash
-# 서버 시작
-hossam-mcp
-```
-
-### VSCode + Copilot 연동
-
-VSCode에서 Copilot과 함께 사용하려면 `.vscode/settings.json` 설정이 필요합니다.
-
-**Copilot Chat에서 사용:**
-```
-@hossam 이 DataFrame의 결측치를 분석하고 처리하는 코드 작성해줘
-```
-
-**설정 가이드:**
-- [`.vscode/settings.json` 완성형 샘플](https://py.hossam.kr/guides/vscode-settings-sample/) ⭐
-- [VSCode + Copilot 연동 상세](https://py.hossam.kr/guides/vscode-copilot-integration/)
-- [MCP 서버 사용법](https://py.hossam.kr/guides/mcp/)
-- [Copilot Chat 프롬프트 예시](https://py.hossam.kr/guides/copilot-prompts/)
-
----
-
 ## 📚 전체 문서
 
 **완전한 API 문서와 가이드는 [py.hossam.kr](https://py.hossam.kr)에서 확인하세요.**
@@ -152,49 +89,11 @@ VSCode에서 Copilot과 함께 사용하려면 `.vscode/settings.json` 설정이
 
 자세한 사용법은 [API 문서](https://py.hossam.kr/api/hossam/)를 참고하세요.
 
----
-
-## 🎓 예제
-
-### 결측치 분석
-
-```python
-from hossam import hs_prep
-
-# 결측치 정보 확인
-hs_prep.hs_missing_values(df)
-
-# 결측치 시각화
-hs_prep.hs_missing_values_barplot(df)
-```
-
-### 회귀 분석
-
-```python
-from hossam import hs_stats
-
-# 단순 선형 회귀
-result = hs_stats.hs_simple_regression(df, xname='x', yname='y', plot=True)
-```
-
-### 상관분석 히트맵
-
-```python
-from hossam import hs_plot
-
-hs_plot.heatmap(df=df, annot=True, cmap='coolwarm')
-```
-
-더 많은 예제는 [문서 사이트](https://py.hossam.kr)를 참고하세요.
-
----
 
 ## 📄 라이선스
 
 이 프로젝트는 MIT 라이선스를 따릅니다. 자유롭게 사용, 수정, 배포할 수 있습니다.
 
----
-
 ## 🔗 링크
 
 - **문서**: [py.hossam.kr](https://py.hossam.kr)
@@ -203,4 +102,4 @@ hs_plot.heatmap(df=df, annot=True, cmap='coolwarm')
 
 ---
 
-**Made with ❤️ for Data Science Education**
+{% include 'HOSSAM_API.md' %}

{hossam-0.3.19 → hossam-0.4}/README.md

@@ -22,7 +22,6 @@ title: 🎓 Hossam Data Helper
 - 🤖 **MCP 서버**: VSCode/Copilot과 통합 가능한 Model Context Protocol 지원
 - 📈 **교육용 최적화**: 데이터 분석 교육에 특화된 설계
 
----
 
 ## 📦 설치
 
@@ -32,72 +31,6 @@ pip install hossam
 
 **요구사항**: Python 3.8 이상
 
----
-
-## 🚀 빠른 시작
-
-### 샘플 데이터 로드
-
-```python
-from hossam import load_data, load_info
-
-# 사용 가능한 데이터셋 확인
-datasets = load_info()
-
-# 데이터 로드
-df = load_data('AD_SALES')
-```
-
-### 간단한 시각화
-
-```python
-from hossam import hs_plot
-import pandas as pd
-import numpy as np
-
-df = pd.DataFrame({
-    'x': np.random.randn(100),
-    'y': np.random.randn(100),
-    'category': np.random.choice(['A', 'B', 'C'], 100)
-})
-
-# 산점도
-hs_plot.scatterplot(df=df, xname='x', yname='y', hue='category')
-
-# 박스플롯
-hs_plot.boxplot(df=df, xname='category', yname='x')
-```
-
----
-
-## 🤖 MCP Server
-
-Hossam은 **Model Context Protocol(MCP)** 기반 서버로도 작동하며, VSCode Copilot/Cline과 통합하여 데이터 분석 코드를 자동 생성할 수 있습니다.
-
-### 빠른 시작
-
-```bash
-# 서버 시작
-hossam-mcp
-```
-
-### VSCode + Copilot 연동
-
-VSCode에서 Copilot과 함께 사용하려면 `.vscode/settings.json` 설정이 필요합니다.
-
-**Copilot Chat에서 사용:**
-```
-@hossam 이 DataFrame의 결측치를 분석하고 처리하는 코드 작성해줘
-```
-
-**설정 가이드:**
-- [`.vscode/settings.json` 완성형 샘플](https://py.hossam.kr/guides/vscode-settings-sample/) ⭐
-- [VSCode + Copilot 연동 상세](https://py.hossam.kr/guides/vscode-copilot-integration/)
-- [MCP 서버 사용법](https://py.hossam.kr/guides/mcp/)
-- [Copilot Chat 프롬프트 예시](https://py.hossam.kr/guides/copilot-prompts/)
-
----
-
 ## 📚 전체 문서
 
 **완전한 API 문서와 가이드는 [py.hossam.kr](https://py.hossam.kr)에서 확인하세요.**
@@ -113,49 +46,11 @@ VSCode에서 Copilot과 함께 사용하려면 `.vscode/settings.json` 설정이
 
 자세한 사용법은 [API 문서](https://py.hossam.kr/api/hossam/)를 참고하세요.
 
----
-
-## 🎓 예제
-
-### 결측치 분석
-
-```python
-from hossam import hs_prep
-
-# 결측치 정보 확인
-hs_prep.hs_missing_values(df)
-
-# 결측치 시각화
-hs_prep.hs_missing_values_barplot(df)
-```
-
-### 회귀 분석
-
-```python
-from hossam import hs_stats
-
-# 단순 선형 회귀
-result = hs_stats.hs_simple_regression(df, xname='x', yname='y', plot=True)
-```
-
-### 상관분석 히트맵
-
-```python
-from hossam import hs_plot
-
-hs_plot.heatmap(df=df, annot=True, cmap='coolwarm')
-```
-
-더 많은 예제는 [문서 사이트](https://py.hossam.kr)를 참고하세요.
-
----
 
 ## 📄 라이선스
 
 이 프로젝트는 MIT 라이선스를 따릅니다. 자유롭게 사용, 수정, 배포할 수 있습니다.
 
----
-
 ## 🔗 링크
 
 - **문서**: [py.hossam.kr](https://py.hossam.kr)
@@ -164,4 +59,4 @@ hs_plot.heatmap(df=df, annot=True, cmap='coolwarm')
 
 ---
 
-**Made with ❤️ for Data Science Education**
+{% include 'HOSSAM_API.md' %}

{hossam-0.3.19 → hossam-0.4}/hossam/__init__.py

@@ -1,33 +1,30 @@
+# submodules
+from . import hs_classroom
+from . import hs_gis
+from . import hs_plot
+from . import hs_prep
+from . import hs_stats
+from . import hs_timeserise
+from . import hs_util
 from .data_loader import load_data, load_info
-from .hs_stats import oneway_anova
+
+# py-modules
+import sys
+import warnings
 from matplotlib import pyplot as plt
 from matplotlib import font_manager as fm
 from importlib.resources import files, as_file
 from importlib.metadata import version
-from types import SimpleNamespace
-import sys
-import warnings
 
 try:
     __version__ = version("hossam")
 except Exception:
     __version__ = "develop"
 
+__all__ = ["load_data", "load_info", "hs_classroom", "hs_gis", "hs_plot", "hs_prep", "hs_stats", "hs_timeserise", "hs_util"]
 
-hs_fig = SimpleNamespace(
-    dpi=200,
-    width=800,
-    height=450,
-    font_size=9.5,
-    font_weight="normal",
-    frame_width=0.7,
-    line_width=1.5,
-    grid_alpha=0.3,
-    grid_width=0.5,
-    fill_alpha=0.3
-)
-
-__all__ = ["load_data", "load_info", "hs_classroom", "hs_gis", "hs_plot", "hs_prep", "hs_stats", "hs_timeserise", "hs_util", "hs_fig"]
+# 내부 모듈에서 hs_fig를 사용할 때는 아래와 같이 import 하세요.
+# from hossam import hs_fig
 
 
 def _init_korean_font():
@@ -44,14 +41,14 @@ def _init_korean_font():
 
             plt.rcParams.update({
                 "font.family": fname,
-                "font.size": hs_fig.font_size,
-                "font.weight": hs_fig.font_weight,
+                "font.size": hs_plot.config.font_size,
+                "font.weight": hs_plot.config.font_weight,
                 "axes.unicode_minus": False,
                 "text.antialiased": True,
                 "lines.antialiased": True,
                 "patch.antialiased": True,
-                "figure.dpi": hs_fig.dpi,
-                "savefig.dpi": hs_fig.dpi * 2,
+                "figure.dpi": hs_plot.config.dpi,
+                "savefig.dpi": hs_plot.config.dpi * 2,
                 "text.hinting": "auto",
                 "text.hinting_factor": 8,
                 "pdf.fonttype": 42,

{hossam-0.3.19 → hossam-0.4}/hossam/data_loader.py

@@ -39,7 +39,8 @@ def __get_df(path: str, index_col=None) -> DataFrame:
                 hs_pretty_table(info)
                 print()
             except Exception:
-                print(f"\033[91m[!] Cannot read metadata\033[0m")
+                #print(f"\033[91m[!] Cannot read metadata\033[0m")
+                pass
         else:
             df = read_excel(path, index_col=index_col)
 
@@ -51,7 +52,8 @@ def __get_df(path: str, index_col=None) -> DataFrame:
                 hs_pretty_table(info)
                 print()
             except:
-                print(f"\033[91m[!] Cannot read metadata\033[0m")
+                #print(f"\033[91m[!] Cannot read metadata\033[0m")
+                pass
     else:
         df = read_csv(path, index_col=index_col)
 
@@ -105,10 +107,11 @@ def load_info(search: str = None, local: str = None) -> DataFrame:
         DataFrame: name, chapter, desc, url 컬럼을 갖는 테이블
 
     Examples:
-        >>> from hossam.data_loader import load_info
-        >>> info = load_info()
-        >>> list(info.columns)
-        ['name', 'chapter', 'desc', 'url']
+        ```python
+        from hossam import *
+        info = load_info()
+        list(info.columns) #['name', 'chapter', 'desc', 'url']
+        ```
     """
     global BASE_URL
 
@@ -168,8 +171,10 @@ def load_data(key: str, local: str = None) -> Optional[DataFrame]:
         DataFrame | None: 성공 시 데이터프레임, 실패 시 None
 
     Examples:
-        >>> from hossam.data_loader import load_data
-        >>> df = load_data('AD_SALES')  # 메타데이터에 해당 키가 있어야 함
+        ```python
+        from hossam import *
+        df = load_data('AD_SALES')  # 메타데이터에 해당 키가 있어야 함
+        ```
     """
     index = None
     try:
@@ -181,8 +186,9 @@ def load_data(key: str, local: str = None) -> Optional[DataFrame]:
             print(e)
         return
 
-    print("\033[94m[data]\033[0m", url.replace("\\", "/"))
-    print("\033[94m[desc]\033[0m", desc)
+    #print("\033[94m[data]\033[0m", url.replace("\\", "/"))
+    #print("\033[94m[desc]\033[0m", desc)
+    print(f"\033[94m{desc}\033[0m")
 
     df = None
 

{hossam-0.3.19 → hossam-0.4}/hossam/hs_classroom.py

@@ -8,8 +8,8 @@ from kmodes.kmodes import KModes
 from matplotlib import pyplot as plt
 import seaborn as sns
 from .hs_util import load_data, pretty_table
-from . import hs_fig
 from . import hs_plot
+from .hs_plot import config
 
 # ===================================================================
 # 학생들을 관심사와 성적으로 균형잡힌 조로 편성한다
@@ -50,13 +50,16 @@ def cluster_students(
         ValueError: 필수 컬럼이 없거나 입력값이 유효하지 않은 경우.
 
     Examples:
-        >>> df = read_csv('students.csv')
-        >>> result = cluster_students(
-        ...     df=df,
-        ...     n_groups=5,
-        ...     score_cols=['국어', '영어', '수학'],
-        ...     interest_col='관심사'
-        ... )
+        ```python
+        df = read_csv('students.csv')
+
+        from hossam import *
+        result = hs_classroom.cluster_students(
+                    df=df,
+                    n_groups=5,
+                    score_cols=['국어', '영어', '수학'],
+                    interest_col='관심사')
+        ```
     """
 
     # 파일 경로인 경우 데이터프레임으로 로드
@@ -89,6 +92,11 @@ def cluster_students(
 
     # ===== 1단계: 점수 기반 처리 =====
     if score_cols is not None:
+        # 결측치는 0점으로 대체
+        for s in score_cols:
+            df[s] = df[s].fillna(0)
+        print(df)
+
         # 총점/평균점수 계산
         df['총점'] = df[score_cols].sum(axis=1)
         df['평균점수'] = df[score_cols].mean(axis=1)
@@ -97,12 +105,22 @@ def cluster_students(
         metric_col = '총점' if (score_metric or '').lower() != 'average' else '평균점수'
 
         # 성적사분위 분류 (선택한 기준 사용)
-        df['성적사분위'] = qcut(
-            df[metric_col],
-            q=[0, 0.25, 0.50, 0.75, 1.0],
-            labels=['Q1', 'Q2', 'Q3', 'Q4'],
-            duplicates='drop'  # 중복된 값 처리
-        )
+        quantiles = [0, 0.25, 0.50, 0.75, 1.0]
+        n_bins = len(quantiles) - 1
+        labels = [f"Q{i+1}" for i in range(n_bins)]
+        try:
+            df['성적사분위'] = qcut(
+                df[metric_col],
+                q=quantiles,
+                labels=labels,
+                duplicates='drop'  # 중복된 값 처리
+            )
+        except ValueError:
+            # 구간이 줄어든 경우, bins 개수에 맞게 labels 재생성
+            import pandas as pd
+            bins = pd.qcut(df[metric_col], q=quantiles, duplicates='drop').cat.categories
+            labels = [f"Q{i+1}" for i in range(len(bins))]
+            df['성적사분위'] = pd.qcut(df[metric_col], q=quantiles, labels=labels, duplicates='drop')
 
         # 성적그룹 매핑
         df['성적그룹'] = df['성적사분위'].map({
@@ -374,21 +392,24 @@ def _balance_group_sizes_only(
 # ===================================================================
 # 조 편성 결과의 인원, 관심사, 점수 분포를 시각화한다
 # ===================================================================
-def report_summary(df: DataFrame, width: int = hs_fig.width, height: int = hs_fig.height, dpi: int = hs_fig.dpi) -> None:
+def report_summary(df: DataFrame, interest_col: str = None, width: int = config.width, height: int = config.height, dpi: int = config.dpi) -> None:
     """조 편성 결과의 요약 통계를 시각화합니다.
 
     조별 인원 분포, 관심사 분포, 평균점수 분포를 나타냅니다.
 
     Args:
-        df: cluster_students 함수의 반환 결과 데이터프레임.
-        width: 그래프 넓이. 기본값: hs_fig.width
-        height: 그래프 높이. 기본값: hs_fig.height
-        dpi: 그래프 해상도. 기본값: hs_fig.dpi
+        df (DataFrame): cluster_students 함수의 반환 결과 데이터프레임.
+        interest_col (str): 관심사 컬럼명
+        width (int): 그래프 넓이. 기본값: config.width
+        height (int): 그래프 높이. 기본값: config.height
+        dpi (int): 그래프 해상도. 기본값: config.dpi
 
     Examples:
-        >>> from hossam.classroom import cluster_students, report_summary
-        >>> df_result = cluster_students(df, n_groups=5, score_cols=['국어', '영어', '수학'])
-        >>> report_summary(df_result)
+        ```python
+        from hossam import *
+        df_result = hs_classroom.cluster_students(df, n_groups=5, score_cols=['국어', '영어', '수학'])
+        hs_classroom.report_summary(df_result)
+        ```
     """
 
     if df is None or len(df) == 0:
@@ -405,7 +426,7 @@ def report_summary(df: DataFrame, width: int = hs_fig.width, height: int = hs_fi
     # 필요한 컬럼 확인
     has_score = '총점' in df.columns
     has_avg = '평균점수' in df.columns
-    has_interest = '관심사' in df.columns
+    has_interest = interest_col and '관심사' in df.columns
 
     # 혼합 타입 안전 정렬 라벨 준비
     labels = df['조'].unique().tolist()
@@ -525,7 +546,7 @@ def report_summary(df: DataFrame, width: int = hs_fig.width, height: int = hs_fi
 # ===================================================================
 # 조별 점수 분포를 커널 밀도 추정(KDE) 그래프로 시각화한다
 # ===================================================================
-def report_kde(df: DataFrame, metric: str = 'average', width: int = hs_fig.width, height: int = hs_fig.height, dpi: int = hs_fig.dpi) -> None:
+def report_kde(df: DataFrame, metric: str = 'average', width: int = config.width, height: int = config.height, dpi: int = config.dpi) -> None:
     """조별 점수 분포를 KDE(Kernel Density Estimation)로 시각화합니다.
 
     각 조의 점수 분포를 커널 밀도 추정으로 표시하고 평균 및 95% 신뢰구간을 나타냅니다.
@@ -534,14 +555,16 @@ def report_kde(df: DataFrame, metric: str = 'average', width: int = hs_fig.width
         df: cluster_students 함수의 반환 결과 데이터프레임.
         metric: 점수 기준 선택 ('total' 또는 'average').
             'total'이면 총점, 'average'이면 평균점수. 기본값: 'average'
-        width: 그래프 넓이. 기본값: hs_fig.width
-        height: 그래프 높이. 기본값: hs_fig.height
-        dpi: 그래프 해상도. 기본값: hs_fig.dpi
+        width: 그래프 넓이. 기본값: config.width
+        height: 그래프 높이. 기본값: config.height
+        dpi: 그래프 해상도. 기본값: config.dpi
 
     Examples:
-        >>> from hossam.classroom import cluster_students, report_kde
-        >>> df_result = cluster_students(df, n_groups=5, score_cols=['국어', '영어', '수학'])
-        >>> report_kde(df_result, metric='average')
+        ```python
+        from hossam import *
+        df_result = hs_classroom.cluster_students(df, n_groups=5, score_cols=['국어', '영어', '수학'])
+        hs_classroom.report_kde(df_result, metric='average')
+        ```
     """
     if df is None or len(df) == 0:
         print("데이터프레임이 비어있습니다")
@@ -611,10 +634,12 @@ def group_summary(df: DataFrame, name_col: str = '학생이름') -> DataFrame:
         컬럼: '조', '학생', '총점평균', '평균점수평균'
 
     Examples:
-        >>> from hossam.classroom import cluster_students, group_summary
-        >>> df_result = cluster_students(df, n_groups=5, score_cols=['국어', '영어', '수학'])
-        >>> summary = group_summary(df_result, name_col='이름')
-        >>> print(summary)
+        ```python
+        from hossam import *
+        df_result = hs_classroom.cluster_students(df, n_groups=5, score_cols=['국어', '영어', '수학'])
+        summary = hs_classroom.group_summary(df_result, name_col='이름')
+        print(summary)
+        ```
     """
 
     if df is None or len(df) == 0:
@@ -698,15 +723,15 @@ def analyze_classroom(
         조별 요약 정보 (group_summary의 결과).
 
     Examples:
-        >>> from hossam.classroom import analyze_classroom
-        >>> summary = analyze_classroom(
-        ...     df='students.csv',
-        ...     n_groups=5,
-        ...     score_cols=['국어', '영어', '수학'],
-        ...     interest_col='관심사',
-        ...     name_col='이름'
-        ... )
-        >>> print(summary)
+        ```python
+        from hossam import *
+        summary = hs_classroom.analyze_classroom(df='students.csv',
+                                                 n_groups=5,
+                                                 score_cols=['국어', '영어', '수학'],
+                                                 interest_col='관심사',
+                                                 name_col='이름')
+        print(summary)
+        ```
     """
 
     # 1. 조 편성
@@ -723,7 +748,7 @@ def analyze_classroom(
 
     # 3. 요약 시각화
     if show_summary:
-        report_summary(df_result)
+        report_summary(df_result, interest_col)
 
     # 4. KDE 시각화
     if show_kde:

{hossam-0.3.19 → hossam-0.4}/hossam/hs_gis.py

@@ -101,10 +101,12 @@ def geocode(df: DataFrame, addr: str, key: str) -> DataFrame:
         Exception: 지오코딩 과정에서 발생한 예외를 전파합니다.
 
     Examples:
-        >>> from hossam import gis
-        >>> result = gis.hs_geocode(df, addr="address", key="YOUR_VWORLD_KEY")
-        >>> set(["latitude","longitude"]).issubset(result.columns)
-        True
+        ```python
+        from hossam import *
+        result = hs_gis.geocode(df, addr="address", key="YOUR_VWORLD_KEY")
+        set(["latitude","longitude"]).issubset(result.columns)
+        # True
+        ```
     """
     data: DataFrame = df.copy()
     size: int = len(data)
@@ -172,8 +174,10 @@ def load_shape(path: str, info: bool = True) -> GeoDataFrame:
         FileNotFoundError: 파일이 존재하지 않는 경우.
 
     Examples:
-        >>> from hossam.gis import load_shape
-        >>> gdf = hs_load_shape("path/to/file.shp", info=False)
+        ```python
+        from hossam import *
+        gdf = hs_gis.load_shape("path/to/file.shp", info=False)
+        ```
     """
     if not os.path.exists(path):
         raise FileNotFoundError("⚠️[FileNotFoundException] 주어진 파일을 찾을 수 없습니다.\n - %s" % path)