← 홈으로

netviz_tools

원시 엣지 테이블을 세 단계 만에 인터랙티브 네트워크 차트로 만드는 Python 패키지입니다. 데이터를 정제하면서 바뀐 내용은 모두 보고서로 남기고 NetworkX 그래프를 만든 뒤 Plotly로 그립니다. 세 단계 모두 같은 인자 이름을 씁니다. 1.0은 2025년에 공개한 0.x 버전을 처음부터 다시 만든 것으로, 지저분한 입력 데이터의 예로 FAOSTAT 농산물 무역 데이터를 사용합니다.

한눈에 보기

문제 / 배경

네트워크 데이터가 NetworkX에 바로 넣을 수 있는 형태로 들어오는 경우는 드뭅니다. 출처마다 컬럼 이름이 다르고 같은 나라도 여러 가지 표기로 적혀 있습니다. 무역 통계는 수출국과 수입국이 같은 흐름을 각각 보고하기 때문에 하나의 흐름이 서로 다른 숫자로 두 번 나옵니다. 단위가 섞여 있는 경우도 많습니다. 정제를 마쳐도 끝이 아닙니다. 입력 형식도 특성도 제각각인 시각화 패키지 가운데 하나를 골라야 합니다.

2025년에 공개한 0.x 버전도 이 문제를 제대로 풀지 못했습니다. 약 736MB의 FAOSTAT CSV 파일을 wheel 안에 그대로 넣었고 Python 3.13 이상에서만 설치할 수 있었습니다. 상태를 가진 매니저 클래스 중심의 구조여서 출력, 로깅, 그래프 표시가 부수 효과로 일어났습니다. 1.0은 처음부터 다시 만들었고 0.x API와는 호환되지 않습니다.

접근 방식

1.0은 하나의 파이프라인입니다. 어느 단계에서든 시작할 수 있어서 이미 NetworkX 그래프가 있다면 바로 시각화로 넘어가면 됩니다. 

raw table ──clean()──▶ flow table ──build_graph()──▶ NetworkX graph ──plot.<kind>()──▶ Plotly figure

결과

차트로 무엇을 볼 수 있는지 내장 샘플(FAOSTAT 물량, 톤 단위)로 두 가지 예를 들어 보겠습니다. 차트는 숫자를 보여줄 뿐, 숫자가 바뀐 이유까지 알려 주지는 않습니다.

주요 결정 사항 / 학습 내용

컬럼 이름은 무역 용어 대신 범용 어휘로 정했습니다. source, target, time, category, weight, unit입니다. 무역 데이터라면 source가 수출국이고 이주 데이터라면 출발국입니다. clean, build_graph, 모든 차트가 같은 단어를 인자 이름으로 씁니다. 화면에 표시할 이름은 flows.attrs["labels"]와 G.graph["labels"]에 담겨 데이터와 함께 움직입니다. 그래서 시각화 코드는 무역을 전혀 몰라도 FAOSTAT 차트에는 Exporter, Importer라는 이름이 제대로 붙습니다.

양쪽이 모두 보고한 흐름(mirror flow)은 사용자에게 맡기지 않고 clean에서 처리합니다. 두 값을 더하면 같은 흐름을 두 번 세게 되고 말없이 하나만 고르면 두 보고가 얼마나 다른지 가려집니다. 그래서 흐름마다 보고를 하나만 남기고(prefer=로 선택), 두 보고의 차이는 보고서에 기록합니다.

그래프 하나에는 구간 하나만 담습니다. 여러 기간이나 범주를 섞어 그래프를 만들면 aggregate="sum" 또는 "mean"을 지정하지 않는 한 MixedSliceError가 납니다. 단위가 섞이면 MixedUnitError가 납니다. FAOSTAT의 살아 있는 가축 품목은 물량이 마리 수와 톤으로 함께 들어 있는데 이 둘을 더한 값에는 아무 의미가 없기 때문입니다.

렌더링 백엔드는 Plotly 하나로 통일했습니다. 모든 차트는 색상과 호버 스타일이 같은 Plotly figure를 돌려줍니다. 0.x와는 정반대로 show()를 호출하거나 파일을 쓰는 함수는 하나도 없습니다.

차트가 쓰지 않는 인자는 아예 받지 않게 해서 넘기면 조용히 무시하는 대신 TypeError를 냅니다. size_by가 무시된 차트는 겉보기엔 멀쩡하지만 사용자가 요청한 차트가 아닙니다. plot.auto를 거쳤다면 어떤 차트를 왜 골랐는지도 오류 메시지에 함께 나옵니다.

전체 데이터 로더는 기본으로 수입국 보고 기준을 씁니다. 러시아는 2021년 이후 밀 수출을 보고하지 않아서 수출국 보고 기준으로는 2022년 밀 네트워크에서 러시아가 아예 빠집니다. 수입국 보고 기준으로는 러시아산 밀이 2022년 2,240만 톤, 2023년 3,400만 톤으로 잡힙니다. 수입을 보고하는 나라도 더 많습니다. 2021년 밀의 경우 수입국은 155개국, 수출국은 99개국이 보고했습니다. 필요하면 reporter="exporter"나 "combined"를 고를 수 있습니다.

한계점

기술 스택

링크

← 홈으로