Skip to content

ReferenceGuide.md

Latest commit

 

History

History
executable file
·
560 lines (394 loc) · 12.6 KB

ReferenceGuide.md

File metadata and controls

executable file
·
560 lines (394 loc) · 12.6 KB

Mat - Complete API Documentation with Examples

All examples extracted from the comprehensive test suite (1461 tests)

Table of Contents

  1. Matrix Creation
  2. Indexing and Slicing
  3. Arithmetic Operations
  4. Broadcasting
  5. Linear Algebra
  6. Statistical Functions
  7. Element-wise Math
  8. Machine Learning
  9. Random Number Generation
  10. Data Manipulation
  11. Comparison and Boolean Operations
  12. Display and Formatting
  13. Pandas-Style Data Analysis

Matrix Creation

Basic Constructors

zeros creates matrix filled with zeros

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val m = Mat.zeros[Double](3, 4)
println(m)
// 3x4 Mat[Double]:
//  (0.0, 0.0, 0.0, 0.0),
//  (0.0, 0.0, 0.0, 0.0),
//  (0.0, 0.0, 0.0, 0.0)

ones creates matrix filled with ones

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val m = Mat.ones[Double](2, 2)
println(m)
// 2x2 Mat[Double]:
//  (1.0, 1.0),
//  (1.0, 1.0)

eye creates identity matrix

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val m = Mat.eye[Double](3)
println(m)
// 3x3 Mat[Double]:
//  (1.0, 0.0, 0.0),
//  (0.0, 1.0, 0.0),
//  (0.0, 0.0, 1.0)

full creates matrix with specified value

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val m = Mat.full[Double](2, 3, 7.0)
println(m)
// 2x3 Mat[Double]:
//  (7.0, 7.0, 7.0),
//  (7.0, 7.0, 7.0)

From Tuples and Values

apply creates matrix from tuples

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val m = Mat[Double]((1, 2), (3, 4))
println(m)
// 2x2 Mat[Double]:
//  (1.0, 2.0),
//  (3.0, 4.0)

row creates row vector

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val v = Mat.row[Double](1, 2, 3)
println(v)
// 1x3 Mat[Double]:
//  (1.0, 2.0, 3.0)

col creates column vector

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val v = Mat.col[Double](1, 2, 3)
println(v)
// 3x1 Mat[Double]:
//  (1.0),
//  (2.0),
//  (3.0)

Mat(scalars...) creates column vector

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val v = Mat[Double](1.0, 2.0, 3.0)
println(v)
// 3x1 Mat[Double]:
//  (1.0),
//  (2.0),
//  (3.0)

Vector Types (CVec / RVec)

CVec[T] (column vector, n×1) and RVec[T] (row vector, 1×n) are opaque types backed by Mat[T]. Their *@ overloads dispatch entirely on static types — no asInstanceOf or runtime branching.

CVec / RVec creation

CVec.apply / RVec.apply — from varargs

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val y: CVecD = CVec(1.0, 2.0, 3.0)   // 3×1 column vector
val r: RVecD = RVec(4.0, 5.0, 6.0)   // 1×3 row vector

Factory methods

val z = CVec.zeros[Double](5)        // 5-element column of zeros
val o = CVec.ones[Double](5)         // 5-element column of ones
val v = CVec.fromArray(Array(1.0, 2.0, 3.0))
val c = CVec.fromMat(someMatD)       // n×1 or 1×n Mat → CVec

RVec provides the same factories. Type aliases: CVecD = CVec[Double], RVecD = RVec[Double].

*@ dispatch table

Expression Types Result
y.T *@ y RVec *@ CVec T (dot product)
y *@ y CVec *@ CVec T (auto-transpose)
r *@ r RVec *@ RVec T (auto-transpose)
y *@ y.T CVec *@ RVec Mat[T] (outer product)
X *@ y Mat *@ CVec CVec[T]
y.T *@ X RVec *@ Mat RVec[T]
y *@ X CVec *@ Mat RVec[T] (auto-transpose)
X *@ r Mat *@ RVec CVec[T] (auto-transpose)

Quadratic form example

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val y: CVecD = CVec(1.0, 2.0, 3.0)
val X: MatD  = MatD((2,0,0),(0,3,0),(0,0,4))

val q: Double = y.T *@ X *@ y   // = 50.0
// println(q)
// 50.0

CVec arithmetic

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val a: CVecD = CVec(1.0, 2.0, 3.0)
val b: CVecD = CVec(4.0, 5.0, 6.0)

val sum   = a + b           // CVec + CVec
val diff  = b - a           // CVec - CVec
val sp1   = a + 1.0         // CVec + scalar
val sm1   = a - 1.0         // CVec - scalar
val s2    = 2.0 * a         // Double * CVec
val i2    = 2   * a         // Int    * CVec
val l2    = 2L  * a         // Long   * CVec
val norm  = a.norm          // Euclidean norm
// println(a.show)
// 3x1 CVec[Double]:
//  (1.0, 2.0, 3.0)

RVec supports the same arithmetic operations.

Scalar Extraction

item — extract scalar from 1×1 matrix (NumPy: .item())

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val a = MatD((3.0, 1.0), (1.0, 2.0))
val s: Double = (a *@ a.T).diagonal.sum.item   // extract scalar from 1×1
// throws IllegalArgumentException if not 1×1

