Skip to main content
numpy-ts provides NumPy-compatible text parsing and serialization, split into environment-agnostic buffer functions and file I/O functions. File I/O functions are available from the main numpy-ts entry point and work on Node.js, Bun, and Deno. They throw in browser environments.
The numpy-ts/node entry point is deprecated. Imports from it still work but you should migrate to numpy-ts.

​
Browser API

These functions work with strings and can be used in any JavaScript environment.

​
parseTxt

Parse a text string into an NDArray. Each row must have the same number of values. 
function parseTxt(text: string, options?: ParseTxtOptions): NDArray
NameTypeDefaultDescription
textstring—The text content to parse.
optionsParseTxtOptions{}Parsing options (see table below).
Returns: NDArray — 2-D array (or 1-D if a single row/column). 
import { parseTxt } from 'numpy-ts';

const csv = `1,2,3
4,5,6
7,8,9`;

const arr = parseTxt(csv, { delimiter: ',' });
// shape [3, 3]

​
serializeTxt

Serialize an NDArray to a text string. 
function serializeTxt(arr: NDArray, options?: SerializeTxtOptions): string
NameTypeDefaultDescription
arrNDArray—Array to serialize (must be 1-D or 2-D).
optionsSerializeTxtOptions{}Serialization options (see table below).
Returns: string — Text representation of the array. 
import * as np from 'numpy-ts';
import { serializeTxt } from 'numpy-ts';

const arr = np.array([[1, 2, 3], [4, 5, 6]]);
const csv = serializeTxt(arr, { delimiter: ',', fmt: '%d' });
// "1,2,3\n4,5,6\n"

​
genfromtxt

Parse a text string with flexible handling of missing values. Replaces missing values with a fill value instead of throwing. This is a buffer-based function that works with strings in any environment. 
function genfromtxt(text: string, options?: LoadTxtOptions): NDArray
NameTypeDefaultDescription
textstring—The text content to parse.
optionsLoadTxtOptions{}Parsing options. Use missing_values and filling_values to handle gaps.
Returns: NDArray — Parsed array with missing values filled in. 
import { genfromtxt } from 'numpy-ts';

const csv = `1,2,3
4,,6
7,8,`;

const arr = genfromtxt(csv, {
  delimiter: ',',
  missing_values: [''],
  filling_values: 0,
});
// array([[1, 2, 3],
//        [4, 0, 6],
//        [7, 8, 0]])

​
fromregex

Extract data from a text string using a regular expression with capture groups. This is a buffer-based function that works with strings in any environment. 
function fromregex(text: string, regexp: RegExp | string, dtype?: DType): NDArray
NameTypeDefaultDescription
textstring—The text content to search.
regexpRegExp | string—Regular expression with capture groups. Each match produces one row; each group produces one column.
dtypeDType'float64'Data type of the resulting array.
Returns: NDArray — Array with one row per match and one column per capture group. 
import { fromregex } from 'numpy-ts';

const log = `x=1.5, y=2.3
x=3.0, y=4.1
x=5.5, y=6.7`;

const arr = fromregex(log, /x=([\d.]+), y=([\d.]+)/);
// array([[1.5, 2.3],
//        [3.0, 4.1],
//        [5.5, 6.7]])

​
Options Reference

​
ParseTxtOptions

NameTypeDefaultDescription
delimiterstringwhitespaceString used to separate values. By default, any consecutive whitespace acts as delimiter.
commentsstring'#'Character indicating the start of a comment line.
skiprowsnumber0Number of lines to skip at the beginning of the file.
usecolsnumber | number[]allWhich columns to read (0-indexed).
max_rowsnumberallMaximum number of data rows to read (after skiprows).
dtypeDType'float64'Data type of the resulting array.
encodingstring'utf-8'Character encoding (only relevant for file I/O operations).
missing_valuesstring | string[]undefinedString representation(s) of missing values (used by genfromtxt).
filling_valuesnumberNaN (float) / 0 (int)Replacement value for missing entries.

​
LoadTxtOptions

Alias for ParseTxtOptions. Used by loadtxt, genfromtxt, and their file-based variants.

​
SerializeTxtOptions

NameTypeDefaultDescription
fmtstring'%.18e'Printf-style format string. Examples: '%.6f' (6 decimals), '%.2e' (scientific), '%d' (integer).
delimiterstring' 'String separating columns.
newlinestring'\n'String written at the end of each row.
headerstringundefinedText written at the beginning of the file. Automatically prefixed with the comment character.
footerstringundefinedText written at the end of the file.
commentsstring'# 'String prepended to header and footer lines.

​
SaveTxtOptions

Alias for SerializeTxtOptions. Used by savetxt and its file-based variants.

​
File I/O API

​
loadtxt

Load data from a text file on disk.
function loadtxt(path: string, options?: LoadTxtOptions): Promise<NDArray>
NameTypeDefaultDescription
pathstring—Path to the text file.
optionsLoadTxtOptions{}Parsing options.
Returns: Promise<NDArray> — The parsed array.
import * as np from 'numpy-ts';

// Load CSV
const data = await np.loadtxt('data.csv', { delimiter: ',' });

// Load with column selection and header skip
const subset = await np.loadtxt('data.txt', {
  usecols: [0, 2],
  skiprows: 1,
});

​
savetxt

Save an array to a text file.
function savetxt(
  path: string,
  arr: NDArray,
  options?: SaveTxtOptions
): Promise<void>
NameTypeDefaultDescription
pathstring—Output file path.
arrNDArray—Array to save (must be 1-D or 2-D).
optionsSaveTxtOptions{}Serialization options.
Returns: Promise<void>
import * as np from 'numpy-ts';

const arr = np.array([[1, 2, 3], [4, 5, 6]]);

// Save as CSV
await np.savetxt('output.csv', arr, { delimiter: ',', fmt: '%d' });

// Save with header
await np.savetxt('output.txt', arr, {
  header: 'x y z',
  fmt: '%.4f',
});

​
genfromtxtFile

Load and parse a text file from disk with flexible handling of missing values. This is the file-based equivalent of genfromtxt.
function genfromtxtFile(path: string, options?: LoadTxtOptions): Promise<NDArray>
NameTypeDefaultDescription
pathstring—Path to the text file.
optionsLoadTxtOptions{}Parsing options. Use missing_values and filling_values to handle gaps.
Returns: Promise<NDArray> — Parsed array with missing values filled in.
import * as np from 'numpy-ts';

const arr = await np.genfromtxtFile('data.csv', {
  delimiter: ',',
  missing_values: [''],
  filling_values: 0,
});

​
fromregexFile

Extract data from a text file on disk using a regular expression with capture groups. This is the file-based equivalent of fromregex.
function fromregexFile(path: string, regexp: RegExp | string, dtype?: DType): Promise<NDArray>
NameTypeDefaultDescription
pathstring—Path to the text file.
regexpRegExp | string—Regular expression with capture groups.
dtypeDType'float64'Data type of the resulting array.
Returns: Promise<NDArray>
import * as np from 'numpy-ts';

const arr = await np.fromregexFile('points.log', /x=([\d.]+), y=([\d.]+)/);