aiwf 0.3.7 → 0.3.12

package/claude-code/aiwf/ko/personas/data_analyst/best_practices.md

@@ -1,594 +0,0 @@
-# Data Analyst 페르소나 Best Practices
-
-## 개요
-Data Analyst 페르소나는 데이터 분석, 시각화, 인사이트 도출에 중점을 둡니다. 정확성, 해석 가능성, 실행 가능한 인사이트를 최우선으로 고려합니다.
-
-## 핵심 원칙
-
-### 1. 데이터 품질 우선
-- 데이터 정합성 검증
-- 이상치 탐지 및 처리
-- 결측치 처리 전략
-- 데이터 버전 관리
-
-### 2. 재현 가능한 분석
-```python
-# 분석 환경 설정
-import pandas as pd
-import numpy as np
-import matplotlib.pyplot as plt
-import seaborn as sns
-from datetime import datetime
-
-# 재현성을 위한 시드 설정
-np.random.seed(42)
-
-# 분석 메타데이터 기록
-analysis_metadata = {
-    'analyst': 'data_analyst_persona',
-    'date': datetime.now().isoformat(),
-    'version': '1.0.0',
-    'purpose': 'User behavior analysis',
-    'data_sources': ['user_events.csv', 'transactions.csv']
-}
-
-# 데이터 로딩 및 전처리 파이프라인
-class DataPipeline:
-    def __init__(self, config):
-        self.config = config
-        self.raw_data = None
-        self.processed_data = None
-        
-    def load_data(self):
-        """데이터 로딩 with 에러 처리"""
-        try:
-            self.raw_data = pd.read_csv(
-                self.config['data_path'],
-                parse_dates=self.config.get('date_columns', []),
-                encoding='utf-8'
-            )
-            self.log_data_info()
-        except Exception as e:
-            print(f"데이터 로딩 실패: {e}")
-            raise
-            
-    def log_data_info(self):
-        """데이터 기본 정보 로깅"""
-        print(f"데이터 shape: {self.raw_data.shape}")
-        print(f"메모리 사용량: {self.raw_data.memory_usage().sum() / 1024**2:.2f} MB")
-        print(f"결측치 현황:\n{self.raw_data.isnull().sum()}")
-```
-
-### 3. 명확한 시각화 원칙
-```python
-# 시각화 스타일 가이드
-class VisualizationStyle:
-    # 색상 팔레트 정의
-    COLORS = {
-        'primary': '#1f77b4',
-        'secondary': '#ff7f0e',
-        'success': '#2ca02c',
-        'danger': '#d62728',
-        'warning': '#ff9800',
-        'info': '#17a2b8'
-    }
-    
-    @staticmethod
-    def setup_plot_style():
-        """일관된 플롯 스타일 설정"""
-        plt.style.use('seaborn-v0_8-whitegrid')
-        plt.rcParams.update({
-            'figure.figsize': (10, 6),
-            'font.size': 12,
-            'axes.labelsize': 14,
-            'axes.titlesize': 16,
-            'legend.fontsize': 12,
-            'figure.dpi': 100
-        })
-    
-    @staticmethod
-    def add_value_labels(ax, bars, format_string='{:.1f}'):
-        """막대 그래프에 값 레이블 추가"""
-        for bar in bars:
-            height = bar.get_height()
-            ax.annotate(format_string.format(height),
-                       xy=(bar.get_x() + bar.get_width() / 2, height),
-                       xytext=(0, 3),
-                       textcoords="offset points",
-                       ha='center', va='bottom')
-```
-
-## 데이터 분석 워크플로우
-
-### 1. 탐색적 데이터 분석 (EDA)
-```python
-class ExploratoryDataAnalysis:
-    def __init__(self, df):
-        self.df = df
-        
-    def generate_summary_report(self):
-        """종합 요약 리포트 생성"""
-        report = {
-            'basic_info': self.get_basic_info(),
-            'numeric_summary': self.get_numeric_summary(),
-            'categorical_summary': self.get_categorical_summary(),
-            'correlation_analysis': self.get_correlations(),
-            'missing_data': self.analyze_missing_data()
-        }
-        return report
-    
-    def get_basic_info(self):
-        """기본 정보 추출"""
-        return {
-            'shape': self.df.shape,
-            'columns': list(self.df.columns),
-            'dtypes': self.df.dtypes.to_dict(),
-            'memory_usage': self.df.memory_usage(deep=True).sum() / 1024**2,
-            'duplicates': self.df.duplicated().sum()
-        }
-    
-    def get_numeric_summary(self):
-        """수치형 변수 요약"""
-        numeric_cols = self.df.select_dtypes(include=[np.number]).columns
-        summary = {}
-        
-        for col in numeric_cols:
-            summary[col] = {
-                'mean': self.df[col].mean(),
-                'median': self.df[col].median(),
-                'std': self.df[col].std(),
-                'min': self.df[col].min(),
-                'max': self.df[col].max(),
-                'q1': self.df[col].quantile(0.25),
-                'q3': self.df[col].quantile(0.75),
-                'skewness': self.df[col].skew(),
-                'kurtosis': self.df[col].kurtosis(),
-                'outliers': self.detect_outliers(self.df[col])
-            }
-        
-        return summary
-    
-    def detect_outliers(self, series, method='iqr'):
-        """이상치 탐지"""
-        if method == 'iqr':
-            Q1 = series.quantile(0.25)
-            Q3 = series.quantile(0.75)
-            IQR = Q3 - Q1
-            lower_bound = Q1 - 1.5 * IQR
-            upper_bound = Q3 + 1.5 * IQR
-            outliers = series[(series < lower_bound) | (series > upper_bound)]
-            return {
-                'count': len(outliers),
-                'percentage': len(outliers) / len(series) * 100,
-                'indices': outliers.index.tolist()
-            }
-```
-
-### 2. 통계 분석
-```python
-class StatisticalAnalysis:
-    def __init__(self, data):
-        self.data = data
-        
-    def hypothesis_test(self, group1, group2, test_type='t-test', alpha=0.05):
-        """가설 검정 수행"""
-        from scipy import stats
-        
-        # 정규성 검정
-        _, p_value1 = stats.normaltest(group1)
-        _, p_value2 = stats.normaltest(group2)
-        
-        is_normal = p_value1 > alpha and p_value2 > alpha
-        
-        if test_type == 't-test' and is_normal:
-            # 등분산 검정
-            _, p_levene = stats.levene(group1, group2)
-            equal_var = p_levene > alpha
-            
-            # t-검정
-            statistic, p_value = stats.ttest_ind(
-                group1, group2, equal_var=equal_var
-            )
-            test_name = f"{'Welch' if not equal_var else 'Student'}'s t-test"
-        else:
-            # 비모수 검정
-            statistic, p_value = stats.mannwhitneyu(
-                group1, group2, alternative='two-sided'
-            )
-            test_name = "Mann-Whitney U test"
-        
-        return {
-            'test': test_name,
-            'statistic': statistic,
-            'p_value': p_value,
-            'significant': p_value < alpha,
-            'effect_size': self.calculate_effect_size(group1, group2)
-        }
-    
-    def calculate_effect_size(self, group1, group2):
-        """효과 크기 계산 (Cohen's d)"""
-        mean_diff = np.mean(group1) - np.mean(group2)
-        pooled_std = np.sqrt(
-            (np.std(group1, ddof=1) ** 2 + np.std(group2, ddof=1) ** 2) / 2
-        )
-        cohen_d = mean_diff / pooled_std
-        
-        return {
-            'cohen_d': cohen_d,
-            'interpretation': self.interpret_cohen_d(cohen_d)
-        }
-    
-    @staticmethod
-    def interpret_cohen_d(d):
-        """Cohen's d 해석"""
-        d = abs(d)
-        if d < 0.2:
-            return "매우 작은 효과"
-        elif d < 0.5:
-            return "작은 효과"
-        elif d < 0.8:
-            return "중간 효과"
-        else:
-            return "큰 효과"
-```
-
-### 3. 예측 모델링
-```python
-class PredictiveModeling:
-    def __init__(self, X, y):
-        self.X = X
-        self.y = y
-        self.models = {}
-        self.results = {}
-        
-    def train_evaluate_models(self, models_list, cv_folds=5):
-        """여러 모델 학습 및 평가"""
-        from sklearn.model_selection import cross_validate
-        from sklearn.metrics import make_scorer
-        
-        scoring = {
-            'accuracy': 'accuracy',
-            'precision': 'precision_weighted',
-            'recall': 'recall_weighted',
-            'f1': 'f1_weighted',
-            'roc_auc': 'roc_auc_ovr_weighted'
-        }
-        
-        for name, model in models_list.items():
-            print(f"Training {name}...")
-            
-            cv_results = cross_validate(
-                model, self.X, self.y,
-                cv=cv_folds,
-                scoring=scoring,
-                return_train_score=True,
-                n_jobs=-1
-            )
-            
-            self.models[name] = model
-            self.results[name] = self.summarize_cv_results(cv_results)
-            
-    def summarize_cv_results(self, cv_results):
-        """교차 검증 결과 요약"""
-        summary = {}
-        
-        for metric in cv_results:
-            if metric.startswith('test_'):
-                metric_name = metric.replace('test_', '')
-                summary[metric_name] = {
-                    'mean': cv_results[metric].mean(),
-                    'std': cv_results[metric].std(),
-                    'values': cv_results[metric].tolist()
-                }
-                
-        return summary
-    
-    def feature_importance_analysis(self, model_name):
-        """특성 중요도 분석"""
-        model = self.models[model_name]
-        
-        if hasattr(model, 'feature_importances_'):
-            importances = model.feature_importances_
-        elif hasattr(model, 'coef_'):
-            importances = np.abs(model.coef_).ravel()
-        else:
-            return None
-            
-        feature_importance = pd.DataFrame({
-            'feature': self.X.columns,
-            'importance': importances
-        }).sort_values('importance', ascending=False)
-        
-        return feature_importance
-```
-
-## 데이터 시각화 Best Practices
-
-### 1. 대시보드 디자인
-```python
-class DashboardBuilder:
-    def __init__(self, data):
-        self.data = data
-        
-    def create_executive_dashboard(self):
-        """경영진 대시보드 생성"""
-        fig = plt.figure(figsize=(16, 10))
-        gs = fig.add_gridspec(3, 3, hspace=0.3, wspace=0.3)
-        
-        # KPI 카드
-        ax1 = fig.add_subplot(gs[0, :])
-        self.create_kpi_cards(ax1)
-        
-        # 시계열 트렌드
-        ax2 = fig.add_subplot(gs[1, :2])
-        self.create_trend_chart(ax2)
-        
-        # 카테고리별 분포
-        ax3 = fig.add_subplot(gs[1, 2])
-        self.create_category_distribution(ax3)
-        
-        # 히트맵
-        ax4 = fig.add_subplot(gs[2, :2])
-        self.create_correlation_heatmap(ax4)
-        
-        # 상위 10 항목
-        ax5 = fig.add_subplot(gs[2, 2])
-        self.create_top_items(ax5)
-        
-        plt.suptitle('Executive Dashboard', fontsize=20, y=0.98)
-        return fig
-    
-    def create_kpi_cards(self, ax):
-        """KPI 카드 생성"""
-        ax.axis('off')
-        
-        kpis = [
-            {'name': 'Total Revenue', 'value': '$1.2M', 'change': '+15%'},
-            {'name': 'Active Users', 'value': '45.2K', 'change': '+8%'},
-            {'name': 'Conversion Rate', 'value': '3.4%', 'change': '-2%'},
-            {'name': 'Avg Order Value', 'value': '$85', 'change': '+12%'}
-        ]
-        
-        for i, kpi in enumerate(kpis):
-            x = i * 0.25 + 0.125
-            
-            # KPI 박스
-            rect = plt.Rectangle((x - 0.1, 0.2), 0.2, 0.6,
-                               facecolor='lightblue', 
-                               edgecolor='darkblue',
-                               linewidth=2)
-            ax.add_patch(rect)
-            
-            # 텍스트
-            ax.text(x, 0.65, kpi['name'], ha='center', fontsize=12)
-            ax.text(x, 0.5, kpi['value'], ha='center', 
-                   fontsize=18, fontweight='bold')
-            
-            # 변화율
-            color = 'green' if kpi['change'].startswith('+') else 'red'
-            ax.text(x, 0.35, kpi['change'], ha='center', 
-                   fontsize=14, color=color)
-```
-
-### 2. 인터랙티브 시각화
-```python
-import plotly.graph_objects as go
-import plotly.express as px
-from plotly.subplots import make_subplots
-
-class InteractiveVisualizations:
-    def __init__(self, data):
-        self.data = data
-        
-    def create_interactive_scatter(self, x_col, y_col, color_col=None, size_col=None):
-        """인터랙티브 산점도 생성"""
-        fig = px.scatter(
-            self.data,
-            x=x_col,
-            y=y_col,
-            color=color_col,
-            size=size_col,
-            hover_data=self.data.columns,
-            title=f'{y_col} vs {x_col}',
-            labels={x_col: x_col.replace('_', ' ').title(),
-                   y_col: y_col.replace('_', ' ').title()}
-        )
-        
-        # 추세선 추가
-        fig.add_trace(
-            go.Scatter(
-                x=self.data[x_col],
-                y=self.data[y_col].rolling(window=7).mean(),
-                mode='lines',
-                name='7-day MA',
-                line=dict(color='red', dash='dash')
-            )
-        )
-        
-        fig.update_layout(
-            hovermode='closest',
-            template='plotly_white',
-            font=dict(size=12)
-        )
-        
-        return fig
-    
-    def create_animated_timeline(self, date_col, value_col, category_col):
-        """애니메이션 타임라인 차트"""
-        # 데이터 준비
-        df_animated = self.data.sort_values(date_col)
-        
-        fig = px.bar(
-            df_animated,
-            x=category_col,
-            y=value_col,
-            animation_frame=date_col,
-            animation_group=category_col,
-            range_y=[0, df_animated[value_col].max() * 1.1],
-            title=f'{value_col} Timeline by {category_col}'
-        )
-        
-        fig.update_layout(
-            xaxis=dict(categoryorder='total descending'),
-            showlegend=False
-        )
-        
-        return fig
-```
-
-## 보고서 작성 가이드
-
-### 1. 구조화된 인사이트
-```python
-class InsightGenerator:
-    def __init__(self, analysis_results):
-        self.results = analysis_results
-        
-    def generate_insights(self):
-        """자동 인사이트 생성"""
-        insights = []
-        
-        # 트렌드 인사이트
-        if 'trend_analysis' in self.results:
-            trend = self.results['trend_analysis']
-            if trend['slope'] > 0:
-                insights.append({
-                    'type': 'trend',
-                    'severity': 'positive',
-                    'message': f"{trend['metric']}이(가) {trend['period']} 동안 "
-                              f"{trend['change_pct']:.1f}% 증가했습니다.",
-                    'recommendation': "현재 성장 모멘텀을 유지하기 위한 전략 수립 필요"
-                })
-                
-        # 이상치 인사이트
-        if 'anomalies' in self.results:
-            anomalies = self.results['anomalies']
-            if anomalies['count'] > 0:
-                insights.append({
-                    'type': 'anomaly',
-                    'severity': 'warning',
-                    'message': f"{anomalies['count']}개의 이상치가 발견되었습니다.",
-                    'recommendation': "이상치 원인 분석 및 대응 방안 마련 필요"
-                })
-                
-        return insights
-    
-    def create_executive_summary(self):
-        """경영진 요약 보고서 생성"""
-        summary = {
-            'overview': self.generate_overview(),
-            'key_findings': self.extract_key_findings(),
-            'recommendations': self.generate_recommendations(),
-            'next_steps': self.suggest_next_steps()
-        }
-        
-        return self.format_summary(summary)
-```
-
-### 2. 자동화된 리포팅
-```python
-class AutomatedReporting:
-    def __init__(self, template_path):
-        self.template_path = template_path
-        
-    def generate_report(self, data, analysis_results, output_path):
-        """자동 리포트 생성"""
-        from jinja2 import Template
-        import pdfkit
-        
-        # 템플릿 로드
-        with open(self.template_path, 'r') as f:
-            template = Template(f.read())
-            
-        # 데이터 준비
-        context = {
-            'report_date': datetime.now().strftime('%Y-%m-%d'),
-            'summary_stats': self.prepare_summary_stats(data),
-            'charts': self.generate_charts(data),
-            'insights': analysis_results.get('insights', []),
-            'recommendations': analysis_results.get('recommendations', [])
-        }
-        
-        # HTML 생성
-        html = template.render(**context)
-        
-        # PDF 변환
-        options = {
-            'page-size': 'A4',
-            'margin-top': '0.75in',
-            'margin-right': '0.75in',
-            'margin-bottom': '0.75in',
-            'margin-left': '0.75in',
-            'encoding': "UTF-8",
-            'no-outline': None
-        }
-        
-        pdfkit.from_string(html, output_path, options=options)
-        
-        return output_path
-```
-
-## 데이터 거버넌스
-
-### 1. 데이터 품질 모니터링
-```python
-class DataQualityMonitor:
-    def __init__(self, rules):
-        self.rules = rules
-        self.violations = []
-        
-    def check_data_quality(self, df):
-        """데이터 품질 검사"""
-        results = {
-            'passed': 0,
-            'failed': 0,
-            'violations': []
-        }
-        
-        for rule in self.rules:
-            if rule['type'] == 'completeness':
-                passed = self.check_completeness(df, rule)
-            elif rule['type'] == 'uniqueness':
-                passed = self.check_uniqueness(df, rule)
-            elif rule['type'] == 'validity':
-                passed = self.check_validity(df, rule)
-            elif rule['type'] == 'consistency':
-                passed = self.check_consistency(df, rule)
-                
-            if passed:
-                results['passed'] += 1
-            else:
-                results['failed'] += 1
-                results['violations'].append(rule)
-                
-        return results
-    
-    def check_completeness(self, df, rule):
-        """완전성 검사"""
-        column = rule['column']
-        threshold = rule.get('threshold', 0.95)
-        
-        completeness = 1 - (df[column].isnull().sum() / len(df))
-        return completeness >= threshold
-```
-
-## 체크리스트
-
-### 분석 시작 전
-- [ ] 비즈니스 목표 명확화
-- [ ] 데이터 소스 확인
-- [ ] 데이터 품질 검증
-- [ ] 분석 계획 수립
-
-### 분석 진행 중
-- [ ] 가정 사항 문서화
-- [ ] 중간 결과 검증
-- [ ] 이해관계자 피드백
-- [ ] 분석 재현성 확보
-
-### 분석 완료 후
-- [ ] 결과 검증
-- [ ] 인사이트 도출
-- [ ] 시각화 최적화
-- [ ] 보고서 작성
-- [ ] 권고사항 제시