hossam 0.3.15__py3-none-any.whl → 0.3.17__py3-none-any.whl

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
+
+
 # ===================================================================
 # 지정된 변수에 로그 먼저 변환을 적용한다
 # ===================================================================