nshiab/simple-data-analysis

설명: Deno, Node.js, Bun에서 실행되는 탭형, 지리공간, AI 지원 데이터 분석을 위한 TypeScript 라이브러리입니다. Pandas/Tidyverse에서 영감을 받은 체이닝 가능한 API 뒤에서 DuckDB(프로세스 내 분석 데이터베이스)를 래핑하고, 행 단위 LLM 처리, 임베딩, RAG와 같은 선택적 AI 기능을 추가합니다. CBC 뉴스의 컴퓨터 저널리스트가 Python, R, JS를 전환하는 대신 데이터 분석과 시각화를 전적으로 JavaScript로 수행하고자 만들어졌습니다.

중요성: JavaScript는 진지한 데이터 작업(pandas, tidyverse, GeoPandas)에서 역사적으로 Python과 R에 뒤쳐져 있습니다. SDA는 다음과 같은 방법으로 그 격차를 해소합니다.

• DuckDB를 통한 성능 – README의 벤치마크(2,200만 개 온도 기록, 335,000개 지리공간 포인트)는 SDA가 원시 DuckDB 속도에 가깝게 실행되면서 pandas/tidyverse/GeoPandas를 능가하고 메모리 사용량이 더 낮음을 보여줍니다.
• 파이프라인 전체를 하나의 언어로 – 분석, 지리공간 조인, 차트, 지도, AI 강화가 모두 생태계를 전환하지 않고 TypeScript에서 이루어집니다.
• 지연 로딩 및 쿼리 융합 – 핵심 변환은 대기열에 들어가 단일 SQL 문으로 융합되어 왕복 시간을 줄입니다. AI/Google/차트 종속성은 해당 특정 메서드가 호출될 때만 로드되므로 핵심만 사용하는 사용자는 시작 비용을 지불하지 않습니다.
• 내장 AI 기능(확장 패키지): aiRowByRow()는 열 값을 LLM에 보내고 구조화된 응답을 저장합니다(예: 도시 이름에서 국가 및 대륙 추출). aiEmbeddings()는 텍스트를 벡터로 변환하고, 클러스터링(HDBSCAN), 하이브리드 검색, RAG 스타일 질문 응답, 자연어 쿼리를 지원합니다. Google Gemini, Vertex AI 또는 로컬 Ollama 모델은 .env에서 구성할 수 있습니다.
• 공개 데이터 소스 – Statistics Canada 테이블과 OpenStreetMap(로컬 파일 또는 Overpass 쿼리)용 직접 로더, 재현성을 위한 로컬 캐싱 제공.

내부 작동 방식: SDA는 duckdb-node-neo를 통해 DuckDB에서 SQL을 실행하고 DuckDB 확장(지리공간 작업용 spatial, 퍼지 매칭, 전체 텍스트 검색, 벡터 인덱스)을 지연 로드합니다. API는 변환을 위해 동기식 및 체이닝이 가능합니다. 최종 관찰자 메서드(예: .log(), .writeData() 또는 결과 얻기)만 await하면 됩니다.

예제(README에서): 캐나다 기상 관측소 CSV를 로드하고, 열 이름을 바꾸고, 누락 값을 제거하고, 관측소별 평균 온도를 계산하고, 정렬하고, 출력하고, 내보냅니다:

const sdb = new SimpleDB();

const data = await sdb
  .newTable("temperatures")
  .loadData(".../dailyTemperatures.csv")
  .renameColumns({ t: "temperature", id: "station" })
  .removeMissing({ columns: "temperature" })
  .summarize({
    columns: "temperature", by: "station", stats: "mean", decimals: 2,
  })
  .sort({ mean: "desc" })
  .log();

await data.writeData("output/averageTemperatures.csv");
await sdb.close();

대상 사용자: JavaScript/TypeScript를 선호하고 대규모 데이터 세트를 처리하고, 지리공간 조인을 수행하고, 차트/지도를 만들거나, 두 번째 데이터 언어를 배우지 않고 LLM으로 데이터를 강화해야 하는 데이터 저널리스트, 분석가, 개발자.

README의 주의 사항: 이는 실제적이고 실질적인 라이브러리이지만 모든 Python 사용 사례를 대체하는 완전한 데이터프레임은 아닙니다. AI 기능에는 API 키(Gemini/Vertex/Ollama)가 필요하며 README는 JSR 문서가 현재 상속된 메서드를 생략한다고(알려진 상위 제한 사항) 언급합니다. 설치 방법은 Node/Bun/Deno용 JSR 또는 npm을 통한 방법이며, 새 프로젝트를 시작하는 데 도움이 되는 보조 스캐폴딩 도구(setup-data-project)가 있습니다.