new-value-analysis 0.1.3
New Value Analysis: actor/action/opportunity 분석 유틸리티 패키지
License: MIT
Requires Python: >=3.9

# New Value Analysis

`new_value_analysis`는 **신규가치분석(New Value Analysis)**을 수행하기 위한
Python 기반 분석 유틸리티 라이브러리입니다.

텍스트 데이터 기반으로
**Action(행동) → Actor(행위자) → Opportunity Area(기회영역)** 분석 파이프라인을
일관된 구조로 수행할 수 있도록 설계되었습니다.

---

## 📦 Installation

```bash
pip install new_value_analysis
```

> Python 3.9 이상 권장

---

## 📚 Core Concept

본 라이브러리는 다음과 같은 **3단계 분석 흐름**을 전제로 합니다.

```
[Action Finder]
텍스트 데이터 → 토픽 모델링 → 행동(Action) 정의

[Actor Finder]
문서 임베딩 → 군집 분석 → 행위자(Actor) 유형화

[Opportunity Area Analysis]
중요도 × 만족도 → 기회영역(Opportunity Area) 도출
```

---

## 📁 Package Structure

```text
new_value_analysis
├─ action_finder
│  ├─ topic_modeling.py          # LDA 학습
│  ├─ find_topicnum.py           # 토픽 수 탐색
│  └─ select_action_number.py    # 문서별 Action 번호 할당
│
├─ actor_finder
│  ├─ doc2vec.py                 # Doc2Vec 임베딩
│  ├─ find_right_silhouette.py   # 최적 군집 수 탐색
│  ├─ silhouette_plot.py         # 실루엣 플롯
│  └─ visualize_dendrogram.py    # 덴드로그램 시각화
│
└─ opportunity_area_analysis
   ├─ satisfaction_scaling.py    # 점수 스케일링
   └─ opportunity_plot.py        # Opportunity Area 시각화
```

---

## 1️⃣ Action Finder

### 목적

* 텍스트 데이터에서 **행동(Action)**을 추출
* 문서별로 어떤 행동을 가장 강하게 드러내는지 식별

### 주요 기능

```python
from new_value_analysis.action_finder import (
    LDA_train,
    assign_action_number
)
```

### 예시 흐름

```python
# 1. LDA 모델 학습
lda_model, corpus, dictionary = LDA_train(texts)

# 2. 문서별 Action 번호 할당
df["action_number"] = assign_action_number(lda_model, corpus)
```

---

## 2️⃣ Actor Finder

### 목적

* 문서를 **행위자(Actor) 관점에서 군집화**
* “어떤 유형의 사람이 어떤 행동을 하는가?”를 구조화

### 주요 기능

```python
from new_value_analysis.actor_finder import (
    train_doc2vec_module,
    agglomerative_silhouette_module,
    visualize_silhouette,
    plot_dendrogram
)
```

### 예시 흐름

```python
# 1. Doc2Vec 임베딩
model, vectors, tagged_docs = train_doc2vec_module(
    df,
    token_col="tagged_review"
)
df["vector"] = vectors

# 2. 최적 군집 수 탐색
scores, best_k = agglomerative_silhouette_module(df)

# 3. 군집 품질 시각화
visualize_silhouette([2, 3, 4, 5], vectors)

# 4. 덴드로그램 확인
plot_dendrogram(df)
```

---

## 3️⃣ Opportunity Area Analysis

### 목적

* 중요도 × 만족도 기반으로 **기회영역(Opportunity Area)** 도출
* “노력 대비 가치가 큰 영역”을 시각적으로 식별

### 주요 기능

```python
from new_value_analysis.opportunity_area_analysis import (
    minmax_scale_scores,
    plot_opportunity_area
)
```

### 예시 흐름

```python
# 1. 점수 스케일링
df_scaled = minmax_scale_scores(df)

# 2. Opportunity Area 시각화
plot_opportunity_area(
    importance=df_scaled["importance"],
    satisfaction=df_scaled["satisfaction"],
    labels=df_scaled["action_label"]
)
```

---

## 🧠 Recommended Workflow

```text
텍스트 수집
   ↓
전처리 / 토큰화
   ↓
Action Finder (행동 정의)
   ↓
Actor Finder (행위자 유형화)
   ↓
Opportunity Area Analysis (기회영역 도출)
```

---

## 🎓 Use Cases

* AI 서비스 기획 / UX 리서치
* VOC / 리뷰 데이터 기반 서비스 개선
* 공공 데이터 기반 정책 기획
* 교육 과정(부트캠프) 분석 프로젝트


## ✨ Versioning

* **v0.1.0**

  * Initial public release
  * Action / Actor / Opportunity 분석 파이프라인 제공