dual-wordcloud 0.1.0__tar.gz

dual_wordcloud-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+.pytest_cache/
+*.egg-info/

dual_wordcloud-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: dual-wordcloud
+Version: 0.1.0
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: matplotlib-venn>=0.11.0
+Requires-Dist: matplotlib>=3.8.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: shapely>=2.0.0
+Requires-Dist: wordcloud>=1.9.0
+Description-Content-Type: text/markdown
+
+# dual-wordcloud
+
+Venn diagram–style wordcloud that splits keywords across three regions: left-only, shared (center), and right-only.
+
+## Installation
+
+```bash
+pip install dual-wordcloud
+```
+
+## Usage
+
+### Mode 1: Direct regions (`from_regions`)
+
+Use when you already have keywords pre-divided into three groups — e.g. positive / neutral / negative sentiment.
+
+```python
+from collections import Counter
+from dual_wordcloud import DualWordCloud
+
+positive = Counter({"성장": 42, "혁신": 35, "안정": 28})
+neutral  = Counter({"금리": 20, "실적": 18})
+negative = Counter({"손실": 30, "위기": 25, "부채": 15})
+
+dwc = DualWordCloud.from_regions(
+    left=positive,
+    center=neutral,
+    right=negative,
+    left_label="긍정",
+    right_label="부정",
+    left_border_color="#3498db",
+    right_border_color="#e74c3c",
+)
+dwc.to_file("sentiment.png")
+```
+
+### Mode 2: Comparison (`from_comparison`)
+
+Use when you have two raw keyword counters and want to compare them. Keyword placement (left / center / right) is determined automatically by normalized frequency ratio.
+
+```python
+from collections import Counter
+from dual_wordcloud import DualWordCloud
+
+bnk   = Counter({"대출": 120, "금리": 95, "부채": 40, "성장": 60})
+hana  = Counter({"예금": 110, "금리": 88, "투자": 75, "성장": 58})
+
+dwc = DualWordCloud.from_comparison(
+    left=bnk,
+    right=hana,
+    count_left=1000,   # total articles for BNK (for normalization)
+    count_right=850,   # total articles for Hana
+    left_label="BNK",
+    right_label="하나",
+)
+dwc.to_file("comparison.png")
+```
+
+Keywords that appear predominantly in one source land in that source's circle. Keywords with similar frequency in both land in the center intersection.
+
+### Output
+
+```python
+dwc.to_file("output.png")   # save PNG, returns Path
+dwc.to_image()              # PIL Image (for further processing)
+dwc.show()                  # open in system viewer
+dwc                         # inline display in Jupyter Notebook
+```
+
+## Parameters
+
+### `from_regions(left, center, right, **kwargs)`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `left` | `Counter[str]` | required | Left circle keywords |
+| `center` | `Counter[str]` | required | Intersection keywords |
+| `right` | `Counter[str]` | required | Right circle keywords |
+| `left_label` | `str` | `"Left"` | Left circle label |
+| `right_label` | `str` | `"Right"` | Right circle label |
+| `word_colors` | `dict[str, str] \| None` | `None` | Per-word hex colors (highest priority) |
+| `colormap` | `str \| None` | `None` | matplotlib colormap name (e.g. `"Reds"`) |
+| `font_path` | `str \| Path \| None` | `None` | Font file path. Auto-detected if `None` |
+| `left_border_color` | `str` | `"#2980b9"` | Left circle border color |
+| `right_border_color` | `str` | `"#e74c3c"` | Right circle border color |
+| `left_word_color` | `str` | `"#2980b9"` | Left region word fallback color |
+| `right_word_color` | `str` | `"#e74c3c"` | Right region word fallback color |
+| `center_word_color` | `str` | `"#95a5a6"` | Center region word fallback color |
+| `quality_scale` | `int` | `2` | Render quality 1–3 |
+
+### `from_comparison(left, right, count_left, count_right, **kwargs)`
+
+Same as `from_regions` plus:
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `count_left` | `int` | required | Total document count for left (normalization denominator) |
+| `count_right` | `int` | required | Total document count for right |
+| `ratio_threshold` | `float` | `2.0` | Frequency ratio above which a keyword is placed exclusively in one circle |
+
+### Word color priority
+
+```
+word_colors[keyword]   →  per-word color (highest)
+colormap               →  matplotlib colormap
+*_word_color           →  region fallback color (lowest)
+```
+
+## Korean font
+
+The renderer auto-detects common Korean system fonts (AppleSDGothicNeo, NanumGothic, Malgun Gothic). To use a specific font:
+
+```python
+dwc = DualWordCloud.from_regions(
+    ...,
+    font_path="/path/to/NanumGothic.ttf",
+)
+```
+
+## Requirements
+
+- Python 3.12+
+- matplotlib, matplotlib-venn, wordcloud, shapely, Pillow, numpy