Pandas-Style Data Analysis

All methods are defined on Mat[T] and work with MatD, MatF, and MatB.

Row selection

head returns first n rows

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val m = MatD((1,2),(3,4),(5,6),(7,8))
m.head(2)
// 2x2 Mat[Double]:
//  (1.0, 2.0),
//  (3.0, 4.0)

tail returns last n rows

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val m = MatD((1,2),(3,4),(5,6),(7,8))
m.tail(2)
// 2x2 Mat[Double]:
//  (5.0, 6.0),
//  (7.0, 8.0)

Argmin / Argmax per axis

idxmin(axis) — index of minimum per column (axis=0) or per row (axis=1)

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val m = MatD((3,1),(2,4),(5,0))
m.idxmin(0)   // 1x3 — column minimums at rows: (1, 2, 2)
m.idxmin(1)   // 3x1 — row minimums at cols:    (1, 0, 1)

idxmax(axis) — index of maximum per column or row

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val m = MatD((3,1),(2,4),(5,0))
m.idxmax(0)   // 1x3 — column maximums at rows: (2, 1, 1)
m.idxmax(1)   // 3x1 — row maximums at cols:    (0, 1, 0)

Cumulative min / max

cummax(axis) — running maximum along an axis

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val m = MatD((3,1),(1,4),(5,2))
m.cummax(0)
// 3x2 Mat[Double]:
//  (3.0, 1.0),
//  (3.0, 4.0),
//  (5.0, 4.0)

cummin(axis) — running minimum along an axis

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val m = MatD((3,1),(1,4),(5,2))
m.cummin(0)
// 3x2 Mat[Double]:
//  (3.0, 1.0),
//  (1.0, 1.0),
//  (1.0, 1.0)

Top / bottom N values

nlargest(n) — n largest values as a row vector

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val m = MatD((3,1),(2,5),(4,0))
m.nlargest(3)   // 1x3: (5.0, 4.0, 3.0)

nsmallest(n) — n smallest values as a row vector

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val m = MatD((3,1),(2,5),(4,0))
m.nsmallest(3)  // 1x3: (0.0, 1.0, 2.0)

Range test

between(lo, hi) — boolean mask: lo <= x <= hi

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val m = MatD((1,5),(3,7),(9,2))
m.between(2.0, 6.0)
// 3x2 Mat[Boolean]:
//  (false, true),
//  (true,  false),
//  (false, true)

Unique values and frequency

nunique — count of distinct values

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val m = MatD((1,2),(2,3),(1,3))
m.nunique   // 3

valueCounts — frequency table, descending

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val m = MatD((1,2),(2,3),(1,3))
m.valueCounts   // Array((2.0, 2), (1.0, 2), (3.0, 2)) — ties broken by order

Shift / lag

shift(n, fill, axis=0) — shift rows (axis=0) or columns (axis=1) by n steps

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val m = MatD((1,2),(3,4),(5,6))
m.shift(1, Double.NaN)
// 3x2 Mat[Double]:
//  (NaN,  NaN),
//  (1.0,  2.0),
//  (3.0,  4.0)

pct_change(axis=0) — element-wise percent change from previous position

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val prices = MatD((100.0),(110.0),(99.0))
prices.pct_change()
// 3x1 Mat[Double]:
//  (NaN),
//  (0.1),
//  (-0.1)

NaN fill

fillna(value) — replace NaN with a constant

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val m = MatD((1,Double.NaN),(Double.NaN,4))
m.fillna(0.0)
// 2x2 Mat[Double]:
//  (1.0, 0.0),
//  (0.0, 4.0)

Descriptive statistics summary

describe — returns (labels, 8×cols summary matrix)

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val m = MatD((1,2),(3,4),(5,6))
val (labels, stats) = m.describe
// labels: Array("count","mean","std","min","25%","50%","75%","max")
// stats:  8x2 Mat[Double] — one column per input column

Rolling window

rolling(window) — sliding-window aggregations (NaN for the first window-1 rows)

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.data.*

val m = MatD((1),(2),(3),(4),(5))
m.rolling(3).mean
// 5x1 Mat[Double]:
//  (NaN), (NaN), (2.0), (3.0), (4.0)

m.rolling(3).sum
// 5x1 Mat[Double]:
//  (NaN), (NaN), (6.0), (9.0), (12.0)

Available aggregations: .mean, .sum, .min, .max, .std

CSV with named columns (MatResult)

FileOps.loadSmart returns a MatResult[T] that pairs headers with matrix data:

#!/usr/bin/env -S scala-cli shebang -Wunused:imports -Wunused:locals -deprecation

//> using dep org.vastblue:uni_3:0.11.2

import uni.*
import uni.data.*
import uni.io.FileOps.*

val result = loadSmart(Paths.get("data.csv"))          // MatResult[Big]
val col    = result("Price")                            // ColVec[Big] — throws if not found
val maybeQ = result.col("Qty")                         // Option[ColVec[Big]]
val idx    = result.columnIndex                         // Map[String, Int]

// Convert to Double
val dbl = loadSmart(Paths.get("data.csv"), _.toDouble) // MatResult[Double]
val prices: ColVec[Double] = dbl("Price")

Quick Start Guide | README Documentation auto-generated from Mat test suite - all examples are validated and passing.