hossam 0.4.17__tar.gz → 0.4.19__tar.gz

{hossam-0.4.17/hossam.egg-info → hossam-0.4.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hossam
-Version: 0.4.17
+Version: 0.4.19
 Summary: Hossam Data Helper
 Author-email: Lee Kwang-Ho <leekh4232@gmail.com>
 License-Expression: MIT
@@ -40,6 +40,7 @@ Requires-Dist: xgboost
 Requires-Dist: lightgbm
 Requires-Dist: catboost
 Requires-Dist: kneed
+Requires-Dist: shap
 Dynamic: license-file
 
 ---

{hossam-0.4.17 → hossam-0.4.19}/hossam/__init__.py

@@ -9,11 +9,19 @@ from . import hs_prep
 from . import hs_stats
 from . import hs_timeserise
 from . import hs_util
+from . import hs_reg
 from . import hs_cluster
 from . import hs_study
 from .hs_util import load_info
 from .hs_util import _load_data_remote as load_data
 from .hs_plot import visualize_silhouette
+from .hs_stats import ttest_ind as hs_ttest_ind
+from .hs_stats import outlier_table as hs_outlier_table
+from .hs_stats import oneway_anova as hs_oneway_anova
+from .hs_reg import learning_cv as hs_learning_cv
+from .hs_reg import get_scores as hs_get_scores
+from .hs_reg import get_score_cv as hs_get_score_cv
+from .hs_reg import VIFSelector
 
 # py-modules
 import sys
@@ -31,7 +39,29 @@ 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", "hs_cluster", "hs_study", "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",
+    "hs_reg",
+    "hs_study",
+    "visualize_silhouette",
+    "hs_ttest_ind",
+    "hs_outlier_table",
+    "hs_oneway_anova",
+    "hs_learning_cv",
+    "hs_get_scores",
+    "hs_get_score_cv",
+    "VIFSelector",
+]
 
 
 def check_pypi_latest(package_name: str):
@@ -51,7 +81,7 @@ def check_pypi_latest(package_name: str):
         "package": package_name,
         "installed": installed,
         "latest": latest,
-        "outdated": installed != latest
+        "outdated": installed != latest,
     }
 
 
@@ -67,21 +97,23 @@ def _init_korean_font():
             fprop = fm.FontProperties(fname=str(font_path))
             fname = fprop.get_name()
 
-            plt.rcParams.update({
-                "font.family": fname,
-                "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_plot.config.dpi,
-                "savefig.dpi": hs_plot.config.dpi * 2,
-                "text.hinting": "auto",
-                "text.hinting_factor": 8,
-                "pdf.fonttype": 42,
-                "ps.fonttype": 42,
-            })
+            plt.rcParams.update(
+                {
+                    "font.family": fname,
+                    "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_plot.config.dpi,
+                    "savefig.dpi": hs_plot.config.dpi * 2,
+                    "text.hinting": "auto",
+                    "text.hinting_factor": 8,
+                    "pdf.fonttype": 42,
+                    "ps.fonttype": 42,
+                }
+            )
 
             print(
                 "\n✅ 시각화를 위한 한글 글꼴(NotoSansKR-Regular)이 자동 적용되었습니다."
@@ -103,6 +135,8 @@ def _init():
         f"🔖 Version: {__version__}",
     ]
 
+    
+
     for msg in messages:
         print(f"{msg}")
 
@@ -119,10 +153,36 @@ def _init():
 
     _init_korean_font()
 
+    # 각 열의 넓이 제한 없음
+    pd.set_option("display.max_colwidth", None)
+    # 출력 너비 제한 없음 (가로 스크롤될 수 있음)
+    pd.set_option("display.width", None)
     # 컬럼 생략 금지
     pd.set_option("display.max_columns", None)
     # 행 최대 출력 수 100개로 수정
     pd.set_option("display.max_rows", 100)