dual_wordcloud-0.1.0/README.ko.md

@@ -0,0 +1,123 @@
+# dual-wordcloud
+
+벤 다이어그램 스타일의 워드클라우드. 키워드를 세 영역(왼쪽 전용 / 공통(교집합) / 오른쪽 전용)으로 나눠 시각화합니다.
+
+## 설치
+
+```bash
+pip install dual-wordcloud
+```
+
+## 사용법
+
+### 모드 1: 영역 직접 지정 (`from_regions`)
+
+키워드를 세 그룹으로 미리 나눠놓은 경우 사용합니다. 긍정/중립/부정 감성 분류가 대표적인 예입니다.
+
+```python
+from collections import Counter
+from dual_wordcloud import DualWordCloud
+
+긍정 = Counter({"성장": 42, "혁신": 35, "안정": 28})
+중립 = Counter({"금리": 20, "실적": 18})
+부정 = Counter({"손실": 30, "위기": 25, "부채": 15})
+
+dwc = DualWordCloud.from_regions(
+    left=긍정,
+    center=중립,
+    right=부정,
+    left_label="긍정",
+    right_label="부정",
+    left_border_color="#3498db",
+    right_border_color="#e74c3c",
+)
+dwc.to_file("sentiment.png")
+```
+
+### 모드 2: 두 대상 비교 (`from_comparison`)
+
+두 Counter를 넣으면 키워드 배치(왼쪽/교집합/오른쪽)를 자동으로 계산합니다. 정규화 빈도 비율 기준으로 분류되므로 기사 수가 다른 두 대상도 공정하게 비교됩니다.
+
+```python
+from collections import Counter
+from dual_wordcloud import DualWordCloud
+
+bnk  = Counter({"대출": 120, "금리": 95, "부채": 40, "성장": 60})
+hana = Counter({"예금": 110, "금리": 88, "투자": 75, "성장": 58})
+
+dwc = DualWordCloud.from_comparison(
+    left=bnk,
+    right=hana,
+    count_left=1000,   # BNK 전체 기사 수 (정규화 분모)
+    count_right=850,   # 하나 전체 기사 수
+    left_label="BNK",
+    right_label="하나",
+)
+dwc.to_file("comparison.png")
+```
+
+한쪽에서 압도적으로 많이 나오는 키워드는 해당 원 안에, 두 대상에서 비슷한 빈도로 나오는 키워드는 교집합에 배치됩니다.
+
+### 출력
+
+```python
+dwc.to_file("output.png")   # PNG 파일 저장, Path 반환
+dwc.to_image()              # PIL Image 반환 (추가 가공 등)
+dwc.show()                  # 시스템 뷰어로 바로 확인
+dwc                         # Jupyter Notebook 셀에서 인라인 표시
+```
+
+## 파라미터
+
+### `from_regions(left, center, right, **kwargs)`
+
+| 파라미터 | 타입 | 기본값 | 설명 |
+|----------|------|--------|------|
+| `left` | `Counter[str]` | 필수 | 왼쪽 원 키워드 |
+| `center` | `Counter[str]` | 필수 | 교집합 키워드 |
+| `right` | `Counter[str]` | 필수 | 오른쪽 원 키워드 |
+| `left_label` | `str` | `"Left"` | 왼쪽 원 라벨 |
+| `right_label` | `str` | `"Right"` | 오른쪽 원 라벨 |
+| `word_colors` | `dict[str, str] \| None` | `None` | 키워드별 hex 색상 (최우선) |
+| `colormap` | `str \| None` | `None` | matplotlib colormap명 (예: `"Reds"`) |
+| `font_path` | `str \| Path \| None` | `None` | 폰트 경로. `None`이면 자동탐색 |
+| `left_border_color` | `str` | `"#2980b9"` | 왼쪽 원 테두리색 |
+| `right_border_color` | `str` | `"#e74c3c"` | 오른쪽 원 테두리색 |
+| `left_word_color` | `str` | `"#2980b9"` | 왼쪽 단어 폴백색 |
+| `right_word_color` | `str` | `"#e74c3c"` | 오른쪽 단어 폴백색 |
+| `center_word_color` | `str` | `"#95a5a6"` | 교집합 단어 폴백색 |
+| `quality_scale` | `int` | `2` | 렌더링 품질 1~3 |
+
+### `from_comparison(left, right, count_left, count_right, **kwargs)`
+
+`from_regions`의 모든 파라미터에 추가로:
+
+| 파라미터 | 타입 | 기본값 | 설명 |
+|----------|------|--------|------|
+| `count_left` | `int` | 필수 | 왼쪽 전체 문서 수 (정규화 분모) |
+| `count_right` | `int` | 필수 | 오른쪽 전체 문서 수 |
+| `ratio_threshold` | `float` | `2.0` | 이 비율 초과 시 한쪽 원에 단독 배치 |
+
+### 단어 색상 우선순위
+
+```
+word_colors[키워드]   →  키워드별 개별 색상 (최우선)
+colormap             →  matplotlib colormap 적용
+*_word_color         →  영역별 폴백 색상 (최후순위)
+```
+
+## 한글 폰트
+
+AppleSDGothicNeo, NanumGothic, Malgun Gothic 등 주요 한글 폰트를 자동으로 탐색합니다. 특정 폰트를 지정하려면:
+
+```python
+dwc = DualWordCloud.from_regions(
+    ...,
+    font_path="/path/to/NanumGothic.ttf",
+)
+```
+
+## 요구사항
+
+- Python 3.12+
+- matplotlib, matplotlib-venn, wordcloud, shapely, Pillow, numpy

