hossam 0.3.14__py3-none-any.whl → 0.3.16__py3-none-any.whl

hossam/__init__.py

@@ -15,14 +15,14 @@ except Exception:
 
 hs_fig = SimpleNamespace(
     dpi=200,
-    width=600,
-    height=320,
-    font_size=6,
+    width=800,
+    height=480,
+    font_size=9.5,
     font_weight="light",
-    frame_width=0.4,
-    line_width=1,
+    frame_width=0.5,
+    line_width=1.5,
     grid_alpha=0.3,
-    grid_width=0.4,
+    grid_width=0.5,
     fill_alpha=0.3
 )
 

hossam/hs_plot.py

@@ -56,6 +56,9 @@ def get_default_ax(width: int = hs_fig.width, height: int = hs_fig.height, rows:
         rows (int): 서브플롯 행 개수.
         cols (int): 서브플롯 열 개수.
         dpi (int): 해상도(DPI).
+        flatten (bool): Axes 배열을 1차원 리스트로 평탄화할지 여부.
+        ws (int|None): 서브플롯 가로 간격(`wspace`). rows/cols가 1보다 클 때만 적용.
+        hs (int|None): 서브플롯 세로 간격(`hspace`). rows/cols가 1보다 클 때만 적용.
 
     Returns:
         tuple[Figure, Axes]: 생성된 matplotlib Figure와 Axes 객체.
@@ -100,7 +103,7 @@ def finalize_plot(ax: Axes, callback: any = None, outparams: bool = False, save_
         callback (Callable|None): 추가 설정을 위한 사용자 콜백.
         outparams (bool): 내부에서 생성한 Figure인 경우 True.
         save_path (str|None): 이미지 저장 경로. None이 아니면 해당 경로로 저장.
-        grid (bool): 그리드 표시 여부.
+        grid (bool): 그리드 표시 여부. 기본값은 True입니다.
 
     Returns:
         None
@@ -166,6 +169,7 @@ def lineplot(
         height (int): 캔버스 세로 픽셀.
         linewidth (float): 선 굵기.
         dpi (int): 해상도.
+        save_path (str|None): 이미지 저장 경로. None이면 화면에 표시.
         callback (Callable|None): Axes 후처리 콜백.
         ax (Axes|None): 외부에서 전달한 Axes.
         **params: seaborn lineplot 추가 인자.
@@ -230,6 +234,7 @@ def boxplot(
         height (int): 캔버스 세로 픽셀.
         linewidth (float): 선 굵기.
         dpi (int): 그림 크기 및 해상도.
+        save_path (str|None): 이미지 저장 경로. None이면 화면에 표시.
         callback (Callable|None): Axes 후처리 콜백.
         ax (Axes|None): 외부에서 전달한 Axes.
         **params: seaborn boxplot 추가 인자.
@@ -1847,6 +1852,7 @@ def distribution_by_class(
                 linewidth=linewidth,
                 dpi=dpi,
                 callback=callback,
+                save_path=save_path
             )
         elif type == "hist":
             histplot(
@@ -1861,6 +1867,7 @@ def distribution_by_class(
                 linewidth=linewidth,
                 dpi=dpi,
                 callback=callback,
+                save_path=save_path
             )
         elif type == "histkde":
             histplot(
@@ -1875,6 +1882,7 @@ def distribution_by_class(
                 linewidth=linewidth,
                 dpi=dpi,
                 callback=callback,
+                save_path=save_path
             )
 
 
@@ -1892,6 +1900,7 @@ def scatter_by_class(
     height: int = hs_fig.height,
     linewidth: float = hs_fig.line_width,
     dpi: int = hs_fig.dpi,
+    save_path: str = None,
     callback: any = None,
 ) -> None:
     """종속변수(y)와 각 연속형 독립변수(x) 간 산점도/볼록껍질을 그린다.
@@ -1939,10 +1948,14 @@ def scatter_by_class(
 
     if outline:
         for v in group:
-            convex_hull(data, v[0], v[1], hue, palette, width, height, linewidth, dpi, callback)
+            convex_hull(data=data, xname=v[0], yname=v[1], hue=hue, palette=palette,
+                        width=width, height=height, linewidth=linewidth, dpi=dpi, callback=callback,
+                        save_path=save_path)
     else:
         for v in group:
-            scatterplot(data, v[0], v[1], hue, palette, width, height, linewidth, dpi, callback)
+            scatterplot(data=data, xname=v[0], yname=v[1], hue=hue, palette=palette,
+                        width=width, height=height, linewidth=linewidth, dpi=dpi, callback=callback,
+                        save_path=save_path)
 
 
 # ===================================================================
@@ -1951,7 +1964,7 @@ def scatter_by_class(
 def categorical_target_distribution(
     data: DataFrame,
     yname: str,
-    xnames: list | str | None = None,
+    hue: list | str | None = None,
     kind: str = "box",
     kde_fill: bool = True,
     palette: str | None = None,
@@ -1960,6 +1973,7 @@ def categorical_target_distribution(
     linewidth: float = hs_fig.line_width,
     dpi: int = hs_fig.dpi,
     cols: int = 2,
+    save_path: str = None,
     callback: any = None,
 ) -> None:
     """명목형 변수별로 종속변수 분포 차이를 시각화한다.
@@ -1967,7 +1981,7 @@ def categorical_target_distribution(
     Args:
         data (DataFrame): 시각화할 데이터.
         yname (str): 종속변수 컬럼명(연속형 추천).
-        xnames (list|str|None): 명목형 독립변수 목록. None이면 자동 탐지.
+        hue (list|str|None): 명목형 독립변수 목록. None이면 자동 탐지.
         kind (str): 'box', 'violin', 'kde'.
         kde_fill (bool): kind='kde'일 때 영역 채우기 여부.
         palette (str|None): 팔레트 이름.
@@ -1983,13 +1997,13 @@ def categorical_target_distribution(
     """
 
     # 명목형 컬럼 후보: object, category, bool
-    if xnames is None:
+    if hue is None:
         cat_cols = data.select_dtypes(include=["object", "category", "bool", "boolean"]).columns
         target_cols = [c for c in cat_cols if c != yname]
-    elif isinstance(xnames, str):
-        target_cols = [xnames]
+    elif isinstance(hue, str):
+        target_cols = [hue]
     else:
-        target_cols = list(xnames)
+        target_cols = list(hue)
 
     if len(target_cols) == 0:
         return
@@ -2030,7 +2044,7 @@ def categorical_target_distribution(
 
 
 # ===================================================================
-#
+# ROC 커브를 시각화 한다.
 # ===================================================================
 def roc_curve_plot(
     fit,
@@ -2100,14 +2114,13 @@ def roc_curve_plot(
 
 
 # ===================================================================
-#
+# 혼동행렬 시각화
 # ===================================================================
 def confusion_matrix_plot(
     fit,
     threshold: float = 0.5,
     width: int = hs_fig.width,
     height: int = hs_fig.height,
-    linewidth: float = hs_fig.line_width,
     dpi: int = hs_fig.dpi,
     save_path: str = None,
     callback: any = None,
@@ -2120,7 +2133,6 @@ def confusion_matrix_plot(
         threshold (float): 예측 확률을 이진 분류로 변환할 임계값. 기본값 0.5.
         width (int): 캔버스 가로 픽셀.
         height (int): 캔버스 세로 픽셀.
-        linewidth (float): 선 굵기 (현재 사용되지 않음).
         dpi (int): 해상도.
         callback (Callable|None): Axes 후처리 콜백.
         ax (Axes|None): 외부에서 전달한 Axes. None이면 새로 생성.
@@ -2152,7 +2164,7 @@ def confusion_matrix_plot(
 
 
 # ===================================================================
-#
+# 레이더 차트(방사형 차트)
 # ===================================================================
 def radarplot(
     df: DataFrame,
@@ -2279,3 +2291,118 @@ def radarplot(
         ax.set_title('Radar Chart', pad=20)
 
     finalize_plot(ax, callback, outparams, save_path)
+
+
+# ===================================================================
+# 연속형 데이터 분포 시각화 (KDE + Boxplot)
+# ===================================================================
+def distribution_plot(
+    data: DataFrame,
+    column: str,
+    clevel: float = 0.95,
+    orient: str = "h",
+    hue: str | None = None,
+    kind: str = "boxplot",
+    width: int = hs_fig.width,
+    height: int = hs_fig.height,
+    linewidth: float = hs_fig.line_width,
+    dpi: int = hs_fig.dpi,
+    save_path: str = None,
+    callback: any = None,
+) -> None:
+    """연속형 데이터의 분포를 KDE와 Boxplot으로 시각화한다.
+
+    1행 2열의 서브플롯을 생성하여:
+    - 왼쪽: KDE with 신뢰구간
+    - 오른쪽: Boxplot
+
+    Args:
+        data (DataFrame): 시각화할 데이터.
+        column (str): 분석할 컬럼명.
+        clevel (float): KDE 신뢰수준 (0~1). 기본값 0.95.
+        orient (str): Boxplot 방향 ('v' 또는 'h'). 기본값 'h'.
+        hue (str|None): 명목형 컬럼명. 지정하면 각 범주별로 행을 늘려 KDE와 boxplot을 그림.
+        kind (str): 두 번째 그래프의 유형 (boxplot, hist). 기본값 "boxplot".
+        width (int): 캔버스 가로 픽셀.
+        height (int): 캔버스 세로 픽셀.
+        linewidth (float): 선 굵기.
+        dpi (int): 그림 크기 및 해상도.
+        save_path (str|None): 저장 경로.
+        callback (Callable|None): Axes 후처리 콜백.
+
+    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],
+                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
+
+        fig, axes = get_default_ax(width, height, rows=n_cat, cols=2, dpi=dpi)
+        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=column,
+                clevel=clevel,
+                linewidth=linewidth,
+                ax=left_ax,
+            )
+            left_ax.set_title(f"{hue} = {cat}")
+
+            if kind == "hist":
+                histplot(
+                    df=subset,
+                    xname=column,
+                    linewidth=linewidth,
+                    ax=right_ax,
+                )
+            else:
+                boxplot(
+                    df=subset[column],
+                    linewidth=linewidth,
+                    ax=right_ax
+                )
+
+        fig.suptitle(f"Distribution of {column} 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/hs_prep.py

@@ -10,6 +10,7 @@ from itertools import combinations
 #
 # ===================================================================
 import pandas as pd
+import jenkspy
 from pandas import DataFrame
 from sklearn.preprocessing import StandardScaler, MinMaxScaler
 from sklearn.impute import SimpleImputer
@@ -177,7 +178,7 @@ def set_category(data: DataFrame, *args: str) -> DataFrame:
 
 
 # ===================================================================
-# Melted 형태를 원래 모양으로 복구하여 변수를 펼친다
+# 명목형 변수의 값 종류에 따른 데이터 분리
 # ===================================================================
 def unmelt(
     data: DataFrame, id_vars: str = "class", value_vars: str = "values"
@@ -185,49 +186,32 @@ def unmelt(
     """두 개의 컬럼으로 구성된 데이터프레임에서 하나는 명목형, 나머지는 연속형일 경우
     명목형 변수의 값에 따라 고유한 변수를 갖는 데이터프레임으로 변환한다.
 
+    각 그룹의 데이터 길이가 다를 경우 짧은 쪽에 NaN을 채워 동일한 길이로 맞춥니다.
+    이는 독립표본 t-검정(ttest_ind) 등의 분석을 위한 데이터 준비에 유용합니다.
+
     Args:
         data (DataFrame): 데이터프레임
         id_vars (str, optional): 명목형 변수의 컬럼명. Defaults to 'class'.
         value_vars (str, optional): 연속형 변수의 컬럼명. Defaults to 'values'.
 
     Returns:
-        DataFrame: 변환된 데이터프레임
-    """
-    result = data.groupby(id_vars)[value_vars].apply(list)
-    mydict = {}
-
-    for i in result.index:
-        mydict[i] = result[i]
-
-    return DataFrame(mydict)
-
-
-# ===================================================================
-# 결측치를 평균, 중앙값 등의 전략으로 대체한다
-# ===================================================================
-def replace_missing_value(data: DataFrame, strategy: str = "mean") -> DataFrame:
-    """SimpleImputer로 결측치를 대체한다.
-
-    Args:
-        data (DataFrame): 결측치가 포함된 데이터프레임
-        strategy (str, optional): 결측치 대체 방식(mean, median, most_frequent, constant). Defaults to "mean".
-
-    Returns:
-        DataFrame: 결측치가 대체된 데이터프레임
+        DataFrame: 변환된 데이터프레임 (각 그룹이 개별 컬럼으로 구성)
 
     Examples:
-        >>> from hossam.prep import replace_missing_value
-        >>> out = hs_replace_missing_value(df.select_dtypes(include="number"), strategy="median")
+        >>> df = pd.DataFrame({
+        ...     'group': ['A', 'A', 'B', 'B', 'B'],
+        ...     'value': [1, 2, 3, 4, 5]
+        ... })
+        >>> result = unmelt(df, id_vars='group', value_vars='value')
+        >>> # 결과: A 컬럼에는 [1, 2, NaN], B 컬럼에는 [3, 4, 5]
     """
+    # 그룹별로 값들을 리스트로 모음
+    grouped = data.groupby(id_vars, observed=True)[value_vars].apply(lambda x: x.tolist())
+    series_dict = {}
+    for idx, values in grouped.items():
+        series_dict[str(idx)] = pd.Series(values)
 
-    allowed = {"mean", "median", "most_frequent", "constant"}
-    if strategy not in allowed:
-        raise ValueError(f"strategy는 {allowed} 중 하나여야 합니다.")
-
-    imr = SimpleImputer(missing_values=np.nan, strategy=strategy)
-    df_imr = imr.fit_transform(data.values)
-    return DataFrame(df_imr, index=data.index, columns=data.columns)
-
+    return DataFrame(series_dict)
 
 # ===================================================================
 # 지정된 변수의 이상치 테이블로 반환한다
@@ -439,6 +423,304 @@ def labelling(data: DataFrame, *fields: str) -> DataFrame:
     return df
 
 
+# ===================================================================
+# 연속형 변수를 다양한 기준으로 구간화하여 명목형 변수로 추가한다
+# ===================================================================
+def bin_continuous(
+    data: DataFrame,
+    field: str,
+    method: str = "natural_breaks",
+    bins: int | list[float] | None = None,
+    labels: list[str] | None = None,
+    new_col: str | None = None,
+    is_log_transformed: bool = False,
+    apply_labels: bool = True,
+) -> DataFrame:
+    """연속형 변수를 다양한 알고리즘으로 구간화해 명목형 파생변수를 추가한다.
+
+    지원 방법:
+    - "natural_breaks"(기본): Jenks 자연 구간화. jenkspy 미사용 시 quantile로 대체
+      기본 라벨: "X~Y" 형식 (예: "18~30", "30~40")
+    - "quantile"/"qcut"/"equal_freq": 분위수 기반 동빈도
+      기본 라벨: "X~Y" 형식
+    - "equal_width"/"uniform": 동일 간격
+      기본 라벨: "X~Y" 형식
+    - "std": 평균±표준편차를 경계로 4구간 생성
+      라벨: "low", "mid_low", "mid_high", "high"
+    - "lifecourse"/"life_stage": 생애주기 5단계
+      라벨: "아동", "청소년", "청년", "중년", "노년" (경계: 0, 13, 19, 40, 65)
+    - "age_decade": 10대 단위 연령대
+      라벨: "아동", "10대", "20대", "30대", "40대", "50대", "60대 이상"
+    - "health_band"/"policy_band": 의료비 위험도 기반 연령대
+      라벨: "18-29", "30-39", "40-49", "50-64", "65+"
+    - 커스텀 구간: bins에 경계 리스트 전달 (예: [0, 30, 50, 100])
+
+    Args:
+        data (DataFrame): 입력 데이터프레임
+        field (str): 구간화할 연속형 변수명
+        method (str): 구간화 알고리즘 키워드 (기본값: "natural_breaks")
+        bins (int|list[float]|None):
+            - int: 생성할 구간 개수 (quantile, equal_width, natural_breaks에서 사용)
+            - list: 경계값 리스트 (커스텀 구간화)
+            - None: 기본값 사용 (quantile/equal_width는 4~5, natural_breaks는 5)
+        labels (list[str]|None): 구간 레이블 목록
+            - None: method별 기본 라벨 자동 생성
+            - list: 사용자 정의 라벨 (구간 개수와 일치해야 함)
+        new_col (str|None): 생성할 컬럼명
+            - None: f"{field}_bin" 사용 (예: "age_bin")
+        is_log_transformed (bool): 대상 컬럼이 로그 변환되어 있는지 여부
+            - True: 지정된 컬럼을 역변환(exp)한 후 구간화
+            - False: 원래 값 그대로 구간화 (기본값)
+        apply_labels (bool): 구간에 숫자 인덱스를 적용할지 여부
+            - True: 숫자 인덱스 사용 (0, 1, 2, 3, ...) (기본값)
+            - False: 문자 라벨 적용 (예: "18~30", "아동")
+
+    Returns:
+        DataFrame: 원본에 구간화된 명목형 컬럼이 추가된 데이터프레임
+
+    Examples:
+        동일 간격으로 5개 구간 생성 (숫자 인덱스):
+        >>> df = pd.DataFrame({'age': [20, 35, 50, 65]})
+        >>> result = bin_continuous(df, 'age', method='equal_width', bins=5)
+        >>> print(result['age_bin'])  # 0, 1, 2, ... (숫자 인덱스)
+
+        문자 레이블 사용:
+        >>> result = bin_continuous(df, 'age', method='equal_width', bins=5, apply_labels=False)
+        >>> print(result['age_bin'])  # 20~30, 30~40, ... (문자 레이블)
+
+        생애주기 기반 구간화:
+        >>> result = bin_continuous(df, 'age', method='lifecourse')
+        >>> print(result['age_bin'])  # 0, 1, 2, 3, 4 (숫자 인덱스)
+
+        생애주기 문자 레이블:
+        >>> result = bin_continuous(df, 'age', method='lifecourse', apply_labels=False)
+        >>> print(result['age_bin'])  # 아동, 청소년, 청년, 중년, 노년
+
+        의료비 위험도 기반 연령대 (health_band):
+        >>> result = bin_continuous(df, 'age', method='health_band', apply_labels=False)
+        >>> print(result['age_bin'])  # 18-29, 30-39, 40-49, 50-64, 65+
+
+        로그 변환된 컬럼 역변환 후 구간화:
+        >>> df_log = pd.DataFrame({'charges_log': [np.log(1000), np.log(5000), np.log(50000)]})
+        >>> result = bin_continuous(df_log, 'charges_log', method='equal_width', is_log_transformed=True)
+        >>> print(result['charges_log_bin'])  # 0, 1, 2 (숫자 인덱스)
+    """
+
+    if field not in data.columns:
+        return data
+
+    df = data.copy()
+    series = df[field].copy()
+
+    # 로그 변환 역변환
+    if is_log_transformed:
+        series = np.exp(series)
+
+    new_col = new_col or f"{field}_bin"
+    method_key = (method or "").lower()
+
+    def _cut(edges: list[float], default_labels: list[str] | None = None, right: bool = False, ordered: bool = True):
+        nonlocal labels
+        use_labels = None
+
+        # apply_labels=True일 때 숫자 인덱스, False일 때 문자 레이블
+        if apply_labels:
+            # 숫자 인덱스 생성
+            numeric_labels = list(range(len(edges) - 1))
+            use_labels = numeric_labels
+        else:
+            # 문자 레이블 적용
+            use_labels = labels if labels is not None else default_labels
+
+        df[new_col] = pd.cut(
+            series,
+            bins=edges,
+            labels=use_labels,
+            right=right,
+            include_lowest=True,
+            ordered=False,  # 레이블이 있으므로 ordered=False 사용
+        )
+        df[new_col] = df[new_col].astype("category")
+
+    # 생애주기 구분
+    if method_key in {"lifecourse", "life_stage", "lifecycle", "life"}:
+        edges = [0, 13, 19, 40, 65, np.inf]
+        # 나이 구간을 함께 표기한 라벨 (apply_labels=False에서 사용)
+        default_labels = [
+            "아동(0~12)",
+            "청소년(13~18)",
+            "청년(19~39)",
+            "중년(40~64)",
+            "노년(65+)",
+        ]
+        _cut(edges, default_labels, right=False)
+        return df
+
+    # 연령대(10단위)
+    if method_key in {"age_decade", "age10", "decade"}:
+        edges = [0, 13, 20, 30, 40, 50, 60, np.inf]
+        default_labels = ["아동", "10대", "20대", "30대", "40대", "50대", "60대 이상"]
+        _cut(edges, default_labels, right=False)
+        return df
+
+    # 건강/제도 기준 (의료비 위험군 분류 기준)
+    if method_key in {"health_band", "policy_band", "health"}:
+        # 연령 데이터 최소값(예: 18세)과 레이블을 일치시킴
+        edges = [0, 19, 30, 40, 50, 65, np.inf]
+        default_labels = ["0~18", "19-29", "30-39", "40-49", "50-64", "65+"]
+        _cut(edges, default_labels, right=False)
+        return df
+
+    # 표준편차 기반
+    if method_key == "std":
+        mu = series.mean()
+        sd = series.std(ddof=0)
+        edges = [-np.inf, mu - sd, mu, mu + sd, np.inf]
+        default_labels = ["low", "mid_low", "mid_high", "high"]
+        _cut(edges, default_labels, right=True)
+        return df
+
+    # 동일 간격
+    if method_key in {"equal_width", "uniform"}:
+        k = bins if isinstance(bins, int) and bins > 0 else 5
+        _, edges = pd.cut(series, bins=k, include_lowest=True, retbins=True)
+
+        # apply_labels=True: 숫자 인덱스 / False: 문자 레이블
+        if apply_labels:
+            # 숫자 인덱스 사용 (0, 1, 2, ...)
+            numeric_labels = list(range(len(edges) - 1))
+            df[new_col] = pd.cut(series, bins=edges, labels=numeric_labels, include_lowest=True, ordered=False)
+        else:
+            # 문자 레이블 적용
+            if labels is None:
+                auto_labels = []
+                for i in range(len(edges) - 1):
+                    left = f"{edges[i]:.2f}" if edges[i] != -np.inf else "-∞"
+                    right = f"{edges[i+1]:.2f}" if edges[i+1] != np.inf else "∞"
+                    # 정수값인 경우 소수점 제거
+                    try:
+                        left = str(int(float(left))) if float(left) == int(float(left)) else left
+                        right = str(int(float(right))) if float(right) == int(float(right)) else right
+                    except:
+                        pass
+                    auto_labels.append(f"{left}~{right}")
+                df[new_col] = pd.cut(series, bins=edges, labels=auto_labels, include_lowest=True, ordered=False)
+            else:
+                df[new_col] = pd.cut(series, bins=edges, labels=labels, include_lowest=True, ordered=False)
+
+        df[new_col] = df[new_col].astype("category")
+        return df
+
+    # 분위수 기반 동빈도
+    if method_key in {"quantile", "qcut", "equal_freq"}:
+        k = bins if isinstance(bins, int) and bins > 0 else 4
+        # apply_labels=False일 때 기본 레이블을 사분위수 위치(Q1~)로 설정
+        default_q_labels = labels if labels is not None else [f"Q{i+1}" for i in range(k)]
+        try:
+            if apply_labels:
+                # 숫자 인덱스 사용
+                numeric_labels = list(range(k))
+                df[new_col] = pd.qcut(series, q=k, labels=numeric_labels, duplicates="drop")
+            else:
+                # 사분위수 위치 기반 문자 레이블(Q1, Q2, ...)
+                df[new_col] = pd.qcut(series, q=k, labels=default_q_labels, duplicates="drop")
+        except ValueError:
+            _, edges = pd.cut(series, bins=k, include_lowest=True, retbins=True)
+            # apply_labels=True: 숫자 인덱스 / False: 문자 레이블
+            n_bins = len(edges) - 1
+            if apply_labels:
+                numeric_labels = list(range(n_bins))
+                df[new_col] = pd.cut(series, bins=edges, labels=numeric_labels, include_lowest=True, ordered=False)
+            else:
+                if labels is None:
+                    position_labels = [f"Q{i+1}" for i in range(n_bins)]
+                    df[new_col] = pd.cut(
+                        series, bins=edges, labels=position_labels, include_lowest=True, ordered=False
+                    )
+                else:
+                    df[new_col] = pd.cut(series, bins=edges, labels=labels, include_lowest=True, ordered=False)
+        df[new_col] = df[new_col].astype("category")
+        return df
+
+    # 자연 구간화 (Jenks) - 의존성 없으면 분위수로 폴백
+    if method_key in {"natural_breaks", "natural", "jenks"}:
+        k = bins if isinstance(bins, int) and bins > 1 else 5
+        series_nonnull = series.dropna()
+        k = min(k, max(2, series_nonnull.nunique()))
+        edges = None
+        try:
+            edges = jenkspy.jenks_breaks(series_nonnull.to_list(), nb_class=k)
+            edges[0] = -np.inf
+            edges[-1] = np.inf
+        except Exception:
+            try:
+                use_labels = labels if apply_labels else None
+                df[new_col] = pd.qcut(series, q=k, labels=use_labels, duplicates="drop")
+                df[new_col] = df[new_col].astype("category")
+                return df
+            except Exception:
+                edges = None
+
+        if edges:
+            # apply_labels=True: 숫자 인덱스 / False: 문자 레이블
+            if apply_labels:
+                # 숫자 인덱스 사용
+                numeric_labels = list(range(len(edges) - 1))
+                df[new_col] = pd.cut(series, bins=edges, labels=numeric_labels, include_lowest=True, ordered=False)
+                df[new_col] = df[new_col].astype("category")
+            else:
+                if labels is None:
+                    auto_labels = []
+                    for i in range(len(edges) - 1):
+                        left = f"{edges[i]:.2f}" if edges[i] != -np.inf else "-∞"
+                        right = f"{edges[i+1]:.2f}" if edges[i+1] != np.inf else "∞"
+                        # 정수값인 경우 소수점 제거
+                        try:
+                            left = str(int(float(left))) if float(left) == int(float(left)) else left
+                            right = str(int(float(right))) if float(right) == int(float(right)) else right
+                        except:
+                            pass
+                        auto_labels.append(f"{left}~{right}")
+                    _cut(edges, auto_labels, right=True, ordered=False)
+                else:
+                    _cut(edges, labels, right=True, ordered=False)
+        else:
+            _, cut_edges = pd.cut(series, bins=k, include_lowest=True, retbins=True)
+            if apply_labels:
+                # 숫자 인덱스 사용
+                numeric_labels = list(range(len(cut_edges) - 1))
+                df[new_col] = pd.cut(series, bins=cut_edges, labels=numeric_labels, include_lowest=True, ordered=False)
+            else:
+                if labels is None:
+                    auto_labels = []
+                    for i in range(len(cut_edges) - 1):
+                        left = f"{cut_edges[i]:.2f}" if cut_edges[i] != -np.inf else "-∞"
+                        right = f"{cut_edges[i+1]:.2f}" if cut_edges[i+1] != np.inf else "∞"
+                        # 정수값인 경우 소수점 제거
+                        try:
+                            left = str(int(float(left))) if float(left) == int(float(left)) else left
+                            right = str(int(float(right))) if float(right) == int(float(right)) else right
+                        except:
+                            pass
+                        auto_labels.append(f"{left}~{right}")
+                    df[new_col] = pd.cut(series, bins=cut_edges, labels=auto_labels, include_lowest=True, ordered=False)
+                else:
+                    df[new_col] = pd.cut(series, bins=cut_edges, labels=labels, include_lowest=True, ordered=False)
+            df[new_col] = df[new_col].astype("category")
+        return df
+
+    # 커스텀 경계
+    if isinstance(bins, list) and len(bins) >= 2:
+        edges = sorted(bins)
+        _cut(edges, labels, right=False)
+        return df
+
+    # 기본 폴백: 분위수 4구간
+    df[new_col] = pd.qcut(series, q=4, labels=labels, duplicates="drop")
+    df[new_col] = df[new_col].astype("category")
+    return df
+
+
 # ===================================================================
 # 지정된 변수에 로그 먼저 변환을 적용한다
 # ===================================================================

hossam/hs_stats.py

@@ -2702,3 +2702,155 @@ def predict(fit, data: DataFrame | Series) -> DataFrame | Series | float:
             f"모형 학습 시 사용한 특성과 입력 데이터의 특성이 일치하는지 확인하세요.\n"
             f"원본 오류: {str(e)}"
         )
+
+
+# ===================================================================
+# 확장된 기술통계량 (Extended Descriptive Statistics)
+# ===================================================================
+def summary(data: DataFrame, *fields: str, columns: list = None):
+    """데이터프레임의 연속형 변수에 대한 확장된 기술통계량을 반환한다.
+
+    각 연속형(숫자형) 컬럼의 기술통계량(describe)을 구하고, 이에 사분위수 범위(IQR),
+    이상치 경계값(UP, DOWN), 왜도(skew), 이상치 개수 및 비율, 분포 특성, 로그변환 필요성을
+    추가하여 반환한다.
+
+    Args:
+        data (DataFrame): 분석 대상 데이터프레임.
+        *fields (str): 분석할 컬럼명 목록. 지정하지 않으면 모든 숫자형 컬럼을 처리.
+        columns (list, optional): 반환할 통계량 컬럼 목록. None이면 모든 통계량 반환.
+
+    Returns:
+        DataFrame: 각 필드별 확장된 기술통계량을 포함한 데이터프레임.
+            행은 다음과 같은 통계량을 포함:
+
+            - count (float): 비결측치의 수
+            - mean (float): 평균값
+            - std (float): 표준편차
+            - min (float): 최소값
+            - 25% (float): 제1사분위수 (Q1)
+            - 50% (float): 제2사분위수 (중앙값)
+            - 75% (float): 제3사분위수 (Q3)
+            - max (float): 최대값
+            - iqr (float): 사분위 범위 (Q3 - Q1)
+            - up (float): 이상치 상한 경계값 (Q3 + 1.5 * IQR)
+            - down (float): 이상치 하한 경계값 (Q1 - 1.5 * IQR)
+            - skew (float): 왜도
+            - outlier_count (int): 이상치 개수
+            - outlier_rate (float): 이상치 비율(%)
+            - dist (str): 분포 특성 ("극단 우측 꼬리", "거의 대칭" 등)
+            - log_need (str): 로그변환 필요성 ("높음", "중간", "낮음")
+
+    Examples:
+        전체 숫자형 컬럼에 대한 확장된 기술통계:
+
+        >>> from hossam import summary
+        >>> import pandas as pd
+        >>> df = pd.DataFrame({
+        ...     'x': [1, 2, 3, 4, 5, 100],
+        ...     'y': [10, 20, 30, 40, 50, 60],
+        ...     'z': ['a', 'b', 'c', 'd', 'e', 'f']
+        ... })
+        >>> result = summary(df)
+        >>> print(result)
+
+        특정 컬럼만 분석:
+
+        >>> result = summary(df, 'x', 'y')
+        >>> print(result)
+
+    Notes:
+        - 숫자형이 아닌 컬럼은 자동으로 제외됩니다.
+        - 결과는 필드(컬럼)가 행으로, 통계량이 열로 구성됩니다.
+        - Tukey의 1.5 * IQR 규칙을 사용하여 이상치를 판정합니다.
+        - 분포 특성은 왜도 값으로 판정합니다.
+        - 로그변환 필요성은 왜도의 절댓값 크기로 판정합니다.
+    """
+    if not fields:
+        fields = data.select_dtypes(include=['int', 'int32', 'int64', 'float', 'float32', 'float64']).columns
+
+    # 기술통계량 구하기
+    desc = data[list(fields)].describe().T
+
+    # 추가 통계량 계산
+    additional_stats = []
+    for f in fields:
+        # 숫자 타입이 아니라면 건너뜀
+        if data[f].dtype not in [
+            'int',
+            'int32',
+            'int64',
+            'float',
+            'float32',
+            'float64',
+            'int64',
+            'float64',
+            'float32'
+        ]:
+            continue
+
+        # 사분위수
+        q1 = data[f].quantile(q=0.25)
+        q3 = data[f].quantile(q=0.75)
+
+        # 이상치 경계 (Tukey's fences)
+        iqr = q3 - q1
+        down = q1 - 1.5 * iqr
+        up = q3 + 1.5 * iqr
+
+        # 왜도
+        skew = data[f].skew()
+
+        # 이상치 개수 및 비율
+        outlier_count = ((data[f] < down) | (data[f] > up)).sum()
+        outlier_rate = (outlier_count / len(data)) * 100
+
+        # 분포 특성 판정 (왜도 기준)
+        abs_skew = abs(skew)
+        if abs_skew < 0.5:
+            dist = "거의 대칭"
+        elif abs_skew < 1.0:
+            if skew > 0:
+                dist = "약한 우측 꼬리"
+            else:
+                dist = "약한 좌측 꼬리"
+        elif abs_skew < 2.0:
+            if skew > 0:
+                dist = "중간 우측 꼬리"
+            else:
+                dist = "중간 좌측 꼬리"
+        else:
+            if skew > 0:
+                dist = "극단 우측 꼬리"
+            else:
+                dist = "극단 좌측 꼬리"
+
+        # 로그변환 필요성 판정
+        if abs_skew < 0.5:
+            log_need = "낮음"
+        elif abs_skew < 1.0:
+            log_need = "중간"
+        else:
+            log_need = "높음"
+
+        additional_stats.append({
+            'field': f,
+            'iqr': iqr,
+            'up': up,
+            'down': down,
+            'outlier_count': outlier_count,
+            'outlier_rate': outlier_rate,
+            'skew': skew,
+            'dist': dist,
+            'log_need': log_need
+        })
+
+    additional_df = DataFrame(additional_stats).set_index('field')
+
+    # 결과 병합
+    result = concat([desc, additional_df], axis=1)
+
+    # columns 파라미터가 지정된 경우 해당 컬럼만 필터링
+    if columns is not None:
+        result = result[columns]
+
+    return result

{hossam-0.3.14.dist-info → hossam-0.3.16.dist-info}/METADATA

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

{hossam-0.3.14.dist-info → hossam-0.3.16.dist-info}/RECORD

@@ -1,16 +1,16 @@
 hossam/NotoSansKR-Regular.ttf,sha256=0SCufUQwcVWrWTu75j4Lt_V2bgBJIBXl1p8iAJJYkVY,6185516
-hossam/__init__.py,sha256=_JKBoe04oOsil2xB2Ab4FD9Mat1hm7zngpx2ClJE51g,2609
+hossam/__init__.py,sha256=hJTS1Yl85JqG0iBaVkQcYtguP5f-zO0_wT-ZAouQyzI,2613
 hossam/data_loader.py,sha256=UpC_gn-xUWij0s-MO51qrzJNz3b5-RCz1N6esQMZUJM,6320
 hossam/hs_classroom.py,sha256=b2vzxHapxibnJwcRwWvOfLfczjF-G3ZdT9hIUt4z4oU,27407
 hossam/hs_gis.py,sha256=9ER8gXG2Or0DZ1fpbJR84WsNVPcxu788FsNtR6LsEgo,11379
-hossam/hs_plot.py,sha256=U_rBU6PueGZboe0DzhSWUu3FGWrTdghI2XU9lVRuNg8,73966
-hossam/hs_prep.py,sha256=sHoirbIXfv594SayqReuaVj_KbfjQD3upQ-VLaX27_w,22580
-hossam/hs_stats.py,sha256=a50n8fWOVjsOgKQIzmlkOrAdtDOEzAbNoHvSiIGXc6c,107062
+hossam/hs_plot.py,sha256=7cngzrEeVeBvANyReI9kd3yHZGMOFZjvgBbBGA7rT2E,78467
+hossam/hs_prep.py,sha256=hTHNJvHMVBkV7xthV6igSz0QIKy-bTyVXHzQKblVfQw,36220
+hossam/hs_stats.py,sha256=nhfdZjo4NeyQ3_Pk-xTAN8OLNBDHH8nH9UDtvBNs5AU,112373
 hossam/hs_timeserise.py,sha256=loRofR-m2NMxHaDEWDhZjo6DwayEf4c7qkSoCErfBWY,42165
 hossam/hs_util.py,sha256=E4LnzPlRdWeqICv7TtTL9DT5PogqBhOuTgYiaav565U,7461
 hossam/leekh.png,sha256=1PB5NQ24SDoHA5KMiBBsWpSa3iniFcwFTuGwuOsTHfI,6395
-hossam-0.3.14.dist-info/licenses/LICENSE,sha256=nIqzhlcFY_2D6QtFsYjwU7BWkafo-rUJOQpDZ-DsauI,941
-hossam-0.3.14.dist-info/METADATA,sha256=eoM_2q6o7rV1gNfuDe93bJnDXoA5_CUfVvOgyvJmVqc,13116
-hossam-0.3.14.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-hossam-0.3.14.dist-info/top_level.txt,sha256=_-7bwjhthHplWhywEaHIJX2yL11CQCaLjCNSBlk6wiQ,7
-hossam-0.3.14.dist-info/RECORD,,
+hossam-0.3.16.dist-info/licenses/LICENSE,sha256=nIqzhlcFY_2D6QtFsYjwU7BWkafo-rUJOQpDZ-DsauI,941
+hossam-0.3.16.dist-info/METADATA,sha256=5Yhqjz7S5BTs_OTGaC_l4YzbhQXL8mssrS73hjjCy5s,13116
+hossam-0.3.16.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+hossam-0.3.16.dist-info/top_level.txt,sha256=_-7bwjhthHplWhywEaHIJX2yL11CQCaLjCNSBlk6wiQ,7
+hossam-0.3.16.dist-info/RECORD,,