+    # 소수점 자리수 3자리로 설정
+    pd.options.display.float_format = "{:.3f}".format
+
+    from IPython.display import display, HTML
+
+    display(
+        HTML(
+            """
+    <style>      
+    .dataframe tr:hover {
+        background-color: #ffff99 !important;
+        border: 1px solid #ffcc00;
+    }
+    </style>
+    """
+        )
+    )
+
+import multiprocessing as mp
 
+def is_parallel_worker():
+    return mp.current_process().name != "MainProcess"
 
-_init()
+if not is_parallel_worker():
+    _init()

{hossam-0.4.17 → hossam-0.4.19}/hossam/hs_classroom.py

@@ -6,6 +6,7 @@ import math
 from pandas import DataFrame, qcut, concat, to_numeric
 from kmodes.kmodes import KModes
 from matplotlib import pyplot as plt
+from prompt_toolkit.formatted_text.ansi import i
 import seaborn as sns
 from .hs_util import load_data, pretty_table
 from .hs_plot import config
@@ -19,6 +20,7 @@ def cluster_students(
     n_groups: int,
     score_cols: list | None = None,
     interest_col: str | None = None,
+    interest_ignore: str | None = None,
     max_iter: int = 200,
     score_metric: str = 'total'
 ) -> DataFrame:
