hossam 0.4.9__py3-none-any.whl → 0.4.11__py3-none-any.whl

hossam/__init__.py

@@ -6,6 +6,7 @@ from . import hs_prep
 from . import hs_stats
 from . import hs_timeserise
 from . import hs_util
+from . import hs_cluster
 from .hs_util import load_info
 from .hs_util import _load_data_remote as load_data
 from .hs_plot import visualize_silhouette
@@ -25,7 +26,7 @@ except Exception:
 
 my_dpi = hs_plot.config.dpi
 
-__all__ = ["my_dpi", "load_data", "load_info", "hs_classroom", "hs_gis", "hs_plot", "hs_prep", "hs_stats", "hs_timeserise", "hs_util", "visualize_silhouette"]
+__all__ = ["my_dpi", "load_data", "load_info", "hs_classroom", "hs_gis", "hs_plot", "hs_prep", "hs_stats", "hs_timeserise", "hs_util", "hs_cluster", "visualize_silhouette"]
 
 # 내부 모듈에서 hs_fig를 사용할 때는 아래와 같이 import 하세요.
 # from hossam import hs_fig

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_plot
 from .hs_plot import config
+from . import hs_plot
 
 # ===================================================================
 # 학생들을 관심사와 성적으로 균형잡힌 조로 편성한다

hossam/hs_cluster.py

@@ -0,0 +1,119 @@
+from typing import Literal
+from kneed import KneeLocator
+from pandas import Series
+from matplotlib.pyplot import Axes # type: ignore
+
+from . import hs_plot
+
+import numpy as np
+
+def elbow_point(
+        x: Series | np.ndarray | list,
+        y: Series | np.ndarray | list,
+        dir: Literal["left,down", "left,up", "right,down", "right,up"] = "left,down",
+        S: float = 0.1,
+        plot: bool = True,
+        title: str = None,
+        marker: str = None,
+        width: int = hs_plot.config.width,
+        height: int = hs_plot.config.height,
+        dpi: int = hs_plot.config.dpi,
+        linewidth: int = hs_plot.config.line_width,
+        save_path: str | None = None,
+        ax: Axes | None = None,
+        **params,
+) -> tuple:
+
+    """
+    엘보우(Elbow) 포인트를 자동으로 탐지하는 함수.
+
+    주어진 x, y 값의 곡선에서 KneeLocator를 활용해 엘보우(혹은 니) 포인트를 탐지하고, 필요시 시각화까지 지원함.
+
+    Args:
+        x (Series | np.ndarray | list): x축 값(일반적으로 K값 등).
+        y (Series | np.ndarray | list): y축 값(일반적으로 inertia, SSE 등).
+        dir (Literal["left,down", "left,up", "right,down", "right,up"], optional):
+            곡선의 방향 및 형태 지정. 기본값은 "left,down".
+            - "left,down": 왼쪽에서 오른쪽으로 감소(볼록)
+            - "left,up": 왼쪽에서 오른쪽으로 증가(오목)
+            - "right,down": 오른쪽에서 왼쪽으로 감소(볼록)
+            - "right,up": 오른쪽에서 왼쪽으로 증가(오목)
+        S (float, optional): KneeLocator의 민감도 파라미터. 기본값 0.1.
+        plot (bool, optional): True면 결과를 시각화함. 기본값 True.
+        title (str, optional): 플롯 제목.
+        marker (str, optional): 마커 스타일.
+        width (int, optional): 플롯 가로 크기.
+        height (int, optional): 플롯 세로 크기.
+        dpi (int, optional): 플롯 해상도.
+        linewidth (int, optional): 선 두께.
+        save_path (str | None, optional): 저장 경로 지정시 파일로 저장.
+        ax (Axes | None, optional): 기존 matplotlib Axes 객체. None이면 새로 생성.
+        **params: lineplot에 전달할 추가 파라미터.
+
+    Returns:
+        tuple: (best_x, best_y)
+            - best_x: 엘보우 포인트의 x값(예: 최적 K)
+            - best_y: 엘보우 포인트의 y값
+
+    Examples:
+        ```python
+        x = [1, 2, 3, 4, 5, 6]
+        y = [100, 80, 60, 45, 44, 43]
+        elbow_point(x, y)
+        ```
+
+    Note:
+        - KneeLocator는 kneed 패키지의 클래스로, 곡선의 형태(curve)와 방향(direction)에 따라 엘보우 포인트를 탐지함.
+        - dir 파라미터에 따라 curve/direction이 자동 지정됨.
+        - plot=True일 때, 엘보우 포인트에 수직/수평선과 텍스트가 표시됨.
+    """
+
+    if dir == "left,down":
+        curve = "convex"
+        direction = "decreasing"
+    elif dir == "left,up":
+        curve = "concave"
+        direction = "increasing"
+    elif dir == "right,down":
+        curve = "convex"
+        direction = "increasing"
+    else:
+        curve = "concave"
+        direction = "decreasing"
+
+    kn = KneeLocator(x=x, y=y, curve=curve, direction=direction, S=S)
+
+    best_x = kn.elbow
+    best_y = kn.elbow_y
+
+    if plot:
+        def hvline(ax):
+            ax.axvline(best_x, color="red", linestyle="--", linewidth=0.7)
+            ax.axhline(best_y, color="red", linestyle="--", linewidth=0.7)
+            ax.text(
+                best_x + 0.1,
+                best_y + 0.1,
+                "Best K=%d" % best_x,
+                fontsize=8,
+                ha="left",
+                va="bottom",
+                color="r",
+            )
+
+        hs_plot.lineplot(
+                df = None,
+                xname = x,
+                yname = y,
+                title = title,
+                marker = marker,
+                width = width,
+                height = height,
+                linewidth = linewidth,
+                dpi = dpi,
+                save_path = save_path,
+                callback = hvline,
+                ax = ax,
+                **params
+        )
+
+    return best_x, best_y

