{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Creating Arrays and Datasets\n", "\n", "There are several ways to create data structures in Scipp.\n", "`scipp.Variable` is particularly diverse.\n", "\n", "The examples on this page only show some representative creation functions and only the most commonly used arguments.\n", "See the linked reference pages for complete lists of functions and arguments.\n", "\n", "## Variable\n", "\n", "[Variables](../../generated/classes/scipp.Variable.rst) can be created using any of the dedicated [creation functions](../../reference/creation-functions.rst#creation-functions).\n", "These fall into several categories as described by the following subsections.\n", "\n", "### From Python Sequences or NumPy Arrays\n", "\n", "#### Arrays: N-D Variables\n", "\n", "Variables can be constructed from any Python object that can be used to create a NumPy array or NumPy arrays directly.\n", "See [NumPy array creation](https://numpy.org/doc/stable/user/basics.creation.html) for details.\n", "Given such an object, an array variable can be created using [scipp.array](../../generated/functions/scipp.array.rst) (not to be confused with [data arrays](../../generated/classes/scipp.DataArray.rst)!)" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import scipp as sc\n", "\n", "v1d = sc.array(dims=['x'], values=[1, 2, 3, 4])\n", "v2d = sc.array(dims=['x', 'y'], values=[[1, 2], [3, 4]])\n", "v3d = sc.array(dims=['x', 'y', 'z'], values=[[[1, 2], [3, 4]], [[5, 6], [7, 8]]])" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Alternatively, passing a NumPy array:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import numpy as np\n", "\n", "a = np.array([[1, 2], [3, 4]])\n", "v = sc.array(dims=['x', 'y'], values=a)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Note that *both* the NumPy array and Python lists are copied into the Scipp variable which leads to some additional time and memory costs.\n", "See [Filling with a Value](#Filling-with-a-Value) for ways of creating variables without this overhead.\n", "\n", "The `dtype` of the variable is deduced automatically in the above cases.\n", "The unit is set to `scipp.units.dimensionless` if the `dtype` is a numeric type (e.g. integer, floating point) or `None` otherwise (e.g. strings).\n", "This applies to all creation functions, not just `scipp.array`." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "v" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The `dtype` can be overridden with the `dtype` argument (see [Data types](../../reference/dtype.rst)):" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "sc.array(dims=['x', 'y'], values=[[1, 2], [3, 4]], dtype='float64')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The unit can and almost always should be set manually (see [unit](../../reference/units.rst)):" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "sc.array(dims=['x', 'y'], values=[[1, 2], [3, 4]], unit='m')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Variances can be added using the `variances` keyword:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "sc.array(\n", " dims=['x', 'y'], values=[[1.0, 2.0], [3.0, 4.0]], variances=[[0.1, 0.2], [0.3, 0.4]]\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "