ThaiEDA

AutoEDA และเครื่องมือทำความสะอาดข้อมูลอัจฉริยะสำหรับข้อมูลภาษาไทยและข้อมูลผสมภาษา

One-line Exploratory Data Analysis and Smart Data Cleaning for Thai and Mixed-Language Datasets.

ThaiEDA ออกแบบมาเพื่อตอบคำถามเดียว: "ชุดข้อมูลนี้มีความน่าเชื่อถือเพียงใด และควรเริ่มต้นสำรวจจุดไหนก่อน?"

เครื่องมือวิเคราะห์ข้อมูล (profiling) ทั่วไปมักจะตรวจนับค่าว่าง (missing values) และวาดกราฟมาตรฐานได้ดี แต่มักจะมองข้ามปัญหาเฉพาะตัวของข้อมูลภาษาไทย เช่น ปี พ.ศ., เลขไทย, อักขระเว้นวรรคที่มองไม่เห็น (zero-width space), ปัญหาการแสดงผลตัวอักษรผิดเพี้ยน (mojibake), รูปแบบเบอร์โทรศัพท์/บัตรประชาชน หรือแม้กระทั่งฟอนต์ในกราฟที่อ่านไม่ออก ซึ่ง ThaiEDA สามารถจัดการกับปัญหาเหล่านี้ให้โดยอัตโนมัติในกระบวนการทำงานปกติ (pipeline) ทำให้คุณไม่ต้องเสียเวลาเตรียมข้อมูล (preprocess) เองทีละคอลัมน์

ThaiEDA answers one simple question: "Can I trust this dataset, and what should I explore first?" It treats Thai-specific data issues — Buddhist Era dates, Thai numerals, zero-width spaces, encoding errors, local phone formats, and chart fonts — as normal problems to fix automatically.

• Repository: github.com/peetwan/thaieda
• PyPI: pypi.org/project/thaieda
• License: Apache-2.0
• Current version: v2.3.0

คุณสมบัติหลัก / Key Features

ติดตั้ง / Installation

ต้องการ Python 3.10+

pip install thaieda

ตั้งแต่เวอร์ชัน v2.2.0 เป็นต้นไป แพ็กเกจและ dependencies ทั้งหมดจะถูกติดตั้งพร้อมใช้งานโดยอัตโนมัติ:

แพ็กเกจสำหรับการพัฒนา / Development Dependencies

สำหรับการทดสอบและพัฒนาโครงการ สามารถติดตั้งเพิ่มเติมได้ด้วย:

pip install "thaieda[dev]"

เริ่มต้นเร็ว / Quickstart

One-liner CLI

เมื่อติดตั้งเรียบร้อยแล้ว สามารถเริ่มรันวิเคราะห์ได้ทันทีด้วยคำสั่งเดียว ซึ่งจะทำการอ่านข้อมูล → ทำความสะอาด → และสร้างรายงานผลลัพธ์แบบ HTML blueprint ให้โดยอัตโนมัติ:

pip install thaieda
thaieda mydata.csv
# → สร้าง mydata-report.html ในโฟลเดอร์เดียวกับไฟล์

พารามิเตอร์และตัวเลือกที่ใช้งานบ่อย:

thaieda data.csv -o report.html          # ระบุพาธ output
thaieda data.csv --target clicked        # คอลัมน์เป้าหมาย (หรือเดาอัตโนมัติจากชื่อ)
thaieda data.csv -t clicked              # ย่อ — เหมือน --target
thaieda data.csv --columns               # ดูคอลัมน์ + target ที่น่าจะเป็น (ไม่รัน EDA)
thaieda data.csv -y                      # ข้าม prompt เลือก target (CI/batch)
thaieda data.csv --explore               # รายงาน EDA แบบเต็ม (แทน blueprint)
thaieda data.csv --lang en --no-clean    # ภาษาอังกฤษ, ไม่ทำความสะอาด

Target column: หากไม่กำหนดตัวเลือก -t หรือ --target ระบบ ThaiEDA จะวิเคราะห์และคาดเดาจากชื่อคอลัมน์โดยอัตโนมัติ (เช่น target, label, clicked, churn, survived, y, class, outcome, income, quality, response, default, fraud, exit และชื่ออื่น ๆ ที่มีคำเหล่านี้ประกอบอยู่) ในกรณีที่รันผ่านหน้าจอ Terminal (TTY) ระบบจะแสดงรายการคอลัมน์เพื่อให้คุณเลือก (สามารถกด Enter เพื่อข้าม) และหากต้องการรันแบบอัตโนมัติโดยไม่แสดงคำถาม ให้ใช้ตัวเลือก -y หรือ --no-interactive

เลือก target อย่างไร?

1. ดูคอลัมน์ก่อน — เพื่อตรวจสอบเบื้องต้นโดยไม่ต้องวิเคราะห์ข้อมูลเต็มรูปแบบ:

   thaieda data.csv --columns
   # หรือ
   thaieda data.csv --preview
   

   แสดงตารางข้อมูลประกอบด้วย ลำดับที่ (#), ชื่อคอลัมน์, ชนิดข้อมูล (dtype), จำนวนค่าที่ไม่ซ้ำ (unique values) และเครื่องหมายดาว (★) หน้าคอลัมน์ที่ระบบคาดเดาว่าเป็นตัวแปรเป้าหมาย (target)

2. กำหนดด้วยตนเอง — ระบุพารามิเตอร์โดยตรง เช่น thaieda data.csv -t clicked หรือ --target churn

3. ไม่กำหนดตัวเลือก — ระบบจะตรวจหาโดยอัตโนมัติจากชื่อคอลัมน์ หรือสอบถามในหน้าจอ Terminal (หากรองรับระบบตอบรับโต้ตอบ)

4. หลังเสร็จสิ้นกระบวนการ — หน้าจอ CLI จะแสดงผล Target: clicked (auto) / (จาก --target) / (ไม่ระบุ — ไม่มีแผนสร้างโมเดล)

การประมวลผลแบบกลุ่ม (Batch) ในโฟลเดอร์: ทำการประมวลผลข้อมูลทุกไฟล์ที่พบในโฟลเดอร์ และบันทึกรายงานแยกเป็นรายไฟล์ในรูปแบบ {stem}-report.html (ซึ่งแตกต่างจากการสั่งงานด้วย thaieda dataset ที่จะเป็นการเชื่อมโยงโครงสร้างข้อมูล (schema) ของหลาย ๆ ตารางเข้าด้วยกัน)

cd ~/my-data/
thaieda .                                # batch ทุก CSV/TSV/JSON/Excel/Parquet
thaieda /path/to/folder --output-dir reports/
thaieda folder/ -t clicked -y            # target เดียวกันทุกไฟล์, ไม่ถาม interactive

รองรับไฟล์ข้อมูลหลากหลายรูปแบบ เช่น CSV, TSV, JSON, Excel, Parquet โดยระบบจะตรวจสอบรูปแบบไฟล์ (format) และการเข้ารหัสอักขระ (encoding) ให้โดยอัตโนมัติ

Python API

import pandas as pd
import thaieda

# ข้อมูลจำลองที่มีปัญหาพบบ่อยในข้อมูลไทย
data = {
    "name": ["สมชาย\u200bรักไทย", "สมหญิง   ใจดี", "นายดำ ๐๑"],
    "birth_year": [2530, 2532, 2528],           # ปี พ.ศ.
    "sales": ["฿1,200", "฿3,500", "฿10,000"],
    "phone": ["081-234-5678", "+66898765432", "๐๒-๓๔๕-๖๗๘๙"],
}
df = pd.DataFrame(data)

# EDA ครบวงจร (ค่าเริ่มต้น lang="th" → รายงานภาษาไทย)
result = thaieda.run(df, clean=True, lang="th")
result.to_html("quickstart-report.html")

print(result.cleaned_df)
print(result.quality_score)   # คะแนนคุณภาพ 0–100

One-liner API: run() / EDA()

ฟังก์ชัน thaieda.run(df) และ thaieda.EDA(df) ทำงานในลักษณะเดียวกัน โดยจะส่งคืนผลลัพธ์เป็นออบเจกต์ EDAResult

result = thaieda.run(
    df,
    clean=True,                  # ทำความสะอาดก่อนวิเคราะห์ (default: True)
    handle_missing="flag",         # flag | median | mode | drop | unknown | ml
    remove_duplicates=True,
    downcast=True,
    lang="th",                     # "th" | "en" — ภาษารายงาน
    report_mode="explore",         # "explore" | "blueprint"
    target_column=None,            # คอลัมน์เป้าหมาย (สำหรับ ML / blueprint)
    make_charts=True,
    timeseries=True,
    insights_engine=True,
    insights_top=8,
    narrative=True,                # บทสรุป offline ไม่ต้องใช้ LLM
    llm=False,                     # เปิด LLM analysis
    privacy="insight_only",        # insight_only | synthetic | anonymized | dp_noise | full
    provider="openai",             # openai | anthropic | ollama
)

EDAResult — ผลลัพธ์หลัก

หากรันบน Jupyter Notebook: เพียงแค่พิมพ์ตัวแปร result ระบบจะแสดงผลรายงาน HTML ให้โดยอัตโนมัติผ่านเมธอด _repr_html_

Blueprint mode — รายงานสำหรับงาน ML

การกำหนด report_mode="blueprint" จะเป็นการสร้างรายงานขนาดกระชับที่เน้นคำแนะนำการดำเนินการในขั้นตอนถัดไป เหมาะสำหรับเตรียมชุดข้อมูลตารางเพื่อสร้างโมเดล Machine Learning ที่มีตัวแปรเป้าหมาย (เช่น การจำแนกประเภท (classification), อัตราการคลิก (CTR) หรือการยกเลิกบริการ (churn))

result = thaieda.run(
    df,
    report_mode="blueprint",
    target_column="clicked",   # หรือ churn, income, quality, …
    lang="th",
    clean=True,
)
result.to_html("modeling-blueprint.html")

สิ่งที่ระบบวิเคราะห์ในโหมด Blueprint:

• วิเคราะห์จัดกลุ่มข้อมูลอัตโนมัติ — ตรวจสอบและจำแนกประเภทโมเดล (ml_tabular) เมื่อพบตัวแปรเป้าหมายและคอลัมน์คุณลักษณะ (feature columns) หลายคอลัมน์
• ข้ามการวิเคราะห์อนุกรมเวลา — ข้ามกระบวนการวิเคราะห์อนุกรมเวลา (timeseries) ในข้อมูลประเภทเหตุการณ์ เช่น ข้อมูลการบันทึก (event log/impression) ที่แต่ละแถวไม่ใช่ลำดับเวลาต่อเนื่อง
• ลดจำนวนแผนภูมิลง — ตัดการแสดงผลแผนภูมิที่มีความซับซ้อนและขนาดใหญ่ เช่น scatter matrix และ violin chart ออกไป
• ค้นหาข้อมูลเชิงลึกได้กว้างขึ้น — เพิ่มการแสดงผลข้อมูลเชิงลึก (insights) ได้สูงสุดถึง 12 รายการ
• วางโครงร่างพิมพ์เขียวสำหรับทำโมเดล (Modeling Blueprint) (เมื่อมีการกำหนดตัวแปรเป้าหมาย target_column):
  • ค่าสถิติเริ่มต้นของตัวแปรเป้าหมาย (Target baseline) — ตรวจสอบสัดส่วนของคลาส (class balance) และอัตราส่วนค่าที่เป็นบวก (positive rate)
  • การตรวจจับข้อมูลรั่วไหล (Leakage detection) — ค้นหาปัญหาข้อมูลรั่วไหลแบ่งตามความรุนแรง ได้แก่ Tier A (ระดับวิกฤต) และ Tier B (ระดับแจ้งเตือน)
  • คุณลักษณะที่มีความสัมพันธ์สูง (Strong features) — ระบุคอลัมน์ที่มีผลต่อตัวแปรเป้าหมายอย่างมีนัยสำคัญทางสถิติ
  • คอลัมน์ที่ควรคัดออก (Columns to drop) — แนะนำคอลัมน์ประเภทตัวบ่งชี้เฉพาะ (ID) หรือคอลัมน์ที่ไม่มีประโยชน์ต่อการสร้างแบบจำลอง
  • ขั้นตอนการดำเนินงานถัดไป (Next steps) — รายการตรวจสอบ (checklist) สิ่งที่ควรทำก่อนเริ่มฝึกสอนโมเดล (training model)

Target leakage tiers

สูตรใช้งาน / Core Recipes

1. ทำความสะอาดแยก (clean)

cleaned_df, report = thaieda.clean(
    df,
    handle_missing="ml",       # หรือ flag, median, mode, drop, unknown
    remove_duplicates=True,
    fix_dates=True,
    fix_numerals=True,
    fix_encoding=True,
    downcast=True,
)
report.to_json("cleaning-audit.json")

ตัวเลือก skip_id_like=True (ค่าเริ่มต้น) จะช่วยป้องกันไม่ให้ข้อมูลรหัสสินค้า (product ID) หรือหมายเลขซีเรียล (serial number) สูญเสียรูปแบบเดิมจากการทำความสะอาดอักขระที่ซ้ำซ้อนกัน

2. เปรียบเทียบชุดข้อมูล (compare)

from thaieda import compare

diff = compare(train_df, prod_df, labels=("train", "prod"))
print(diff["schema_diff"])
print(diff["distribution_drift"])
print(diff["categorical_drift"])

3. Schema หลายไฟล์

from thaieda import DatasetReport, profile_dataset

dataset = profile_dataset("data/warehouse", validate_values=True)
DatasetReport(dataset, lang="th").to_html("schema-report.html")
print(dataset.to_mermaid())

4. วิเคราะห์ทั้งโฟลเดอร์ (run_folder)

folder = thaieda.run_folder(
    "data/",
    recursive=True,
    lang="th",
    report_mode="blueprint",
    target_column="label",
)
folder.to_master_html("reports/index.html")
print(folder.summary())

รองรับไฟล์ข้อมูลหลากหลายนามสกุล ได้แก่ .csv, .tsv, .json, .jsonl, .xlsx, .xls และ .parquet

5. LLM analysis (optional)

result = thaieda.run(
    df,
    llm=True,
    privacy="insight_only",   # ปลอดภัยที่สุด — ไม่ส่ง raw rows
    provider="openai",
    lang="th",
)
print(result.llm_response)

นอกจากนี้ยังสามารถเรียกใช้ฟังก์ชันนี้แยกเฉพาะได้ผ่าน: thaieda.llm.analyze_with_llm(...)

Command Line Interface (CLI)

thaieda --version

# One-liner (ค่าเริ่มต้น — blueprint report)
thaieda data.csv
thaieda data.csv -o report.html --target clicked

# Batch โฟลเดอร์ — รายงานต่อไฟล์ (ไม่ใช่ schema discovery)
thaieda .
thaieda data/ --output-dir reports/ -y

# EDA + clean + HTML report (subcommand แบบเดิม)
thaieda run data.csv -o report.html --lang th --target clicked

# Profile แบบละเอียด
thaieda profile data.xlsx -o profile.html --clean --lang en

# Clean อย่างเดียว
thaieda clean inputs.csv -o cleaned.csv

# Schema หลายตาราง
thaieda dataset data/warehouse/ -o schema-report.html --lang th

Blueprint mode: โหมดเริ่มต้นของการทำงานผ่าน CLI และ Python API (report_mode="blueprint") หากต้องการสร้างรายงานวิเคราะห์ข้อมูล (EDA) แบบจัดเต็มและครบถ้วน ให้ใช้ตัวเลือก --explore หรือตั้งค่า report_mode="explore"

โครงสร้างโมดูล / Module Overview

src/thaieda/
├── __init__.py          run(), EDA(), EDAResult, run_folder(), compare()
├── cli.py               Command-line interface
├── detect/              Column type detection + Thai month names
├── clean/               Smart cleaning pipeline + ML imputation
├── quality/             Thai data quality checks + scoring
├── anomaly/             Numeric, text, and Thai-specific anomalies
├── insight/             Auto insight summary + distributions
├── insight_engine/      Cross-column patterns + leakage detection
├── report/              HTML reports, blueprint mode, DatasetReport
├── narrative/           Offline executive narrative (no LLM)
├── viz/                 Charts + Thai font support
├── io/                  Auto format/encoding detection, downcast
├── tokenize/            Thai tokenizer adapters (pythainlp/nlpo3/attacut)
├── text/                Text metrics
├── analysis/            Target variable analysis
├── timeseries/          Timeseries decomposition
├── schema/              Multi-file PK/FK discovery
├── ner/                 Thai Named Entity Recognition
├── llm/                 Privacy-preserving LLM analysis
├── i18n/                TH/EN labels
└── compare.py           Dataset drift & schema comparison

เปรียบเทียบกับเครื่องมือทั่วไป

คำถามที่พบบ่อย / FAQ

เมื่อพบปัญหาแผนภูมิแสดงผลเป็นรูปสี่เหลี่ยมแทนตัวอักษรภาษาไทย? สามารถแก้ไขได้โดยตรวจสอบว่าระบบปฏิบัติการของคุณติดตั้งฟอนต์ภาษาไทยเรียบร้อยแล้ว โดยตัวระบบ ThaiEDA จะกำหนดฟอนต์สำรอง (Fallback font) เพื่อแสดงผลภาษาไทยให้อัตโนมัติ

ข้อมูลในชุดข้อมูลจะถูกอัปโหลดหรือส่งออกไปภายนอกเครื่องคอมพิวเตอร์หรือไม่? ไม่เลย — การทำงานทุกขั้นตอนประมวลผลภายในเครื่องคอมพิวเตอร์ของคุณเอง (Local) ยกเว้นในกรณีที่คุณสั่งเปิดการใช้งานโมเดลภาษาขนาดใหญ่โดยตั้งค่าพารามิเตอร์ llm=True โดยตรงเท่านั้น และสามารถเลือกใช้โหมด privacy="insight_only" หรือเชื่อมต่อกับ Ollama ที่รันแบบ Local เพื่อรักษาความปลอดภัยและความเป็นส่วนตัวของข้อมูลขั้นสูงสุดได้

โหมดวิเคราะห์ข้อมูลแบบ Blueprint แตกต่างกับ Explore อย่างไร? โหมด explore จะแสดงผลรายงานวิเคราะห์ข้อมูล (EDA) แบบเต็มพิกัดพร้อมแผนภูมิทุกประเภท ในขณะที่โหมด blueprint จะสรุปเนื้อหาให้สั้นกระชับพร้อมรายการตรวจสอบสำหรับการเตรียมข้อมูล และตรวจสอบการรั่วไหลของข้อมูล (Leakage detection) ซึ่งเหมาะเป็นขั้นตอนก่อนการนำไปสอนโมเดล Machine Learning

การทดสอบ / Testing

python -m pytest tests/ -q

ชุดทดสอบภายในระบบมีมากกว่า 1,000 เคสทดสอบ (tests) ครอบคลุมทั้งขั้นตอนการทำความสะอาดข้อมูล (Cleaning Pipeline), รูปแบบการค้นพบข้อค้นพบเชิงลึก (Insight Patterns), โหมดวิเคราะห์พิมพ์เขียว (Blueprint Mode), การตรวจจับข้อมูลรั่วไหล (Leakage Detection), การกันผลบวกลวง (false-positive regression tests) ตลอดจนการทดสอบกับชุดข้อมูลจริงที่มีจุดผิดพลาดในโครงสร้างใน tests/fixtures/dirty_datasets/

พัฒนา / Development

python -m pytest tests/
ruff check src/ tests/
ruff format src/ tests/

ศึกษาข้อมูลเพิ่มเติมได้จากแนวทางของโครงการที่ CONTRIBUTING.md และข้อตกลงการมีส่วนร่วม CODE_OF_CONDUCT.md

License

ThaiEDA is released under the Apache-2.0 License.