hossam/hs_plot.py

@@ -5,10 +5,10 @@ from typing import Callable
 
 # ===================================================================
 import numpy as np
-import pandas as pd
 import seaborn as sb
 import matplotlib.pyplot as plt
 from matplotlib.pyplot import Axes # type: ignore
+from pandas import Series, DataFrame
 from math import sqrt
 from pandas import DataFrame
 
@@ -200,9 +200,9 @@ def show_figure(ax: Axes | np.ndarray, callback: Callable | None = None, outpara
 # 선 그래프를 그린다
 # ===================================================================
 def lineplot(
-    df: DataFrame,
-    xname: str | None = None,
-    yname: str | None = None,
+    df: DataFrame | None = None,
+    xname: str | Series | np.ndarray | list | None = None,
+    yname: str | Series | np.ndarray | list | None = None,
     hue: str | None = None,
     title: str | None = None,
     marker: str | None = None,
@@ -219,13 +219,13 @@ def lineplot(
     """선 그래프를 그린다.
 
     Args:
-        df (DataFrame): 시각화할 데이터.
-        xname (str|None): x축 컬럼명.
-        yname (str|None): y축 컬럼명.
-        hue (str|None): 범주 구분 컬럼명.
-        title (str|None): 그래프 제목.
-        marker (str|None): 마커 모양.
-        palette (str|None): 팔레트 이름.
+        df (DataFrame | None): 시각화할 데이터.
+        xname (str | Series | np.ndarray | list | None): x축 컬럼명 혹은 x축 값 시퀀스.
+        yname (str | Series | np.ndarray | list | None): y축 컬럼명 혹은 y축 값 시퀀스.
+        hue (str | None): 범주 구분 컬럼명.
+        title (str | None): 그래프 제목.
+        marker (str | None): 마커 모양.
+        palette (str | None): 팔레트 이름.
         width (int): 캔버스 가로 픽셀.
         height (int): 캔버스 세로 픽셀.
         linewidth (float): 선 굵기.
@@ -2122,8 +2122,8 @@ def categorical_target_distribution(
 # ===================================================================
 def roc_curve_plot(
     fit,
-    y: np.ndarray | pd.Series | None = None,
-    X: pd.DataFrame | np.ndarray | None = None,
+    y: np.ndarray | Series | None = None,
+    X: DataFrame | np.ndarray | None = None,
     title: str | None = None,
     width: int = config.height,
     height: int = config.height,
@@ -2450,7 +2450,7 @@ def distribution_plot(
             if hue not in data.columns:
                 raise ValueError(f"hue column '{hue}' not found in DataFrame")
 
-            categories = list(pd.Series(data[hue].dropna().unique()).sort_values())
+            categories = list(Series(data[hue].dropna().unique()).sort_values())
             n_cat = len(categories) if categories else 1
 
             fig, axes = get_default_ax(width, height, rows=n_cat, cols=2, dpi=dpi, title=title)

hossam/hs_util.py

@@ -10,10 +10,13 @@ from typing import TYPE_CHECKING
 from importlib.metadata import distributions
 import pandas as pd
 import numpy as np
+import glob as gl
+# -------------------------------------------------------------
 from pandas import DataFrame, DatetimeIndex, read_csv, read_excel
 from scipy.stats import normaltest
 from tabulate import tabulate
 from os.path import join, exists
+import os
 from io import BytesIO
 from pandas import DataFrame, read_csv, read_excel
 from typing import Optional, Tuple, Any
@@ -24,11 +27,13 @@ BASE_URL = "https://data.hossam.kr"
 def __get_df(path: str, index_col=None) -> DataFrame:
     p = path.rfind(".")
     exec = path[p+1:].lower()
+    tmp_dir = None
 
     # 파일 확장자가 압축파일인 경우 로컬에 파일을 다운로드 후 압축 해제
     if exec == "zip":
-        tmp_dir = Path(tempfile.mkdtemp())
-        zip_path = tmp_dir / "data.zip"
+        tmp_dir = os.getcwd() + "/.hossam_tmp"
+        os.makedirs(tmp_dir, exist_ok=True)
+        zip_path = join(tmp_dir, "data.zip")
 
         # 원격 URL인 경우 파일 다운로드
         if path.lower().startswith(('http://', 'https://')):
@@ -49,7 +54,7 @@ def __get_df(path: str, index_col=None) -> DataFrame:
             zip_ref.extractall(tmp_dir)
 
         # 압축 해제된 파일 중 첫 번째 파일을 데이터로 로드
-        extracted_files = list(tmp_dir.glob('*'))
+        extracted_files = list(gl.glob(join(tmp_dir, '*')))
         if not extracted_files:
             raise FileNotFoundError("압축 파일 내에 데이터 파일이 없습니다.")
 
@@ -57,10 +62,6 @@ def __get_df(path: str, index_col=None) -> DataFrame:
         p = path.rfind(".")
         exec = path[p+1:].lower()
 
-        # 생성된 임시 디렉토리 삭제
-        shutil.rmtree(tmp_dir)
-
-
     if exec == 'xlsx':
         # If path is a remote URL, fetch the file once and reuse the bytes
         if path.lower().startswith(('http://', 'https://')):
@@ -100,6 +101,9 @@ def __get_df(path: str, index_col=None) -> DataFrame:
     else:
         df = read_csv(path, index_col=index_col)
 
+    if tmp_dir:
+        shutil.rmtree(tmp_dir)
+
     return df
 
 # -------------------------------------------------------------

{hossam-0.4.9.dist-info → hossam-0.4.11.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hossam
-Version: 0.4.9
+Version: 0.4.11
 Summary: Hossam Data Helper
 Author-email: Lee Kwang-Ho <leekh4232@gmail.com>
 License-Expression: MIT
@@ -61,9 +61,9 @@ title: 🎓 Hossam Data Helper
 
 - 📊 **풍부한 시각화**: 25+ 시각화 함수 (Seaborn/Matplotlib 기반)
 - 🎯 **통계 분석**: 회귀, 분류, 시계열 분석 도구
+- 🤖 **머신 러닝**: 예측, 분류, 군집 학습 모델 구축 및 성능 평가
 - 📦 **샘플 데이터**: 학습용 데이터셋 즉시 로드
 - 🔧 **데이터 전처리**: 결측치 처리, 이상치 탐지, 스케일링
-- 🤖 **MCP 서버**: VSCode/Copilot과 통합 가능한 Model Context Protocol 지원
 - 📈 **교육용 최적화**: 데이터 분석 교육에 특화된 설계
 
 
@@ -87,6 +87,8 @@ pip install hossam
 - **hs_timeserise**: 시계열 분석 기능 지원
 - **hs_gis**: GIS 데이터 로드 및 시각화 (대한민국 지도 지원)
 - **hs_util**: 예쁜 테이블 출력, 그리드 서치 등
+- **hs_cluster**: 군집분석, PCA 등 (작업중)
+- **hs_ml**: 예측, 분류 분석 (예정)
 
 자세한 사용법은 [API 문서](https://py.hossam.kr/api/hossam/)를 참고하세요.
 

hossam-0.4.11.dist-info/RECORD

@@ -0,0 +1,16 @@
+hossam/NotoSansKR-Regular.ttf,sha256=0SCufUQwcVWrWTu75j4Lt_V2bgBJIBXl1p8iAJJYkVY,6185516
+hossam/__init__.py,sha256=4cGvavSotmQKhkHS4UCANhzszrMNwXNESAhh0RuFF-w,2893
+hossam/hs_classroom.py,sha256=Sb1thy49LKn2zU90aiOVwHWhyWSMHLZbZX7eXmQlquc,27523
+hossam/hs_cluster.py,sha256=anjoZ12JsIDWoGhm6agd0IF4N_md5czutyW4rbXnDEM,4255
+hossam/hs_gis.py,sha256=DVmndBK-_7GMK3J1_on3ieEQk1S0MfUZ8_wlX-cDdZQ,11581
+hossam/hs_plot.py,sha256=5j498vga_1wZBRlMUZ047LswNSvfTEpGP6uL7yzl3-g,92744
+hossam/hs_prep.py,sha256=ypuX97mCxpo7CLoI_S79bUw7th0ok5LCZjt4vzRaGiI,38326
+hossam/hs_stats.py,sha256=MDS3rvaXDP8aYwcE36JTetWiZgE4fkXnNo0vwlXu-pA,119890
+hossam/hs_timeserise.py,sha256=NzGV4bJmVQr3qUFySOP25qENItmloYjgh3VgwSbSmXc,43163
+hossam/hs_util.py,sha256=ptl-2W7-0Ad_BemZMR8cFnDt6-SHCRRCk1Gh7giFjSs,16149
+hossam/leekh.png,sha256=1PB5NQ24SDoHA5KMiBBsWpSa3iniFcwFTuGwuOsTHfI,6395
+hossam-0.4.11.dist-info/licenses/LICENSE,sha256=nIqzhlcFY_2D6QtFsYjwU7BWkafo-rUJOQpDZ-DsauI,941
+hossam-0.4.11.dist-info/METADATA,sha256=POoVivyFd3rFLoQny6kigfNmsDbHdyvndbZ71Sz2NjY,3803
+hossam-0.4.11.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+hossam-0.4.11.dist-info/top_level.txt,sha256=_-7bwjhthHplWhywEaHIJX2yL11CQCaLjCNSBlk6wiQ,7
+hossam-0.4.11.dist-info/RECORD,,

hossam-0.4.9.dist-info/RECORD

@@ -1,15 +0,0 @@
-hossam/NotoSansKR-Regular.ttf,sha256=0SCufUQwcVWrWTu75j4Lt_V2bgBJIBXl1p8iAJJYkVY,6185516
-hossam/__init__.py,sha256=pPq8agagol9Vhl_CFwa3QNpM8z278Qd_TZ_W4eJ0ziE,2854
-hossam/hs_classroom.py,sha256=oNRnHPXOu0-YqtPY7EJeS1qteH0CtKxNk5Lt7opti_w,27523
-hossam/hs_gis.py,sha256=DVmndBK-_7GMK3J1_on3ieEQk1S0MfUZ8_wlX-cDdZQ,11581
-hossam/hs_plot.py,sha256=u3nev3MRvp_n45K9feQdWhPmNVeCXavnX7xpS3zekXw,92535
-hossam/hs_prep.py,sha256=ypuX97mCxpo7CLoI_S79bUw7th0ok5LCZjt4vzRaGiI,38326
-hossam/hs_stats.py,sha256=MDS3rvaXDP8aYwcE36JTetWiZgE4fkXnNo0vwlXu-pA,119890
-hossam/hs_timeserise.py,sha256=NzGV4bJmVQr3qUFySOP25qENItmloYjgh3VgwSbSmXc,43163
-hossam/hs_util.py,sha256=_IME9IRbjOWZDBZwMQhKMMHdvWT3fjCRLtIt2RK-Yd0,16007
-hossam/leekh.png,sha256=1PB5NQ24SDoHA5KMiBBsWpSa3iniFcwFTuGwuOsTHfI,6395
-hossam-0.4.9.dist-info/licenses/LICENSE,sha256=nIqzhlcFY_2D6QtFsYjwU7BWkafo-rUJOQpDZ-DsauI,941
-hossam-0.4.9.dist-info/METADATA,sha256=rZsVu2NMwdxHp2stQbgoAGIMGkGK9eF6oGe9JuJ0i7k,3706
-hossam-0.4.9.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
-hossam-0.4.9.dist-info/top_level.txt,sha256=_-7bwjhthHplWhywEaHIJX2yL11CQCaLjCNSBlk6wiQ,7
-hossam-0.4.9.dist-info/RECORD,,