# Tutorial: 1-creation

## 1-creation

# Tutorial 1: Array Creation and Factory Functions

This tutorial explores the fundamental ways to create `NDArray` objects, from simple JavaScript arrays to complex random distributions.

## Creating from Existing Data

The most common way to create an array is from a standard JavaScript `Array`.

### `ndarray.array()`

This function intelligently converts a nested JavaScript array into a multi-dimensional `NDArray`. It will infer the shape and data type.

    // Import the library
    import * as ndarray from 'ndarray';

    // Create a 2D array (a 2x3 matrix)
    const a = ndarray.array([[1, 2, 3], [4, 5, 6]]);

    console.log(a.shape);
    // => Int32Array(2) [ 2, 3 ]

    console.log(a.toString());
    // => array([[1, 2, 3],
    //           [4, 5, 6]], dtype=float64)

    // You can also specify the data type
    const b = ndarray.array([1, 2, 3], 'int32');
    console.log(b.dtype);
    // => int32

## Creating Arrays of a Specific Shape

Several "factory" functions exist to create new arrays with a given shape, often filled with a default value.

### `ndarray.zeros()` and `ndarray.ones()`

These create an array of the specified shape with all elements initialized to 0 or 1.

    // A 3x2 matrix of all zeros
    const z = ndarray.zeros([3, 2]);

    // A 2x2x2 cube of all ones
    const o = ndarray.ones([2, 2, 2]);

### `ndarray.full()`

This creates an array filled with any scalar value you provide.

    // A 2x4 matrix filled with the number 42
    const f = ndarray.full([2, 4], 42);

### `ndarray.eye()`

This creates a 2D identity matrix (1s on the diagonal, 0s elsewhere).

    const i = ndarray.eye(3);
    // => array([[1, 0, 0],
    //           [0, 1, 0],
    //           [0, 0, 1]], dtype=float64)

## Creating Arrays from a Numerical Range

### `ndarray.arange()`

Creates a 1D array with values in a defined range with a specific step.

    // An array of values from 0 up to (but not including) 10
    const r1 = ndarray.arange(10);
    // => array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9], dtype=float64)

    // An array from 2 to 8, with a step of 2
    const r2 = ndarray.arange(2, 9, 2);
    // => array([2, 4, 6, 8], dtype=float64)

### `ndarray.linspace()`

Creates a 1D array with a specific number of points spaced evenly between two values.

    // 5 points linearly spaced between 0 and 100 (inclusive)
    const l = ndarray.linspace(0, 100, 5);
    // => array([0, 25, 50, 75, 100], dtype=float64)

## Creating Random Arrays

The `ndarray.random` module provides functions to create arrays with random values from various statistical distributions.

### Uniform Distribution

The `random()` function creates an array with values from a uniform distribution.

    // A 2x2 array of random numbers from a uniform distribution between 0 and 1
    const u = ndarray.random.random([2, 2]);

    // A 3x3 array of random numbers from a uniform distribution between -5 and 5
    const u2 = ndarray.random.random([3, 3], -5, 5);

### Normal (Gaussian) Distribution

The `normal()` function samples from a normal distribution.

    // A 2x2 array of random numbers from a standard normal distribution (mean 0, std 1)
    const n = ndarray.random.normal([2, 2]);

    // A 3x3 array from a normal distribution with mean 100 and standard deviation 15
    const n2 = ndarray.random.normal([3, 3], 100, 15);