Text I/O

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

Name	Type	Default	Description
`text`	`string`	—	The text content to parse.
`options`	`ParseTxtOptions`	`{}`	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

Name	Type	Default	Description
`arr`	`NDArray`	—	Array to serialize (must be 1-D or 2-D).
`options`	`SerializeTxtOptions`	`{}`	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

Name	Type	Default	Description
`text`	`string`	—	The text content to parse.
`options`	`LoadTxtOptions`	`{}`	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

Name	Type	Default	Description
`text`	`string`	—	The text content to search.
`regexp`	`RegExp \| string`	—	Regular expression with capture groups. Each match produces one row; each group produces one column.
`dtype`	`DType`	`'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

Name	Type	Default	Description
`delimiter`	`string`	whitespace	String used to separate values. By default, any consecutive whitespace acts as delimiter.
`comments`	`string`	`'#'`	Character indicating the start of a comment line.
`skiprows`	`number`	`0`	Number of lines to skip at the beginning of the file.
`usecols`	`number \| number[]`	all	Which columns to read (0-indexed).
`max_rows`	`number`	all	Maximum number of data rows to read (after `skiprows`).
`dtype`	`DType`	`'float64'`	Data type of the resulting array.
`encoding`	`string`	`'utf-8'`	Character encoding (only relevant for file I/O operations).
`missing_values`	`string \| string[]`	`undefined`	String representation(s) of missing values (used by `genfromtxt`).
`filling_values`	`number`	`NaN` (float) / `0` (int)	Replacement value for missing entries.

LoadTxtOptions

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

SerializeTxtOptions

Name	Type	Default	Description
`fmt`	`string`	`'%.18e'`	Printf-style format string. Examples: `'%.6f'` (6 decimals), `'%.2e'` (scientific), `'%d'` (integer).
`delimiter`	`string`	`' '`	String separating columns.
`newline`	`string`	`'\n'`	String written at the end of each row.
`header`	`string`	`undefined`	Text written at the beginning of the file. Automatically prefixed with the comment character.
`footer`	`string`	`undefined`	Text written at the end of the file.
`comments`	`string`	`'# '`	String prepended to header and footer lines.

SaveTxtOptions

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

File I/O API

Async
Sync

loadtxt

Load data from a text file on disk.

function loadtxt(path: string, options?: LoadTxtOptions): Promise<NDArray>

Name	Type	Default	Description
`path`	`string`	—	Path to the text file.
`options`	`LoadTxtOptions`	`{}`	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>

Name	Type	Default	Description
`path`	`string`	—	Output file path.
`arr`	`NDArray`	—	Array to save (must be 1-D or 2-D).
`options`	`SaveTxtOptions`	`{}`	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>

Name	Type	Default	Description
`path`	`string`	—	Path to the text file.
`options`	`LoadTxtOptions`	`{}`	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>

Name	Type	Default	Description
`path`	`string`	—	Path to the text file.
`regexp`	`RegExp \| string`	—	Regular expression with capture groups.
`dtype`	`DType`	`'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.]+)/);

Synchronous versions of all file I/O functions:

import * as np from 'numpy-ts';

// loadtxt / savetxt
const data = np.loadtxtSync('data.csv', { delimiter: ',' });
np.savetxtSync('output.csv', data, { delimiter: ',', fmt: '%d' });

// genfromtxt / fromregex (file-based)
const filled = np.genfromtxtFileSync('data.csv', {
  delimiter: ',',
  missing_values: [''],
  filling_values: 0,
});
const matched = np.fromregexFileSync('points.log', /x=([\d.]+), y=([\d.]+)/);

Overview

NDArray

Array Creation

Math

Array Manipulation

Reductions & Statistics

Linear Algebra

Logic & Comparison

Sorting & Searching

Set Operations

Bitwise

Indexing

Gradient & Differences

Polynomials

Random (np.random)

FFT (np.fft)

I/O

Utilities

Browser API

parseTxt

serializeTxt

genfromtxt

fromregex

Options Reference

ParseTxtOptions

LoadTxtOptions

SerializeTxtOptions

SaveTxtOptions

File I/O API

loadtxt

savetxt

genfromtxtFile

fromregexFile

​Browser API

​parseTxt

​serializeTxt

​genfromtxt

​fromregex

​Options Reference

​ParseTxtOptions

​LoadTxtOptions

​SerializeTxtOptions

​SaveTxtOptions

​File I/O API

​loadtxt

​savetxt

​genfromtxtFile

​fromregexFile

Browser API

parseTxt

serializeTxt

genfromtxt

fromregex

Options Reference

ParseTxtOptions

LoadTxtOptions

SerializeTxtOptions

SaveTxtOptions

File I/O API

loadtxt

savetxt

genfromtxtFile

fromregexFile