dual_wordcloud-0.1.0/README.md

@@ -0,0 +1,123 @@
+# dual-wordcloud
+
+Venn diagram–style wordcloud that splits keywords across three regions: left-only, shared (center), and right-only.
+
+## Installation
+
+```bash
+pip install dual-wordcloud
+```
+
+## Usage
+
+### Mode 1: Direct regions (`from_regions`)
+
+Use when you already have keywords pre-divided into three groups — e.g. positive / neutral / negative sentiment.
+
+```python
+from collections import Counter
+from dual_wordcloud import DualWordCloud
+
+positive = Counter({"성장": 42, "혁신": 35, "안정": 28})
+neutral  = Counter({"금리": 20, "실적": 18})
+negative = Counter({"손실": 30, "위기": 25, "부채": 15})
+
+dwc = DualWordCloud.from_regions(
+    left=positive,
+    center=neutral,
+    right=negative,
+    left_label="긍정",
+    right_label="부정",
+    left_border_color="#3498db",
+    right_border_color="#e74c3c",
+)
+dwc.to_file("sentiment.png")
+```
+
+### Mode 2: Comparison (`from_comparison`)
+
+Use when you have two raw keyword counters and want to compare them. Keyword placement (left / center / right) is determined automatically by normalized frequency ratio.
+
+```python
+from collections import Counter
+from dual_wordcloud import DualWordCloud
+
+bnk   = Counter({"대출": 120, "금리": 95, "부채": 40, "성장": 60})
+hana  = Counter({"예금": 110, "금리": 88, "투자": 75, "성장": 58})
+
+dwc = DualWordCloud.from_comparison(
+    left=bnk,
+    right=hana,
+    count_left=1000,   # total articles for BNK (for normalization)
+    count_right=850,   # total articles for Hana
+    left_label="BNK",
+    right_label="하나",
+)
+dwc.to_file("comparison.png")
+```
+
+Keywords that appear predominantly in one source land in that source's circle. Keywords with similar frequency in both land in the center intersection.
+
+### Output
+
+```python
+dwc.to_file("output.png")   # save PNG, returns Path
+dwc.to_image()              # PIL Image (for further processing)
+dwc.show()                  # open in system viewer
+dwc                         # inline display in Jupyter Notebook
+```
+
+## Parameters
+
+### `from_regions(left, center, right, **kwargs)`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `left` | `Counter[str]` | required | Left circle keywords |
+| `center` | `Counter[str]` | required | Intersection keywords |
+| `right` | `Counter[str]` | required | Right circle keywords |
+| `left_label` | `str` | `"Left"` | Left circle label |
+| `right_label` | `str` | `"Right"` | Right circle label |
+| `word_colors` | `dict[str, str] \| None` | `None` | Per-word hex colors (highest priority) |
+| `colormap` | `str \| None` | `None` | matplotlib colormap name (e.g. `"Reds"`) |
+| `font_path` | `str \| Path \| None` | `None` | Font file path. Auto-detected if `None` |
+| `left_border_color` | `str` | `"#2980b9"` | Left circle border color |
+| `right_border_color` | `str` | `"#e74c3c"` | Right circle border color |
+| `left_word_color` | `str` | `"#2980b9"` | Left region word fallback color |
+| `right_word_color` | `str` | `"#e74c3c"` | Right region word fallback color |
+| `center_word_color` | `str` | `"#95a5a6"` | Center region word fallback color |
+| `quality_scale` | `int` | `2` | Render quality 1–3 |
+
+### `from_comparison(left, right, count_left, count_right, **kwargs)`
+
+Same as `from_regions` plus:
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `count_left` | `int` | required | Total document count for left (normalization denominator) |
+| `count_right` | `int` | required | Total document count for right |
+| `ratio_threshold` | `float` | `2.0` | Frequency ratio above which a keyword is placed exclusively in one circle |
+
+### Word color priority
+
+```
+word_colors[keyword]   →  per-word color (highest)
+colormap               →  matplotlib colormap
+*_word_color           →  region fallback color (lowest)
+```
+
+## Korean font
+
+The renderer auto-detects common Korean system fonts (AppleSDGothicNeo, NanumGothic, Malgun Gothic). To use a specific font:
+
+```python
+dwc = DualWordCloud.from_regions(
+    ...,
+    font_path="/path/to/NanumGothic.ttf",
+)
+```
+
+## Requirements
+
+- Python 3.12+
+- matplotlib, matplotlib-venn, wordcloud, shapely, Pillow, numpy

