# ptoe (Plotly-like To ECharts)

**ptoe**는 이미 `matplotlib`으로 그린 차트를  
👉 **ECharts 기반의 인터랙티브 HTML 결과물**로 변환해주는 실험적 라이브러리입니다.

 핵심 철학  
> **“matplotlib 문법은 그대로, 출력만 ECharts로”**

## 지원 차트 유형 (v0.3.0)

### Bar Chart
- 단일 bar
- 다중 series bar
- stacked bar (`bottom=`)

```python
plt.bar(x, y1)
plt.bar(x, y2, bottom=y1)
ptoe.show()
```


*legend, 색상, stack 자동 인식
*category x-axis 지원

### Line Chart

- 일반 line
- step line (plt.step, steps-pre/mid/post)

```python
plt.plot(x, y)
plt.step(x, y, where="post")
ptoe.show()
```

*numeric / category x 자동 판별
*step → ECharts step 옵션으로 변환

### Scatter Plot

```python
plt.scatter(x, y)
ptoe.show()
```

*matplotlib scatter → ECharts scatter
*색상, label 지원

### Area Chart

```python
plt.fill_between

plt.fill_between(x, y)
ptoe.show()
```

*PolyCollection 기반 감지
*ECharts line + areaStyle로 변환

### Histogram (제한적 지원)

```python
plt.hist(data, bins=10)
ptoe.show()
```

*matplotlib hist를 bar 기반 히스토그램으로 변환
*bin 중심값 + height 추출

⚠️ 경고

density=True
cumulative=True

위 옵션 사용 시 통계적 동일성 보장 안 됨

[ptoe] Histogram detected.
If density=True or cumulative=True was used,
statistical equivalence with matplotlib is NOT guaranteed.
ptoe converts rendered bars only.

### Boxplot (최소 지원)

```python
plt.boxplot(data)
ptoe.show()
```

*matplotlib이 이미 계산한 결과를 시각적 형태로만 변환
*quartile / whisker 재계산 ❌

⚠️ 경고

[ptoe] Boxplot detected.
matplotlib boxplot is a statistical chart.
ptoe converts rendered shapes only.
Statistical equivalence is NOT guaranteed.

### Heatmap (imshow 기반)

```python
plt.imshow(data)
ptoe.show()
```

*imshow → ECharts heatmap
*pixel 값 기반 변환
*visualMap 자동 생성

⚠️ 경고

[ptoe] Heatmap detected.
ptoe converts rendered pixel values only.
Color scaling / normalization may differ.

*지원하지 않는 기능 (의도적 제한)

- matplotlib 통계 로직 재현
- hist: density / cumulative
- boxplot: quartile 계산
- 원본 데이터 재수집
- pandas / seaborn 직접 연동
- ptoe는 “이미 그려진 결과”만 변환합니다.

### 실행 방식

Jupyter / Colab
ptoe.show(inline=True)

로컬 (HTML)
ptoe.show()

설계 요약

matplotlib 객체 분석

ax.lines

ax.collections

ax.containers

AxesImage (heatmap)

chart type 자동 감지

ECharts option 생성

통계 차트는 경고로 명확히 한계 표시

버전 히스토리
v0.3.0

hist / boxplot / heatmap 추가

차트별 warning 시스템 도입

detect_chart_type 안정화

한 줄 요약

ptoe는 matplotlib 사용자를 위한
“문법 유지 + 결과물 업그레이드” 도구입니다.
