hossam 0.4.5__tar.gz → 0.4.6__tar.gz

{hossam-0.4.5/hossam.egg-info → hossam-0.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hossam
-Version: 0.4.5
+Version: 0.4.6
 Summary: Hossam Data Helper
 Author-email: Lee Kwang-Ho <leekh4232@gmail.com>
 License-Expression: MIT

{hossam-0.4.5 → hossam-0.4.6}/hossam/__init__.py

@@ -6,7 +6,8 @@ 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_util import load_info
+from .hs_util import _load_data_remote as load_data
 
 # py-modules
 import sys

{hossam-0.4.5 → hossam-0.4.6}/hossam/hs_classroom.py

@@ -15,10 +15,10 @@ from .hs_plot import config
 # 학생들을 관심사와 성적으로 균형잡힌 조로 편성한다
 # ===================================================================
 def cluster_students(
-    df,
+    df: DataFrame | str,
     n_groups: int,
-    score_cols: list = None,
-    interest_col: str = None,
+    score_cols: list | None = None,
+    interest_col: str | None = None,
     max_iter: int = 200,
     score_metric: str = 'total'
 ) -> DataFrame:
@@ -173,7 +173,7 @@ def cluster_students(
             df_main,
             actual_n_groups,
             score_cols,
-            interest_col,
+            interest_col,   # type: ignore
             max_iter
         )
     else:
@@ -219,8 +219,8 @@ def cluster_students(
 def _balance_groups(
     df: DataFrame,
     n_groups: int,
-    score_cols: list,
-    interest_col: str = None,
+    score_cols: list | None = None,
+    interest_col: str | None = None,
     max_iter: int = 200
 ) -> DataFrame:
     """조 내 인원과 성적 균형을 조정하는 내부 함수.
@@ -281,7 +281,7 @@ def _balance_groups(
                 count = grade_counts.loc[g, grade]
                 min_g, max_g = grade_bounds[grade]
 
-                if count <= max_g:
+                if count <= max_g:  # type: ignore
                     continue
 
                 donors = group[group['성적그룹'] == grade]
@@ -291,12 +291,12 @@ def _balance_groups(
                     if og == g:
                         continue
                     other_count = grade_counts.loc[og, grade]
-                    if other_count >= min_g:
+                    if other_count >= min_g:    # type: ignore
                         continue
                     other_group = df[df['조'] == og]
 
                     og_interest = dominant_interest(other_group)
-                    need_groups.append((min_g - other_count, og, og_interest))
+                    need_groups.append((min_g - other_count, og, og_interest))  # type: ignore
 
                 need_groups.sort(reverse=True)
 
@@ -392,14 +392,14 @@ def _balance_group_sizes_only(
 # ===================================================================
 # 조 편성 결과의 인원, 관심사, 점수 분포를 시각화한다
 # ===================================================================
-def report_summary(df: DataFrame, interest_col: str = None, width: int = config.width, height: int = config.height, dpi: int = config.dpi) -> None:
+def report_summary(df: DataFrame, interest_col: str | None = None, width: int = config.width, height: int = config.height, dpi: int = config.dpi) -> None:
     """조 편성 결과의 요약 통계를 시각화합니다.
 
     조별 인원 분포, 관심사 분포, 평균점수 분포를 나타냅니다.
 
     Args:
         df (DataFrame): cluster_students 함수의 반환 결과 데이터프레임.
-        interest_col (str): 관심사 컬럼명
+        interest_col (str | None): 관심사 컬럼명
         width (int): 그래프 넓이. 기본값: config.width
         height (int): 그래프 높이. 기본값: config.height
         dpi (int): 그래프 해상도. 기본값: config.dpi
@@ -540,24 +540,24 @@ def report_summary(df: DataFrame, interest_col: str = None, width: int = config.
         plot_idx += 1
 
     # hs_plot.finalize_plot을 사용하여 마무리
-    hs_plot.finalize_plot(axes, outparams=True, grid=False)
+    hs_plot.finalize_plot(axes, outparams=True, grid=False) # type: ignore
 
 
 # ===================================================================
 # 조별 점수 분포를 커널 밀도 추정(KDE) 그래프로 시각화한다
 # ===================================================================
-def report_kde(df: DataFrame, metric: str = 'average', width: int = config.width, height: int = config.height, dpi: int = config.dpi) -> None:
+def report_kde(df: DataFrame | str, metric: str = 'average', width: int = config.width, height: int = config.height, dpi: int = config.dpi) -> None:
     """조별 점수 분포를 KDE(Kernel Density Estimation)로 시각화합니다.
 
     각 조의 점수 분포를 커널 밀도 추정으로 표시하고 평균 및 95% 신뢰구간을 나타냅니다.
 
     Args:
-        df: cluster_students 함수의 반환 결과 데이터프레임.
-        metric: 점수 기준 선택 ('total' 또는 'average').
+        df (DataFrame | str): cluster_students 함수의 반환 결과 데이터프레임.
+        metric (str): 점수 기준 선택 ('total' 또는 'average').
             'total'이면 총점, 'average'이면 평균점수. 기본값: 'average'
-        width: 그래프 넓이. 기본값: config.width
-        height: 그래프 높이. 기본값: config.height
-        dpi: 그래프 해상도. 기본값: config.dpi
+        width (int): 그래프 넓이. 기본값: config.width
+        height (int): 그래프 높이. 기본값: config.height
+        dpi (int): 그래프 해상도. 기본값: config.dpi
 
     Examples:
         ```python
@@ -570,17 +570,17 @@ def report_kde(df: DataFrame, metric: str = 'average', width: int = config.width
         print("데이터프레임이 비어있습니다")
         return
 
-    if '조' not in df.columns:
+    if '조' not in df.columns:  # type: ignore
         print("데이터프레임에 '조' 컬럼이 없습니다")
         return
 
-    has_score = '총점' in df.columns
-    has_avg = '평균점수' in df.columns
+    has_score = '총점' in df.columns    # type: ignore
+    has_avg = '평균점수' in df.columns  # type: ignore
     if not has_score:
         print("점수 데이터가 없습니다")
         return
 
-    labels = df['조'].unique().tolist()
+    labels = df['조'].unique().tolist() # type: ignore
     def _sort_key(v):
         try:
             return (0, int(v))
@@ -596,18 +596,18 @@ def report_kde(df: DataFrame, metric: str = 'average', width: int = config.width
 
     plot_idx = 0
     metric_col = '평균점수' if (metric or '').lower() == 'average' else '총점'
-    if metric_col not in df.columns:
+    if metric_col not in df.columns:    # type: ignore
         print(f"'{metric_col}' 컬럼이 없습니다")
         return
 
     for group in ordered_labels:
-        group_df = df[df['조'] == group]
-        group_series = group_df[metric_col].dropna()
+        group_df = df[df['조'] == group]    # type: ignore
+        group_series = group_df[metric_col].dropna()    # type: ignore
         n = group_series.size
         if n == 0:
             continue
 
-        hs_plot.kde_confidence_interval(data=group_df, xnames=metric_col, ax=axes[plot_idx], callback=lambda ax: ax.set_title(f"{group}조"))
+        hs_plot.kde_confidence_interval(data=group_df, xnames=metric_col, ax=axes[plot_idx], callback=lambda ax: ax.set_title(f"{group}조"))    # type: ignore
 
         plot_idx += 1
 
@@ -615,7 +615,7 @@ def report_kde(df: DataFrame, metric: str = 'average', width: int = config.width
     for idx in range(plot_idx, len(axes)):
         fig.delaxes(axes[idx])
 
-    hs_plot.finalize_plot(axes)
+    hs_plot.finalize_plot(axes) # type: ignore
 
 
 # ===================================================================
@@ -690,10 +690,10 @@ def group_summary(df: DataFrame, name_col: str = '학생이름') -> DataFrame:
 # 학생 조 편성부터 시각화까지의 전체 분석 프로세스를 일괄 실행한다
 # ===================================================================
 def analyze_classroom(
-    df,
+    df: DataFrame | str,
     n_groups: int,
-    score_cols: list = None,
-    interest_col: str = None,
+    score_cols: list | None = None,
+    interest_col: str | None = None,
     max_iter: int = 200,
     score_metric: str = 'average',
     name_col: str = '학생이름',

{hossam-0.4.5 → hossam-0.4.6}/hossam/hs_plot.py

@@ -73,7 +73,7 @@ def get_default_ax(width: int = config.width, height: int = config.height, rows:
     if is_array and (ws != None and hs != None):
         fig.subplots_adjust(wspace=ws, hspace=hs)
 
-    if title and not is_array:
+    if title and is_array:
         fig.suptitle(title, fontsize=config.font_size * 1.5, fontweight='bold')
 
     if flatten == True:
@@ -126,7 +126,7 @@ def create_figure(width: int = config.width, height: int = config.height, rows:
 # ===================================================================
 # 그래프의 그리드, 레이아웃을 정리하고 필요 시 저장 또는 표시한다
 # ===================================================================
-def finalize_plot(ax: Axes | np.ndarray, callback: Callable | None = None, outparams: bool = False, save_path: str | None = None, grid: bool = True, title: str | None = None) -> None:
+def finalize_plot(ax: Axes | np.ndarray | list, callback: Callable | None = None, outparams: bool = False, save_path: str | None = None, grid: bool = True, title: str | None = None) -> None:
     """공통 후처리를 수행한다: 콜백 실행, 레이아웃 정리, 필요 시 표시/종료.
 
     Args:
@@ -270,6 +270,10 @@ def boxplot(
     yname: str | None = None,
     title: str | None = None,
     orient: str = "v",
+    stat_test: str | None = None,
+    stat_pairs: list[tuple] | None = None,
+    stat_text_format: str = "star",
+    stat_loc: str = "inside",
     palette: str | None = None,
     width: int = config.width,
     height: int = config.height,
@@ -288,6 +292,10 @@ def boxplot(
         yname (str|None): y축 값 컬럼명.
         title (str|None): 그래프 제목.
         orient (str): 'v' 또는 'h' 방향.
+        stat_test (str|None): 통계 검정 방법. None이면 검정 안함. xname과 yname이 모두 지정되어야 함.
+        stat_pairs (list[tuple]|None): 통계 검정할 그룹 쌍 목록.
+        stat_text_format (str): 통계 결과 표시 형식.
+        stat_loc (str): 통계 결과 위치.
         palette (str|None): 팔레트 이름.
         width (int): 캔버스 가로 픽셀.
         height (int): 캔버스 세로 픽셀.
@@ -326,12 +334,67 @@ def boxplot(
 
         boxplot_kwargs.update(params)
         sb.boxplot(**boxplot_kwargs, linewidth=linewidth)
+
+        # 통계 검정 추가
+        if stat_test is not None:
+            if stat_pairs is None:
+                stat_pairs = [df[xname].dropna().unique().tolist()]
+
+            annotator = Annotator(ax, data=df, x=xname, y=yname, pairs=stat_pairs, orient=orient)
+            annotator.configure(test=stat_test, text_format=stat_text_format, loc=stat_loc)
+            annotator.apply_and_annotate()
     else:
         sb.boxplot(data=df, orient=orient, ax=ax, linewidth=linewidth, **params)    # type: ignore
 
     finalize_plot(ax, callback, outparams, save_path, True, title) # type: ignore
 
 
+# ===================================================================
+# 상자그림에 p-value 주석을 추가한다
+# ===================================================================
+def pvalue1_anotation(
+    data: DataFrame,
+    target: str,
+    hue: str,
+    title: str | None = None,
+    pairs: list | None = None,
+    test: str = "t-test_ind",
+    text_format: str = "star",
+    loc: str = "outside",
+    width: int = config.width,
+    height: int = config.height,
+    linewidth: float = config.line_width,
+    dpi: int = config.dpi,
+    save_path: str | None = None,
+    callback: Callable | None = None,
+    ax: Axes | None = None,
+    **params
+) -> None:
+    """
+    boxplot의 wrapper 함수로, 상자그림에 p-value 주석을 추가한다.
+    """
+    boxplot(
+        data,
+        xname=hue,
+        yname=target,
+        title=title,
+        orient="v",
+        stat_test=test,
+        stat_pairs=pairs,
+        stat_text_format=text_format,
+        stat_loc=loc,
+        palette=None,
+        width=width,
+        height=height,
+        linewidth=linewidth,
+        dpi=dpi,
+        save_path=save_path,
+        callback=callback,
+        ax=ax,
+        **params
+    )
+
+
 # ===================================================================
 # 커널 밀도 추정(KDE) 그래프를 그린다
 # ===================================================================
@@ -756,7 +819,12 @@ def regplot(
         "data": df,
         "x": xname,
         "y": yname,
-        "scatter_kws": {"color": scatter_color} if scatter_color else {},
+        "scatter_kws": {
+            "s": 20,
+            "linewidths": 0.5,
+            "edgecolor": "w",
+            "color": scatter_color
+        },
         "line_kws": {
             "color": "red",
             "linestyle": "--",
@@ -1088,7 +1156,7 @@ def barplot(
 
 
 # ===================================================================
-# 바이올린 플롯을 그린다
+# boxen 플롯을 그린다
 # ===================================================================
 def boxenplot(
     df: DataFrame,
@@ -1598,88 +1666,6 @@ def kde_confidence_interval(
     finalize_plot(axes[0] if isinstance(axes, list) and len(axes) > 0 else ax, callback, outparams, save_path, True, title) # type: ignore
 
 
-# ===================================================================
-# 상자그림에 p-value 주석을 추가한다
-# ===================================================================
-def pvalue1_anotation(
-    data: DataFrame,
-    target: str,
-    hue: str,
-    title: str | None = None,
-    pairs: list | None = None,
-    test: str = "t-test_ind",
-    text_format: str = "star",
-    loc: str = "outside",
-    width: int = config.width,
-    height: int = config.height,
-    linewidth: float = config.line_width,
-    dpi: int = config.dpi,
-    save_path: str | None = None,
-    callback: Callable | None = None,
-    ax: Axes | None = None,
-    **params
-) -> None:
-    """statannotations를 이용해 상자그림에 p-value 주석을 추가한다.
-
-    Args:
-        data (DataFrame): 시각화할 데이터.
-        target (str): 값 컬럼명.
-        hue (str): 그룹 컬럼명.
-        title (str|None): 그래프 제목.
-        pairs (list|None): 비교할 (group_a, group_b) 튜플 목록. None이면 hue 컬럼의 모든 고유값 조합을 자동 생성.
-        test (str): 적용할 통계 검정 이름.
-        text_format (str): 주석 형식('star' 등).
-        loc (str): 주석 위치.
-        width (int): 캔버스 가로 픽셀.
-        height (int): 캔버스 세로 픽셀.
-        linewidth (float): 선 굵기.
-        dpi (int): 그림 크기 및 해상도.
-        callback (Callable|None): Axes 후처리 콜백.
-        ax (Axes|None): 외부에서 전달한 Axes.
-        **params: seaborn boxplot 추가 인자.
-
-    Returns:
-        None
-    """
-    # pairs가 None이면 hue 컬럼의 고유값으로 모든 조합 생성
-    if pairs is None:
-        from itertools import combinations
-        unique_values = sorted(data[hue].unique())
-        pairs = list(combinations(unique_values, 2))
-
-    outparams = False
-
-    if ax is None:
-        fig, ax = get_default_ax(width, height, 1, 1, dpi)  # type: ignore
-        outparams = True
-
-    # params에서 palette 추출 (있으면)
-    palette_value = params.pop("palette", None)
-
-    # boxplot kwargs 구성
-    boxplot_kwargs = {
-        "data": data,
-        "x": hue,
-        "y": target,
-        "linewidth": linewidth,
-        "ax": ax,
-    }
-
-    # palette가 있으면 추가 (hue는 x에 이미 할당됨)
-    if palette_value is not None:
-        boxplot_kwargs["palette"] = palette_value
-
-    boxplot_kwargs.update(params)
-
-    sb.boxplot(**boxplot_kwargs)
-    annotator = Annotator(ax, data=data, x=hue, y=target, pairs=pairs)
-    annotator.configure(test=test, text_format=text_format, loc=loc)
-    annotator.apply_and_annotate()
-
-    sb.despine()
-    finalize_plot(ax, callback, outparams, save_path, True, title)  # type: ignore
-
-
 
 # ===================================================================
 # 잔차도 (선형회귀의 선형성 검정)
@@ -1741,7 +1727,7 @@ def ols_residplot(
         outparams = True
 
     # 산점도 seaborn으로 그리기
-    sb.scatterplot(x=y_pred, y=resid, ax=ax, s=0.5, edgecolor="white", alpha=config.fill_alpha, **params)
+    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
@@ -1795,13 +1781,13 @@ def ols_residplot(
         for i, c in enumerate(["red", "green", "blue"]):
             ax.text(    # type: ignore
                 s=f"{i+1} sqrt(MSE) = {mse_r[i]:.2f}% ({mse_r[i] - target[i]:.2f}%)",
-                x=xmax + 0.2,
+                x=xmax + 0.05,
                 y=(i + 1) * mse_sq,
                 color=c,
             )
             ax.text(    # type: ignore
                 s=f"-{i+1} sqrt(MSE) = {mse_r[i]:.2f}% ({mse_r[i] - target[i]:.2f}%)",
-                x=xmax + 0.2,
+                x=xmax + 0.05,
                 y=-(i + 1) * mse_sq,
                 color=c,
             )
@@ -2146,7 +2132,7 @@ def categorical_target_distribution(
             plot_kwargs.update({"x": yname, "hue": col, "palette": palette, "fill": kde_fill, "common_norm": False, "linewidth": linewidth})
             sb.kdeplot(**plot_kwargs)
         else:  # box
-            plot_kwargs.update({"x": col, "y": yname, "palette": palette})
+            plot_kwargs.update({"x": col, "y": yname, "hue": col, "palette": palette})
             sb.boxplot(**plot_kwargs, linewidth=linewidth)
 
         ax.set_title(f"{col} vs {yname}")
@@ -2419,8 +2405,7 @@ def radarplot(
 # ===================================================================
 def distribution_plot(
     data: DataFrame,
-    column: str,
-    title: str | None = None,
+    column: str | list[str],
     clevel: float = 0.95,
     orient: str = "h",
     hue: str | None = None,
@@ -2441,7 +2426,6 @@ def distribution_plot(
     Args:
         data (DataFrame): 시각화할 데이터.
         column (str): 분석할 컬럼명.
-        title (str|None): 그래프 제목.
         clevel (float): KDE 신뢰수준 (0~1). 기본값 0.95.
         orient (str): Boxplot 방향 ('v' 또는 'h'). 기본값 'h'.
         hue (str|None): 명목형 컬럼명. 지정하면 각 범주별로 행을 늘려 KDE와 boxplot을 그림.
@@ -2456,76 +2440,82 @@ def distribution_plot(
     Returns:
         None
     """
-    if hue is None:
-        # 1행 2열 서브플롯 생성
-        fig, axes = get_default_ax(width, height, rows=1, cols=2, dpi=dpi)
-
-        kde_confidence_interval(
-            data=data,
-            xnames=column,
-            clevel=clevel,
-            linewidth=linewidth,
-            ax=axes[0],
-        )
-
-        if kind == "hist":
-            histplot(
-                df=data,
-                xname=column,
-                linewidth=linewidth,
-                ax=axes[1]
-            )
-        else:
-            boxplot(
-                df=data[column],        # type: ignore
-                linewidth=linewidth,
-                ax=axes[1]
-            )
-
-        fig.suptitle(f"Distribution of {column}", fontsize=14, y=1.02)
-    else:
-        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())
-        n_cat = len(categories) if categories else 1
+    if isinstance(column, str):
+        column = [column]
 
-        fig, axes = get_default_ax(width, height, rows=n_cat, cols=2, dpi=dpi)
-        axes_2d = np.atleast_2d(axes)
+    for c in column:
+        title = f"Distribution Plot of {c}"
 
-        for idx, cat in enumerate(categories):
-            subset = data[data[hue] == cat]
-            left_ax, right_ax = axes_2d[idx, 0], axes_2d[idx, 1]
+        if hue is None:
+            # 1행 2열 서브플롯 생성
+            fig, axes = get_default_ax(width, height, rows=1, cols=2, dpi=dpi, title=title)
 
             kde_confidence_interval(
-                data=subset,
-                xnames=column,
+                data=data,
+                xnames=c,
                 clevel=clevel,
                 linewidth=linewidth,
-                ax=left_ax,
+                ax=axes[0],
             )
-            left_ax.set_title(f"{hue} = {cat}")
 
             if kind == "hist":
                 histplot(
-                    df=subset,
-                    xname=column,
+                    df=data,
+                    xname=c,
                     linewidth=linewidth,
-                    ax=right_ax,
+                    ax=axes[1]
                 )
             else:
                 boxplot(
-                    df=subset[column], # type: ignore
+                    df=data[column],        # type: ignore
                     linewidth=linewidth,
-                    ax=right_ax
+                    ax=axes[1]
                 )
 
-        fig.suptitle(f"Distribution of {column} by {hue}", fontsize=14, y=1.02)
+            fig.suptitle(title, fontsize=14, y=1.02)
+        else:
+            if hue not in data.columns:
+                raise ValueError(f"hue column '{hue}' not found in DataFrame")
 
-    plt.tight_layout()
+            categories = list(pd.Series(data[hue].dropna().unique()).sort_values())
+            n_cat = len(categories) if categories else 1
 
-    if save_path:
-        plt.savefig(save_path, bbox_inches='tight', dpi=dpi)
-        plt.close()
-    else:
-        plt.show()
+            fig, axes = get_default_ax(width, height, rows=n_cat, cols=2, dpi=dpi, title=title)
+            axes_2d = np.atleast_2d(axes)
+
+            for idx, cat in enumerate(categories):
+                subset = data[data[hue] == cat]
+                left_ax, right_ax = axes_2d[idx, 0], axes_2d[idx, 1]
+
+                kde_confidence_interval(
+                    data=subset,
+                    xnames=c,
+                    clevel=clevel,
+                    linewidth=linewidth,
+                    ax=left_ax,
+                )
+                left_ax.set_title(f"{hue} = {cat}")
+
+                if kind == "hist":
+                    histplot(
+                        df=subset,
+                        xname=c,
+                        linewidth=linewidth,
+                        ax=right_ax,
+                    )
+                else:
+                    boxplot(
+                        df=subset[c], # type: ignore
+                        linewidth=linewidth,
+                        ax=right_ax
+                    )
+
+            fig.suptitle(f"{title} by {hue}", fontsize=14, y=1.02)
+
+            plt.tight_layout()
+
+            if save_path:
+                plt.savefig(save_path, bbox_inches='tight', dpi=dpi)
+                plt.close()
+            else:
+                plt.show()

{hossam-0.4.5 → hossam-0.4.6}/hossam/hs_prep.py

@@ -764,7 +764,7 @@ def bin_continuous(
 # ===================================================================
 # 지정된 변수에 로그 먼저 변환을 적용한다
 # ===================================================================
-def log_transform(data: DataFrame, *fields: str) -> DataFrame:
+def log_transform(data: DataFrame, *fields: str, columns: list | None = None) -> DataFrame:
     """수치형 변수에 대해 로그 변환을 수행한다.
 
     자연로그(ln)를 사용하여 변환하며, 0 또는 음수 값이 있을 경우
@@ -773,6 +773,7 @@ def log_transform(data: DataFrame, *fields: str) -> DataFrame:
     Args:
         data (DataFrame): 변환할 데이터프레임.
         *fields (str): 변환할 컬럼명 목록. 지정하지 않으면 모든 수치형 컬럼을 처리.
+        columns (list, optional): 변환할 컬럼명 목록. fields와 중복 사용 불가.
 
     Returns:
         DataFrame: 로그 변환된 데이터프레임.
@@ -799,6 +800,11 @@ def log_transform(data: DataFrame, *fields: str) -> DataFrame:
     """
     df = data.copy()
 
+    if columns is not None:
+        if fields:
+            raise ValueError("fields와 columns 인자는 중복 사용할 수 없습니다.")
+        fields = columns # type: ignore
+
     # 대상 컬럼 결정
     if not fields:
         # 모든 수치형 컬럼 선택