dual_wordcloud-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "dual-wordcloud"
+version = "0.1.0"
+requires-python = ">=3.12"
+readme = "README.md"
+license = { text = "MIT" }
+dependencies = [
+    "wordcloud>=1.9.0",
+    "matplotlib>=3.8.0",
+    "matplotlib-venn>=0.11.0",
+    "shapely>=2.0.0",
+    "pillow>=10.0.0",
+    "numpy>=1.24.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dual_wordcloud"]

dual_wordcloud-0.1.0/src/dual_wordcloud/__init__.py

@@ -0,0 +1,3 @@
+from dual_wordcloud.core import DualWordCloud
+
+__all__ = ["DualWordCloud"]

dual_wordcloud-0.1.0/src/dual_wordcloud/_renderer.py

@@ -0,0 +1,171 @@
+"""듀얼 워드클라우드 렌더링 모듈."""
+import io
+from collections import Counter
+from pathlib import Path
+
+import matplotlib
+matplotlib.use("Agg")
+
+import matplotlib.pyplot as plt
+import matplotlib.font_manager as fm
+import numpy as np
+import shapely.geometry as geom
+from matplotlib_venn import venn2
+from PIL import Image, ImageDraw
+from wordcloud import WordCloud
+
+
+def _resolve_font_path() -> Path | None:
+    """시스템에서 사용 가능한 폰트를 자동으로 찾는다."""
+    candidates = [
+        Path("/System/Library/Fonts/AppleSDGothicNeo.ttc"),
+        Path("/Library/Fonts/NanumGothic.ttf"),
+        Path("/usr/share/fonts/truetype/nanum/NanumGothic.ttf"),
+        Path("C:/Windows/Fonts/malgun.ttf"),
+    ]
+    for p in candidates:
+        if p.exists():
+            return p
+    return None
+
+
+def _make_color_func(color_lookup: dict[str, str], fallback: str) -> callable:
+    """키워드별 색상 매핑 함수. 매핑에 없는 단어는 fallback 색상을 사용한다."""
+    def color_func(word: str, **kwargs) -> str:
+        return color_lookup.get(word, fallback)
+    return color_func
+
+
+def _make_region_color_func(color: str) -> callable:
+    """영역 전체를 단일 색상으로 칠하는 함수를 반환한다."""
+    return lambda word, **kwargs: color
+
+
+def render(
+    left: Counter,
+    center: Counter,
+    right: Counter,
+    left_label: str,
+    right_label: str,
+    word_colors: dict[str, str] | None,
+    colormap: str | None,
+    left_border_color: str,
+    right_border_color: str,
+    left_word_color: str,
+    right_word_color: str,
+    center_word_color: str,
+    font_path: Path | None,
+    quality_scale: int,
+) -> Image.Image:
+    """세 Counter를 받아 듀얼 워드클라우드 PIL Image를 반환한다."""
+    if font_path is None:
+        font_path = _resolve_font_path()
+
+    scale = max(1, min(int(quality_scale), 3))
+    border_colors = [left_border_color, right_border_color]
+    word_colors_by_region = [left_word_color, right_word_color, center_word_color]
+
+    if not any([left, center, right]):
+        raise ValueError("left, center, right 중 하나 이상은 비어있지 않아야 합니다")
+
+    global_max = max(
+        max(left.values(), default=0),
+        max(center.values(), default=0),
+        max(right.values(), default=0),
+    ) or 1
+    left = Counter({k: v / global_max for k, v in left.items()})
+    center = Counter({k: v / global_max for k, v in center.items()})
+    right = Counter({k: v / global_max for k, v in right.items()})
+
+    fig_width, fig_height, dpi = 25, 15, 300
+
+    rc_params = {"axes.unicode_minus": False}
+    if font_path:
+        font_prop = fm.FontProperties(fname=str(font_path))
+        rc_params["font.family"] = font_prop.get_name()
+
+    with matplotlib.rc_context(rc_params):
+        fig, ax = plt.subplots(figsize=(fig_width, fig_height), dpi=dpi)
+        venn = venn2(subsets=(10, 10, 5), set_labels=(left_label, right_label), ax=ax)
+
+        subset_data = {
+            frozenset({0}): left,
+            frozenset({1}): right,
+            frozenset({0, 1}): center,
+        }
+        subset_keys = [frozenset({0}), frozenset({1}), frozenset({0, 1})]
+
+        for idx, patch in enumerate(venn.patches):
+            if patch is None:
+                continue
+            patch.set_facecolor("none")
+            if idx < len(border_colors):
+                patch.set_edgecolor(border_colors[idx])
+                patch.set_linewidth(2)
+            else:
+                patch.set_linewidth(0)
+
+        for label in venn.subset_labels:
+            if label:
+                label.set_visible(False)
+
+        for idx, patch in enumerate(venn.patches):
+            if idx >= len(subset_keys):
+                continue
+            counter = subset_data.get(subset_keys[idx], Counter())
+            if not counter:
+                continue
+
+            path = patch.get_path()
+            if path is None:
+                continue
+            vertices = path.vertices
+            if len(vertices) < 3:
+                continue
+
+            polygon = geom.Polygon(vertices)
+            min_x, min_y, max_x, max_y = polygon.bounds
+            width = max(100, min(800, int((max_x - min_x) * dpi * scale)))
+            height = max(100, min(600, int((max_y - min_y) * dpi * scale)))
+
+            img_mask = Image.new("L", (width, height), 255)
+            draw = ImageDraw.Draw(img_mask)
+            x_range = max_x - min_x if max_x > min_x else 1
+            y_range = max_y - min_y if max_y > min_y else 1
+            px_vertices = [
+                (int((x - min_x) / x_range * (width - 1)),
+                 int((max_y - y) / y_range * (height - 1)))
+                for x, y in vertices
+            ]
+            draw.polygon(px_vertices, fill=0)
+            mask = np.array(img_mask)
+
+            region_word_color = word_colors_by_region[idx] if idx < len(word_colors_by_region) else "#95a5a6"
+            wc_kwargs: dict = {}
+            if word_colors:
+                region_lookup = {k: v for k, v in word_colors.items() if k in counter}
+                wc_kwargs["color_func"] = _make_color_func(region_lookup, fallback=region_word_color)
+            elif colormap:
+                wc_kwargs["colormap"] = colormap
+            else:
+                wc_kwargs["color_func"] = _make_region_color_func(region_word_color)
+
+            wc = WordCloud(
+                font_path=str(font_path) if font_path else None,
+                width=width, height=height, mask=mask,
+                mode="RGBA", background_color=None,
+                prefer_horizontal=0.7, min_font_size=8,
+                max_font_size=int(48 * scale),
+                **wc_kwargs,
+            )
+            wc.generate_from_frequencies(counter)
+            ax.imshow(np.array(wc), extent=[min_x, max_x, min_y, max_y],
+                      aspect="auto", alpha=0.9, zorder=10)
+
+        buf = io.BytesIO()
+        fig.savefig(buf, format="png", dpi=dpi, bbox_inches="tight",
+                    pad_inches=0.1, transparent=False, facecolor="white")
+        plt.close(fig)
+
+    buf.seek(0)
+    return Image.open(buf).copy()

