Text I/O

numpy-ts provides NumPy-compatible text parsing and serialization, split into environment-agnostic browser functions and Node.js file I/O functions.

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 file with more flexible handling of missing values. Replaces missing values with a fill value instead of throwing.

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

Name	Type	Default	Description
`path`	`string`	—	Path to the text file 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/node';

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

fromregex

Extract data from a text file using a regular expression with capture groups.

function fromregex(path: string, regexp: RegExp | string, dtype?: DType): Promise<NDArray>

Name	Type	Default	Description
`path`	`string`	—	Path to the text file 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/node';

const arr = await fromregex('points.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 Node.js file 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.

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.

Node.js 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/node';

// 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/node';

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',
});

Synchronous versions are also available:

import * as np from 'numpy-ts/node';

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

Additional sync functions:

genfromtxtSync(path, options) — Like genfromtxt but reads from disk.
fromregexSync(path, regexp, dtype) — Like fromregex but reads from disk.

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

SerializeTxtOptions

Node.js API

loadtxt

savetxt

​Browser API

​parseTxt

​serializeTxt

​genfromtxt

​fromregex

​Options Reference

​ParseTxtOptions

​SerializeTxtOptions

​Node.js API

​loadtxt

​savetxt

Browser API

parseTxt

serializeTxt

genfromtxt

fromregex

Options Reference

ParseTxtOptions

SerializeTxtOptions

Node.js API

loadtxt

savetxt