@@ -39,6 +41,8 @@ def cluster_students(
             None일 경우 점수 기반 균형 조정을 하지 않습니다. 기본값: None
         interest_col: 관심사 정보가 있는 컬럼명.
             None일 경우 관심사 기반 군집화를 하지 않습니다. 기본값: None
+        interest_ignore: 관심사 군집화에서 제외할 값.
+            지정된 값은 별도 군집에서 제외됩니다. 기본값: None
         max_iter: 균형 조정 최대 반복 횟수. 기본값: 200
         score_metric: 점수 기준 선택 ('total' 또는 'average').
             'total'이면 총점, 'average'이면 평균점수 기준. 기본값: 'total'
@@ -151,8 +155,18 @@ def cluster_students(
     if actual_n_groups < 2:
         actual_n_groups = 2
 
+    df_ignore = None
+
     # ===== 3단계: 관심사 기반 1차 군집 =====
     if interest_col is not None:
+        df_main[interest_col] = df_main[interest_col].fillna('미정')
+
+        if interest_ignore is not None:
+            df_ignore = df_main[df_main[interest_col] == interest_ignore].copy()
+            df_main = df_main[df_main[interest_col] != interest_ignore].copy()
+
+            print(df_ignore)
+
         X_interest = df_main[[interest_col]].to_numpy()
 
         kmodes_interest = KModes(
@@ -184,12 +198,18 @@ def cluster_students(
         df_main = _balance_group_sizes_only(df_main, actual_n_groups, min_size, max_size)
 
     # ===== 5단계: 극단값 포함 병합 =====
-    if df_outlier is not None and len(df_outlier) > 0:
+    result = df_main
+
+    if (df_outlier is not None and len(df_outlier) > 0):
         # '조'는 숫자형 유지: 극단값은 0으로 표시
         df_outlier['조'] = 0
-        result = concat([df_main, df_outlier], ignore_index=True)
-    else:
-        result = df_main
+        result = concat([result, df_outlier], ignore_index=True)
+
+    if (df_ignore is not None and len(df_ignore) > 0):
+        # '조'는 숫자형 유지: 제외된 학생은 -1로 표시
+        df_ignore['조'] = -1
+        result = concat([result, df_ignore], ignore_index=True)
+        
 
     # 평균점수는 이미 계산됨 (score_cols 있을 때)
 
@@ -694,6 +714,7 @@ def analyze_classroom(
     n_groups: int,
     score_cols: list | None = None,
     interest_col: str | None = None,
+    interest_ignore: str | None = None,
     max_iter: int = 200,
     score_metric: str = 'average',
     name_col: str = '학생이름',
@@ -713,6 +734,7 @@ def analyze_classroom(
         n_groups: 목표 조의 개수.
         score_cols: 성적 계산에 사용할 점수 컬럼명 리스트. 기본값: None
         interest_col: 관심사 정보가 있는 컬럼명. 기본값: None
+        interest_ignore: 관심사 군집화에서 제외할 값. 기본값: None
         max_iter: 균형 조정 최대 반복 횟수. 기본값: 200
         score_metric: 점수 기준 선택 ('total' 또는 'average'). 기본값: 'average'
         name_col: 학생 이름 컬럼명. 기본값: '학생이름'
@@ -740,6 +762,7 @@ def analyze_classroom(
         n_groups=n_groups,
         score_cols=score_cols,
         interest_col=interest_col,
+        interest_ignore=interest_ignore,
         max_iter=max_iter,
         score_metric=score_metric
     )

{hossam-0.4.17 → hossam-0.4.19}/hossam/hs_cluster.py

@@ -23,6 +23,7 @@ from sklearn.metrics import silhouette_score, adjusted_rand_score
 # hossam 패키지 참조
 # ===================================================================
 from . import hs_plot
+from .hs_util import is_2d
 
 RANDOM_STATE = 52
 
@@ -32,10 +33,11 @@ RANDOM_STATE = 52
 # ===================================================================
 def kmeans_fit(
     data: DataFrame,
-    n_clusters: int,
+    n_clusters: int | None = None,
+    k_range: list | tuple = [2, 11],
     random_state: int = RANDOM_STATE,
     plot: bool = False,
-    fields: list[list[str]] | None = None,
+    fields: list[str] | tuple[str] | tuple[tuple[str]] | list[list[str]] | None = None,
     **params,
 ) -> tuple[KMeans, DataFrame, float]:
     """
@@ -43,7 +45,7 @@ def kmeans_fit(
 
     Args:
         data (DataFrame): 군집화할 데이터프레임.
-        n_clusters (int): 군집 개수.
+        n_clusters (int | None): 군집 개수.
         random_state (int, optional): 랜덤 시드. 기본값은 RANDOM_STATE.
         plot (bool, optional): True면 결과를 시각화함. 기본값 False.
         fields (list[list[str]] | None, optional): 시각화할 필드 쌍 리스트. 기본값 None이면 수치형 컬럼의 모든 조합 사용.
@@ -55,18 +57,36 @@ def kmeans_fit(
         float: 실루엣 점수
     """
     df = data.copy()
+
+    if n_clusters is None:
+        n_clusters = kmeans_best_k(data=df, k_range=k_range, random_state=random_state, plot=False)
+        print(f"Best k found: {n_clusters}")
+
     kmeans = KMeans(n_clusters=n_clusters, random_state=random_state, **params)
     kmeans.fit(data)
     df["cluster"] = kmeans.predict(df)
     score = float(silhouette_score(X=data, labels=df["cluster"]))
 
     if plot:
-        cluster_plot(
-            estimator=kmeans,
-            data=data,
-            fields=fields,
-            title=f"K-Means Clustering (k={n_clusters})",
-        )
+
+        if not is_2d(fields):
+            fields = [fields]   # type: ignore
+
+        # cluster_plot(
+        #     estimator=kmeans,
+        #     data=data,
+        #     fields=fields,
+        #     title=f"K-Means Clustering (k={n_clusters})",
+        # )
+        for f in fields:  # type: ignore
+            hs_plot.visualize_silhouette(
+                estimator=kmeans,
+                data=data,
+                xname=f[0],     # type: ignore
+                yname=f[1],     # type: ignore
+                title=f"K-Means Clustering (k={n_clusters})",
+                outline=True,
+            )
 
     return kmeans, df, score
 
@@ -544,6 +564,9 @@ def persona(
         persona_dict[("", f"count")] = len(group)
 
         for field in fields:
+            if field == cluster:
+                continue
+            
             # 명목형일 경우 최빈값 사용
             if df[field].dtype == "object" or df[field].dtype.name == "category":
                 persona_dict[(field, "mode")] = group[field].mode()[0]
@@ -779,7 +802,9 @@ def dbscan_eps(
 
     return best_eps, eps_grid
 
-
+# ===================================================================
+# DBSCAN 군집화 모델을 적합하고 최적의 eps 값을 탐지하는 함수.
+# ===================================================================
 def dbscan_fit(
     data: DataFrame,
     eps: float | list | np.ndarray | None = None,
@@ -789,6 +814,25 @@ def dbscan_fit(
     plot: bool = True,
     **params,
 ) -> tuple[DBSCAN, DataFrame, DataFrame]:
+    """
+    DBSCAN 군집화 모델을 적합하고 최적의 eps 값을 탐지하는 함수.
+
+    Args:
+        data (DataFrame): 군집화할 데이터프레임.
+        eps (float | list | np.ndarray | None, optional): eps 값 또는 리스트.
+            None이면 최적의 eps 값을 탐지함. 기본값 None.
+        min_samples (int, optional): 핵심점이 되기 위한 최소 샘플수. 기본값 5.
+        ari_threshold (float, optional): 안정 구간 탐지를 위한 ARI 임계값. 기본값 0.9.
+        noise_diff_threshold (float, optional): 안정 구간 탐지를 위한 노이즈 비율 변화 임계값. 기본값 0.05.
+        plot (bool, optional): True면 결과를 시각화함. 기본값 True.
+        **params: DBSCAN에 전달할 추가 파라미터.
+
+    Returns:
+        tuple: (estimator, cluster_df, result_df)
+            - estimator: 적합된 DBSCAN 모델 또는 모델 리스트(최적 eps가 여러 개인 경우).
+            - cluster_df: 클러스터 및 벡터 유형이 포함된 데이터 프레임 또는 데이터 프레임 리스트(최적 eps가 여러 개인 경우).
+            - result_df: eps 값에 따른 군집화 요약 통계 데이터 프레임.
+    """
 
     # eps 값이 지정되지 않은 경우 최적의 eps 탐지
     if eps is None:
@@ -874,18 +918,52 @@ def dbscan_fit(
                 # result_dfs에서 recommand가 best에 해당하는 인덱스와 같은 위치의 추정기만 추출
                 best_indexes = list(result_dfs[result_dfs["recommand"] == "best"].index)  # type: ignore
 
-                for i in range(len(estimators) - 1, -1, -1):
-                    if i not in best_indexes:
-                        del estimators[i]
-                        del cluster_dfs[i]
+                # for i in range(len(estimators) - 1, -1, -1):
+                #     if i not in best_indexes:
+                #         del estimators[i]
+                #         del cluster_dfs[i]
 
             pbar.update(1)
 
-    return (
-        estimators[0] if len(estimators) == 1 else estimators,  # type: ignore
-        cluster_dfs[0] if len(cluster_dfs) == 1 else cluster_dfs,
-        result_dfs,  # type: ignore
-    )
+    # best 모델 선정: recommand=='best'인 인덱스의 estimator/cluster_df만 반환
+    if len(estimators) == 1:
+
+        if plot:
+            hs_plot.scatterplot(
+                df=cluster_dfs[0],
+                xname=cluster_dfs[0].columns[0],
+                yname=cluster_dfs[0].columns[1],
+                hue="cluster",
+                vector="vector",
+                title=f"DBSCAN Clustering (eps={estimators[0].eps}, min_samples={estimators[0].min_samples})",
+                outline=True
+            )
+
+        return estimators[0], cluster_dfs[0], result_dfs # type: ignore
+    
+    # recommand=='best'인 인덱스 추출 (여러 개면 첫 번째)
+    best_indexes = list(result_dfs[result_dfs["recommand"] == "best"].index) # type: ignore
+    if not best_indexes:
+        # fallback: 첫 번째
+        best_index = 0
+    else:
+        best_index = best_indexes[0]
+
+    best_estimator = estimators[best_index]
+    best_cluster_df = cluster_dfs[best_index]
+
+    if plot:
+        hs_plot.scatterplot(
+            df=best_cluster_df,
+            xname=best_cluster_df.columns[0],
+            yname=best_cluster_df.columns[1],
+            hue="cluster",
+            vector="vector",
+            title=f"DBSCAN Clustering (eps={best_estimator.eps}, min_samples={best_estimator.min_samples})",
+            outline=True
+        )
+
+    return best_estimator, best_cluster_df, result_dfs # type: ignore
 
 
 # ===================================================================
@@ -950,8 +1028,8 @@ def agg_fit(
 
     Returns:
         tuple: (estimator(s), df(s), score_df)
-            - estimator(s): 적합된 AgglomerativeClustering 모델 또는 모델 리스트.
-            - df(s): 클러스터 결과가 포함된 데이터 프레임 또는 데이터 프레임 리스트.
+            - estimator(s): 적합된 AgglomerativeClustering 모델 또는 모델 리스트 (n_clusters가 리스트일 때 리턴도 리스트로 처리됨).
+            - df(s): 클러스터 결과가 포함된 데이터 프레임 또는 데이터 프레임 리스트(n_cluseters가 리스트일 때 리턴되 리스트로 처리됨).
             - score_df: 각 군집 개수에 대한 실루엣 점수 데이터프레임.
 
     Examples:

{hossam-0.4.17 → hossam-0.4.19}/hossam/hs_plot.py

@@ -8,6 +8,7 @@ from itertools import combinations
 import numpy as np
 import seaborn as sb
 import matplotlib.pyplot as plt
+from matplotlib.figure import Figure  # type: ignore
 from matplotlib.pyplot import Axes  # type: ignore
 from pandas import Series, DataFrame
 from math import sqrt
@@ -132,7 +133,7 @@ def create_figure(
     ws: int | None = None,
     hs: int | None = None,
     title: str | None = None,
-):
+) -> tuple[Figure, Axes]:
     """기본 크기의 Figure와 Axes를 생성한다. get_default_ax의 래퍼 함수.
 
     Args:
@@ -309,7 +310,7 @@ def lineplot(
 # 상자그림(boxplot)을 그린다
 # ===================================================================
 def boxplot(
-    df: DataFrame,
+    df: DataFrame | None = None,
     xname: str | None = None,
     yname: str | None = None,
     title: str | None = None,
@@ -331,7 +332,7 @@ def boxplot(
     """상자그림(boxplot)을 그린다.
 
     Args:
-        df (DataFrame): 시각화할 데이터.
+        df (DataFrame|None): 시각화할 데이터.
         xname (str|None): x축 범주 컬럼명.
         yname (str|None): y축 값 컬럼명.
         title (str|None): 그래프 제목.
@@ -359,13 +360,20 @@ def boxplot(
         fig, ax = get_default_ax(width, height, 1, 1, dpi)  # type: ignore
         outparams = True
 
-    if xname is not None and yname is not None:
+    if xname is not None or yname is not None:
+        if xname is not None and yname is None:
+            orient = "h"
+        elif xname is None and yname is not None:
+            orient = "v"
+
+
         boxplot_kwargs = {
             "data": df,
             "x": xname,
             "y": yname,
             "orient": orient,
             "ax": ax,
+            "linewidth": linewidth,
         }
 
         # hue 파라미터 확인 (params에 있을 수 있음)
@@ -377,12 +385,12 @@ def boxplot(
             boxplot_kwargs["color"] = sb.color_palette(palette)[0]
 
         boxplot_kwargs.update(params)
-        sb.boxplot(**boxplot_kwargs, linewidth=linewidth)
+        sb.boxplot(**boxplot_kwargs)
 
         # 통계 검정 추가
         if stat_test is not None:
             if stat_pairs is None:
-                stat_pairs = [df[xname].dropna().unique().tolist()]
+                stat_pairs = [df[xname].dropna().unique().tolist()] # type: ignore
 
             annotator = Annotator(
                 ax, data=df, x=xname, y=yname, pairs=stat_pairs, orient=orient
@@ -847,15 +855,15 @@ def scatterplot(
     else:
         # 핵심벡터
         scatterplot_kwargs["edgecolor"] = "#ffffff"
-        sb.scatterplot(data=df[df[vector] == "core"], **scatterplot_kwargs)
+        sb.scatterplot(data=df[df[vector] == "core"], **scatterplot_kwargs) # type: ignore
 
         # 외곽백터
         scatterplot_kwargs["edgecolor"] = "#000000"
         scatterplot_kwargs["s"] = 25
         scatterplot_kwargs["marker"] = "^"
         scatterplot_kwargs["linewidth"] = 0.8
-        sb.scatterplot(data=df[df[vector] == "border"], **scatterplot_kwargs)
-
+        sb.scatterplot(data=df[df[vector] == "border"], **scatterplot_kwargs) # type: ignore
+ 
         # 노이즈벡터
         scatterplot_kwargs["edgecolor"] = None
         scatterplot_kwargs["s"] = 25
@@ -1096,14 +1104,9 @@ def pairplot(
         g.fig.suptitle(title, fontsize=config.font_size * 1.5, fontweight="bold")
 
     g.map_lower(
-        func=sb.kdeplot, fill=True, alpha=config.fill_alpha, linewidth=linewidth
+        func=sb.kdeplot, fill=True, alpha=config.fill_alpha
     )
-    g.map_upper(func=sb.scatterplot, linewidth=linewidth)
-
-    # KDE 대각선에도 linewidth 적용
-    for ax in g.axes.diag:  # type: ignore
-        for line in ax.get_lines():
-            line.set_linewidth(linewidth)
+    g.map_upper(func=sb.scatterplot)
 
     plt.tight_layout()
 
@@ -1761,25 +1764,14 @@ def ols_residplot(
         fig, ax = get_default_ax(width + 150 if mse else width, height, 1, 1, dpi)  # type: ignore
         outparams = True
 
-    # 산점도 seaborn으로 그리기
-    sb.scatterplot(x=y_pred, y=resid, ax=ax, s=20, edgecolor="white", **params)
-
-    # 기준선 (잔차 = 0)
-    ax.axhline(0, color="gray", linestyle="--", linewidth=linewidth * 0.7)  # type: ignore
-
-    # LOWESS 스무딩 (선택적)
-    if lowess:
-        lowess_result = sm_lowess(resid, y_pred, frac=0.6667)
-        ax.plot(    # type: ignore
-            lowess_result[:, 0],
-            lowess_result[:, 1],  # type: ignore
-            color="red",
-            linewidth=linewidth,
-            label="LOWESS",
-        )  # type: ignore
-
-    ax.set_xlabel("Fitted values")  # type: ignore
-    ax.set_ylabel("Residuals")  # type: ignore
+    sb.residplot(
+        x=y_pred,
+        y=resid,
+        lowess=True,  # 잔차의 추세선 표시
+        line_kws={"color": "red", "linewidth": linewidth * 0.7},  # 추세선 스타일
+        scatter_kws={"edgecolor": "white", "alpha": config.alpha},
+        **params
+    )
 
     if mse:
         mse_val = mean_squared_error(y, y_pred)
@@ -1909,8 +1901,7 @@ def ols_qqplot(
 
     # 선 굵기 조정
     for line in ax.get_lines():  # type: ignore
-        if line.get_linestyle() == "--" or line.get_color() == "r":  # type: ignore
-            line.set_linewidth(linewidth)  # type: ignore
+        line.set_linewidth(linewidth)  # type: ignore
 
     finalize_plot(ax, callback, outparams, save_path, True, title)  # type: ignore
 
@@ -3022,10 +3013,15 @@ def pca_plot(
         if field_group is not None:
             title += " - " + ", ".join(field_group)
 
+        tdf = DataFrame({
+            field_group[0]: xs * scalex,
+            field_group[1]: ys * scaley,
+        })
+
         scatterplot(
-            df=None,
-            xname=xs * scalex,
-            yname=ys * scaley,
+            df=tdf,
+            xname=field_group[0],
+            yname=field_group[1],
             hue=pca_df[hue] if hue is not None else None,
             outline=False,
             palette=palette,