dual_wordcloud-0.1.0/src/dual_wordcloud/_splitter.py

@@ -0,0 +1,39 @@
+from collections import Counter
+
+
+def split_for_comparison(
+    a: Counter,
+    b: Counter,
+    count_a: int,
+    count_b: int,
+    ratio_threshold: float = 2.0,
+) -> tuple[Counter, Counter, Counter]:
+    """두 Counter를 정규화 빈도 기반으로 left/center/right로 분리한다.
+
+    각 키워드를 기사 수로 정규화한 뒤 비율 임계값으로 배치를 결정한다:
+      - 한쪽에만 있는 단어: 해당 side (정규화 빈도)
+      - norm_a / norm_b > ratio_threshold: left (norm_a)
+      - norm_b / norm_a > ratio_threshold: right (norm_b)
+      - 그 외 (비슷한 빈도): center ((norm_a + norm_b) / 2)
+    """
+    all_keys = set(a.keys()) | set(b.keys())
+    left: Counter = Counter()
+    center: Counter = Counter()
+    right: Counter = Counter()
+
+    for k in all_keys:
+        norm_a = a.get(k, 0) / count_a
+        norm_b = b.get(k, 0) / count_b
+
+        if norm_b == 0:
+            left[k] = norm_a
+        elif norm_a == 0:
+            right[k] = norm_b
+        elif norm_a / norm_b > ratio_threshold:
+            left[k] = norm_a
+        elif norm_b / norm_a > ratio_threshold:
+            right[k] = norm_b
+        else:
+            center[k] = (norm_a + norm_b) / 2
+
+    return left, center, right