scalar_extract — squeeze / item / bool / first_valid_index / last_valid_index

Utilities to extract scalar values from Series and DataFrames. Mirrors pandas.Series.squeeze(), Series.item(), Series.bool(), Series.first_valid_index(), Series.last_valid_index(), and their DataFrame equivalents.

squeezeSeries — extract scalar from a single-element Series

Python pandas equivalent:

import pandas as pd

s = pd.Series([42])
print(s.squeeze())    # 42

s2 = pd.Series([1, 2, 3])
print(s2.squeeze())   # Series unchanged

tsb equivalent:

import { Series, squeezeSeries } from "tsb";

squeezeSeries(new Series({ data: [42] }));     // 42
squeezeSeries(new Series({ data: [1, 2, 3] })); // Series([1, 2, 3])

squeezeDataFrame — squeeze 1-D axis objects

Python pandas equivalent:

import pandas as pd

df1x1 = pd.DataFrame({"A": [10]})
print(df1x1.squeeze())          # 10 (scalar)

df1xN = pd.DataFrame({"A": [1], "B": [2], "C": [3]})
print(df1xN.squeeze())          # Series indexed by column names

dfNx1 = pd.DataFrame({"A": [1, 2, 3]})
print(dfNx1.squeeze())          # Series indexed by row labels
print(dfNx1.squeeze(axis=1))    # same as above

tsb equivalent:

import { DataFrame, squeezeDataFrame } from "tsb";

// 1×1 → scalar
squeezeDataFrame(DataFrame.fromColumns({ A: [10] }));          // 10

// 1 row, N cols → Series over columns
squeezeDataFrame(DataFrame.fromColumns({ A: [1], B: [2] }));   // Series([1, 2])

// N rows, 1 col → Series over rows
squeezeDataFrame(DataFrame.fromColumns({ A: [1, 2, 3] }));     // Series([1, 2, 3])

// axis=1: force squeeze along columns axis
squeezeDataFrame(DataFrame.fromColumns({ A: [1, 2, 3] }), 1);  // Series([1, 2, 3])

itemSeries — return the single element of a Series

Python pandas equivalent:

import pandas as pd

s = pd.Series([7])
print(s.item())   # 7

s2 = pd.Series([1, 2])
s2.item()  # ValueError

tsb equivalent:

import { Series, itemSeries } from "tsb";

itemSeries(new Series({ data: [7] }));       // 7
itemSeries(new Series({ data: [1, 2] }));    // throws RangeError

boolSeries / boolDataFrame — convert to boolean

Python pandas equivalent:

import pandas as pd

pd.Series([1]).bool()     # True
pd.Series([0]).bool()     # False
pd.DataFrame({"A": [1]}).bool()  # True

tsb equivalent:

import { Series, DataFrame, boolSeries, boolDataFrame } from "tsb";

boolSeries(new Series({ data: [1] }));               // true
boolSeries(new Series({ data: [0] }));               // false
boolDataFrame(DataFrame.fromColumns({ A: [1] }));    // true
boolDataFrame(DataFrame.fromColumns({ A: [false] })); // false

firstValidIndex / lastValidIndex — find first/last non-NA label

Python pandas equivalent:

import pandas as pd
import numpy as np

s = pd.Series([None, np.nan, 3.0, 4.0], index=["a", "b", "c", "d"])
print(s.first_valid_index())  # "a" ... wait: "c"
print(s.last_valid_index())   # "d"

s_all_na = pd.Series([None, None])
print(s_all_na.first_valid_index())  # None

tsb equivalent:

import { Series, firstValidIndex, lastValidIndex } from "tsb";

const s = new Series({ data: [null, NaN, 3, 4], index: ["a", "b", "c", "d"] });
firstValidIndex(s);   // "c"
lastValidIndex(s);    // "d"

const allNA = new Series({ data: [null, null] });
firstValidIndex(allNA);  // null

dataFrameFirstValidIndex / dataFrameLastValidIndex

Python pandas equivalent:

import pandas as pd
import numpy as np

df = pd.DataFrame({"A": [None, None, 1], "B": [None, 2, 3]})
print(df.first_valid_index())  # 1  (row 1 has B=2)
print(df.last_valid_index())   # 2  (row 2 has A=1, B=3)

tsb equivalent:

import { DataFrame, dataFrameFirstValidIndex, dataFrameLastValidIndex } from "tsb";

const df = DataFrame.fromColumns({
  A: [null, null, 1],
  B: [null, 2, 3],
});
dataFrameFirstValidIndex(df);  // 1
dataFrameLastValidIndex(df);   // 2