NumPy .npy / .npz 검사기

사용법

1. .npy나 .npz를 상자에 끌어다 놓으세요. 헤더만 읽으므로 파일 크기는 상관없습니다.
2. dtype, shape, 원소 수를 먼저 보세요. "여기 뭐가 들었나"에 대한 답이고 읽기 한 번이면 됩니다.
3. 예상 데이터와 실제 데이터를 비교하세요. 실제가 적으면 파일이 잘린 것이고, 많으면 배열 뒤에 뭔가 덧붙은 것입니다.
4. 구조체 dtype이면 필드 표를 펼치세요. 정렬된 dtype이 끼워 넣은 이름 없는 패딩까지 형식·오프셋·크기가 모두 나옵니다.
5. .npz라면 멤버 이름을 눌러 그 배열을 살펴보세요. 목록에는 압축된 크기와 풀었을 때의 크기가 함께 나옵니다.

자주 묻는 질문

.npy 헤더에는 정확히 무엇이 들어 있나요?

매직 6바이트(\x93NUMPY), 2바이트 버전, 헤더 길이, 그리고 헤더 본문입니다. 본문은 descr·fortran_order·shape 세 키만 가진 파이썬 dict 리터럴입니다. JSON이 아니라서 JSON.parse로는 읽을 수 없습니다. 문자열은 작은따옴표, 불리언은 True와 False, shape은 (3)이 아니라 (3,)처럼 쓰는 튜플이고, 닫는 중괄호 앞에는 쉼표가 하나 더 붙습니다. 그다음 배열 데이터가 64바이트 경계에서 시작하도록 공백으로 채웁니다. numpy가 정렬된 로드로 파일을 메모리 매핑할 수 있는 이유가 이 패딩입니다. 이 도구는 descr를 파일에 적힌 그대로 보여 주므로 중간에 정규화되었는지 의심할 필요가 없습니다.

문자열 배열이 글자 수의 네 배나 되는 이유는 뭔가요?

numpy의 U dtype이 UCS-4로 저장하기 때문입니다. 어떤 문자든 4바이트 고정이라 원소 크기가 선언 길이의 네 배가 됩니다. U32 필드는 값이 전부 "ok"여도 원소마다 128바이트를 씁니다. 바이트 문자열 S는 문자당 1바이트지만 나름의 함정이 있습니다. 읽을 때 끝의 NUL을 떼어내므로 정말로 0바이트로 끝나는 값은 왕복이 안 되고, 중간의 NUL은 그대로 남습니다. 데이터셋이 이상하게 크다면 대개 U dtype이 원인이고, 해법은 인코딩을 정해 S로 저장하거나 문자열을 아예 별도 배열로 빼는 것입니다.

dtype이 object로 나옵니다. 무슨 뜻이고 왜 경고하나요?

object 배열은 값을 저장하지 않고 포인터를 저장합니다. 그래서 저장할 때 numpy가 전체를 피클로 직렬화하고 불러올 때 역직렬화합니다. 역직렬화는 파싱이 아닙니다. 임의의 객체를 만들고 임의의 코드를 호출할 수 있습니다. numpy.load가 allow_pickle=True 없이는 object 배열을 거부하는 이유입니다. descr가 |O인 .npy는 데이터인 만큼 프로그램이기도 하고, 안전성은 작성자의 안전성과 같습니다. 이 페이지는 절대 피클을 풀지 않고 dtype과 피클 크기만 알려 주고 멈춥니다. 내용이 평범한 문자열이나 들쭉날쭉한 리스트라면 고정 폭 dtype이나 .npz의 여러 배열로 다시 쓰는 편이 낫습니다.

fortran_order는 무엇을 바꾸나요?

같은 숫자가 파일에 놓이는 순서만 바꿉니다. False면 마지막 축이 가장 빨리 변하고(C, 행 우선), True면 첫 축이 가장 빨리 변합니다(열 우선). np.asfortranarray를 거쳤거나 포트란·MATLAB에서 온 데이터가 그렇습니다. shape과 dtype은 어느 쪽이든 같으므로 이 플래그를 무시한 리더는 실패하지 않습니다. 대신 배열을 조용히 전치해 버리는데, 예외가 나는 것보다 훨씬 나쁜 결과입니다. 여기의 미리보기는 논리적 배치가 아니라 파일을 따라가므로 포트란 순서의 2×3 배열은 0열, 1열, 2열 순으로 읽힙니다.

포맷 버전이 왜 셋이나 있나요?

1.0은 헤더 길이를 2바이트에 담아 헤더가 65535바이트로 제한됩니다. 2.0은 그것으로 모자란 드문 경우에 4바이트를 씁니다. 필드가 수천 개인 구조체 dtype이면 그렇게 되고 헤더가 수백 KB에 이릅니다. 3.0은 2.0과 같되 헤더를 Latin-1이 아니라 UTF-8로 선언하며, Latin-1에 없는 문자가 필드 이름에 있을 때만 numpy가 씁니다. numpy는 항상 들어맞는 가장 낮은 버전을 고르므로 2.0이나 3.0이라는 사실 자체가 정보입니다. 하나 더, numpy의 로더는 max_header_size를 올리지 않으면 10000바이트가 넘는 헤더를 거부합니다. 정상적인 2.0 파일이 파이썬에서는 안 열리면서 여기서는 열릴 수 있습니다.

파일이 업로드되나요? 아주 큰 배열도 열 수 있나요?

업로드는 없고, 열 수 있습니다. 브라우저의 File API로 조각만 읽습니다. 헤더용 1KB 남짓과 값 미리보기용 몇 KB가 전부입니다. 2GB 배열을 메모리에 올리는 일은 없습니다. 바로 그 상황을 위한 도구입니다. 누가 파일을 건넸고, dtype과 shape이 궁금하고, 실제로 불러오면 몇 분과 램 대부분을 쓰게 되는 상황 말입니다. .npz는 파일 끝의 zip 디렉터리와 멤버별 헤더만 읽으므로 목록 조회는 읽기 두 번에 멤버당 한 번입니다. 아무것도 전송하지 않으니 페이지를 연 뒤 네트워크를 끊어도 그대로 동작합니다.

관련 도구