Quick start#

This section provides a quick introduction to Scipp. For in depth explanations refer to the sections in the user guide.

[1]:
import numpy as np
import scipp as sc

We start by creating some variables:

[2]:
var = sc.Variable(dims=['y', 'x'], values=np.random.rand(4,5))
sc.show(var)
dims=('y', 'x'), shape=(4, 5), unit=dimensionless, variances=Falsevalues yx

Type the name of a variable at the end of a cell to generate an HTML respresentation:

[3]:
var
[3]:
Show/Hide data repr Show/Hide attributes
scipp.Variable (416 Bytes)
    • (y: 4, x: 5)
      float64
      𝟙
      0.510, 0.188, ..., 0.861, 0.984
      Values:
      array([[0.51016585, 0.18827322, 0.13085134, 0.96372934, 0.0744567 ], [0.06814973, 0.26388695, 0.05553468, 0.34085846, 0.03323121], [0.49310144, 0.78119323, 0.05417718, 0.83678959, 0.15066982], [0.01105393, 0.31648451, 0.16625937, 0.86061993, 0.98386346]])
[4]:
x = sc.Variable(dims=['x'], values=np.arange(5), unit=sc.units.m)
y = sc.Variable(dims=['y'], values=np.arange(4), unit=sc.units.m)

We combine the variables into a data array:

[5]:
array = sc.DataArray(
    data=var,
    coords={'x': x, 'y': y})
sc.show(array)
array
(dims=('y', 'x'), shape=(4, 5), unit=dimensionless, variances=False)values yx yy(dims=('y',), shape=(4,), unit=m, variances=False)values y xx(dims=('x',), shape=(5,), unit=m, variances=False)values x
[5]:
Show/Hide data repr Show/Hide attributes
scipp.DataArray (1.48 KB)
    • y: 4
    • x: 5
    • x
      (x)
      int64
      m
      0, 1, 2, 3, 4
      Values:
      array([0, 1, 2, 3, 4])
    • y
      (y)
      int64
      m
      0, 1, 2, 3
      Values:
      array([0, 1, 2, 3])
    • (y, x)
      float64
      𝟙
      0.510, 0.188, ..., 0.861, 0.984
      Values:
      array([[0.51016585, 0.18827322, 0.13085134, 0.96372934, 0.0744567 ], [0.06814973, 0.26388695, 0.05553468, 0.34085846, 0.03323121], [0.49310144, 0.78119323, 0.05417718, 0.83678959, 0.15066982], [0.01105393, 0.31648451, 0.16625937, 0.86061993, 0.98386346]])

Variables can have uncertainties. Scipp stores these as variances (the square of the standard deviation):

[6]:
array.variances = np.square(np.random.rand(4,5))
sc.show(array)
(dims=('y', 'x'), shape=(4, 5), unit=dimensionless, variances=True)variances yxvalues yx yy(dims=('y',), shape=(4,), unit=m, variances=False)values y xx(dims=('x',), shape=(5,), unit=m, variances=False)values x

We create a dataset:

[7]:
dataset = sc.Dataset(
    data={'a': var},
    coords={'x': x, 'y': y, 'aux': x})
dataset['b'] = array
dataset['scalar'] = 1.23 * (sc.units.m / sc.units.s)
sc.show(dataset)
aa(dims=('y', 'x'), shape=(4, 5), unit=dimensionless, variances=True)variances yxvalues yx bb(dims=('y', 'x'), shape=(4, 5), unit=dimensionless, variances=True)variances yxvalues yx yy(dims=('y',), shape=(4,), unit=m, variances=False)values y scala..scalar(dims=(), shape=(), unit=m/s, variances=False)values auxaux(dims=('x',), shape=(5,), unit=m, variances=False)values x xx(dims=('x',), shape=(5,), unit=m, variances=False)values x

We can slice variables, data arrays, and datasets using a dimension label and an index or a slice object like i:j:

[8]:
dataset['c'] = dataset['b']['x', 2]
sc.show(dataset)
dataset
aa(dims=('y', 'x'), shape=(4, 5), unit=dimensionless, variances=True)variances yxvalues yx bb(dims=('y', 'x'), shape=(4, 5), unit=dimensionless, variances=True)variances yxvalues yx yy(dims=('y',), shape=(4,), unit=m, variances=False)values y cc(dims=('y',), shape=(4,), unit=dimensionless, variances=True)variances yvalues y scala..scalar(dims=(), shape=(), unit=m/s, variances=False)values auxaux(dims=('x',), shape=(5,), unit=m, variances=False)values x xx(dims=('x',), shape=(5,), unit=m, variances=False)values x
[8]:
Show/Hide data repr Show/Hide attributes
scipp.Dataset (5.28 KB out of 5.59 KB)
    • y: 4
    • x: 5
    • aux
      (x)
      int64
      m
      0, 1, 2, 3, 4
      Values:
      array([0, 1, 2, 3, 4])
    • x
      (x)
      int64
      m
      0, 1, 2, 3, 4
      Values:
      array([0, 1, 2, 3, 4])
    • y
      (y)
      int64
      m
      0, 1, 2, 3
      Values:
      array([0, 1, 2, 3])
    • a
      (y, x)
      float64
      𝟙
      0.510, 0.188, ..., 0.861, 0.984
      σ = 0.182, 0.039, ..., 0.776, 0.108
      Values:
      array([[0.51016585, 0.18827322, 0.13085134, 0.96372934, 0.0744567 ], [0.06814973, 0.26388695, 0.05553468, 0.34085846, 0.03323121], [0.49310144, 0.78119323, 0.05417718, 0.83678959, 0.15066982], [0.01105393, 0.31648451, 0.16625937, 0.86061993, 0.98386346]])

      Variances (σ²):
      array([[0.03322328, 0.00152718, 0.93774077, 0.72826363, 0.7674642 ], [0.85846255, 0.88429851, 0.05141708, 0.62562601, 0.55610772], [0.00238002, 0.0067437 , 0.45731416, 0.25835922, 0.09569072], [0.14082989, 0.08947239, 0.28615094, 0.60213375, 0.01172063]])
    • b
      (y, x)
      float64
      𝟙
      0.510, 0.188, ..., 0.861, 0.984
      σ = 0.182, 0.039, ..., 0.776, 0.108
      Values:
      array([[0.51016585, 0.18827322, 0.13085134, 0.96372934, 0.0744567 ], [0.06814973, 0.26388695, 0.05553468, 0.34085846, 0.03323121], [0.49310144, 0.78119323, 0.05417718, 0.83678959, 0.15066982], [0.01105393, 0.31648451, 0.16625937, 0.86061993, 0.98386346]])

      Variances (σ²):
      array([[0.03322328, 0.00152718, 0.93774077, 0.72826363, 0.7674642 ], [0.85846255, 0.88429851, 0.05141708, 0.62562601, 0.55610772], [0.00238002, 0.0067437 , 0.45731416, 0.25835922, 0.09569072], [0.14082989, 0.08947239, 0.28615094, 0.60213375, 0.01172063]])
    • c
      (y)
      float64
      𝟙
      0.131, 0.056, 0.054, 0.166
      σ = 0.968, 0.227, 0.676, 0.535
        • aux
          ()
          int64
          m
          2
          Values:
          array(2)
        • x
          ()
          int64
          m
          2
          Values:
          array(2)
      Values:
      array([0.13085134, 0.05553468, 0.05417718, 0.16625937])

      Variances (σ²):
      array([0.93774077, 0.05141708, 0.45731416, 0.28615094])
    • scalar
      ()
      float64
      m/s
      1.23
      Values:
      array(1.23)

We can also generate table representations (only 0-D and 1-D) and plots:

[9]:
sc.table(dataset['y', 2])
[9]:
ab
CoordinatesDataData
aux [m]x [m] [𝟙] [𝟙]
000.493±0.0490.493±0.049
110.781±0.0820.781±0.082
220.054±0.6760.054±0.676
330.837±0.5080.837±0.508
440.151±0.3090.151±0.309
[10]:
sc.plot(dataset['a'])
[10]:
../_images/getting-started_quick-start_17_0.svg

Arithmetic operations can be combined with slicing and handle propagation of uncertainties and units:

[11]:
print(dataset)
<scipp.Dataset>
Dimensions: Sizes[y:4, x:5, ]
Coordinates:
  aux                         int64              [m]  (x)  [0, 1, ..., 3, 4]
  x                           int64              [m]  (x)  [0, 1, ..., 3, 4]
  y                           int64              [m]  (y)  [0, 1, 2, 3]
Data:
  a                         float64  [dimensionless]  (y, x)  [0.510166, 0.188273, ..., 0.86062, 0.983863]  [0.0332233, 0.00152718, ..., 0.602134, 0.0117206]
  b                         float64  [dimensionless]  (y, x)  [0.510166, 0.188273, ..., 0.86062, 0.983863]  [0.0332233, 0.00152718, ..., 0.602134, 0.0117206]
  c                         float64  [dimensionless]  (y)  [0.130851, 0.0555347, 0.0541772, 0.166259]  [0.937741, 0.0514171, 0.457314, 0.286151]
    Attributes:
        aux                         int64              [m]  ()  [2]
        x                           int64              [m]  ()  [2]
  scalar                    float64            [m/s]  ()  [1.23]


[12]:
dataset['b']['y', 0:2] -= dataset['y', 0:2]['a']['x', 0]
dataset['b'] *= dataset['scalar']
print(dataset)
<scipp.Dataset>
Dimensions: Sizes[y:4, x:5, ]
Coordinates:
  aux                         int64              [m]  (x)  [0, 1, ..., 3, 4]
  x                           int64              [m]  (x)  [0, 1, ..., 3, 4]
  y                           int64              [m]  (y)  [0, 1, 2, 3]
Data:
  a                         float64            [m/s]  (y, x)  [0, -0.395928, ..., 1.05856, 1.21015]  [0.100527, 0.052574, ..., 0.910968, 0.0177321]
  b                         float64            [m/s]  (y, x)  [0, -0.395928, ..., 1.05856, 1.21015]  [0.100527, 0.052574, ..., 0.910968, 0.0177321]
  c                         float64            [m/s]  (y)  [-0.466557, -0.0155165, 0.0666379, 0.204499]  [1.46897, 1.37656, 0.691871, 0.432918]
    Attributes:
        aux                         int64              [m]  ()  [2]
        x                           int64              [m]  ()  [2]
  scalar                    float64            [m/s]  ()  [1.23]


Finally, type the imported name of the Scipp module at the end of a cell for a list of all current Scipp objects (variables, data arrays, datasets). Click on entries to expand nested sections:

[13]:
sc
Variables:(3)
var
Show/Hide data repr Show/Hide attributes
scipp.Variable (576 Bytes)
    • (y: 4, x: 5)
      float64
      m/s
      0.0, -0.396, ..., 1.059, 1.210
      σ = 0.317, 0.229, ..., 0.954, 0.133
      Values:
      array([[ 0. , -0.39592794, -0.46655685, 0.55788309, -0.53592226], [ 0. , 0.24075678, -0.01551651, 0.33543174, -0.04294979], [ 0.60651478, 0.96086767, 0.06663793, 1.02925119, 0.18532387], [ 0.01359633, 0.38927594, 0.20449903, 1.05856251, 1.21015206]])

      Variances (σ²):
      array([[0.10052701, 0.05257398, 1.46897151, 1.15205355, 1.21136009], [2.59753598, 2.63662321, 1.37655689, 2.24527758, 2.14010336], [0.00360072, 0.01020254, 0.6918706 , 0.39087167, 0.14477049], [0.21306154, 0.13536277, 0.43291776, 0.91096815, 0.01773214]])
x
Show/Hide data repr Show/Hide attributes
scipp.Variable (296 Bytes)
    • (x: 5)
      int64
      m
      0, 1, 2, 3, 4
      Values:
      array([0, 1, 2, 3, 4])
y
Show/Hide data repr Show/Hide attributes
scipp.Variable (288 Bytes)
    • (y: 4)
      int64
      m
      0, 1, 2, 3
      Values:
      array([0, 1, 2, 3])
DataArrays:(1)
array
Show/Hide data repr Show/Hide attributes
scipp.DataArray (1.63 KB)
    • y: 4
    • x: 5
    • x
      (x)
      int64
      m
      0, 1, 2, 3, 4
      Values:
      array([0, 1, 2, 3, 4])
    • y
      (y)
      int64
      m
      0, 1, 2, 3
      Values:
      array([0, 1, 2, 3])
    • (y, x)
      float64
      m/s
      0.0, -0.396, ..., 1.059, 1.210
      σ = 0.317, 0.229, ..., 0.954, 0.133
      Values:
      array([[ 0. , -0.39592794, -0.46655685, 0.55788309, -0.53592226], [ 0. , 0.24075678, -0.01551651, 0.33543174, -0.04294979], [ 0.60651478, 0.96086767, 0.06663793, 1.02925119, 0.18532387], [ 0.01359633, 0.38927594, 0.20449903, 1.05856251, 1.21015206]])

      Variances (σ²):
      array([[0.10052701, 0.05257398, 1.46897151, 1.15205355, 1.21136009], [2.59753598, 2.63662321, 1.37655689, 2.24527758, 2.14010336], [0.00360072, 0.01020254, 0.6918706 , 0.39087167, 0.14477049], [0.21306154, 0.13536277, 0.43291776, 0.91096815, 0.01773214]])
Datasets:(1)
dataset
Show/Hide data repr Show/Hide attributes
scipp.Dataset (5.28 KB out of 5.59 KB)
    • y: 4
    • x: 5
    • aux
      (x)
      int64
      m
      0, 1, 2, 3, 4
      Values:
      array([0, 1, 2, 3, 4])
    • x
      (x)
      int64
      m
      0, 1, 2, 3, 4
      Values:
      array([0, 1, 2, 3, 4])
    • y
      (y)
      int64
      m
      0, 1, 2, 3
      Values:
      array([0, 1, 2, 3])
    • a
      (y, x)
      float64
      m/s
      0.0, -0.396, ..., 1.059, 1.210
      σ = 0.317, 0.229, ..., 0.954, 0.133
      Values:
      array([[ 0. , -0.39592794, -0.46655685, 0.55788309, -0.53592226], [ 0. , 0.24075678, -0.01551651, 0.33543174, -0.04294979], [ 0.60651478, 0.96086767, 0.06663793, 1.02925119, 0.18532387], [ 0.01359633, 0.38927594, 0.20449903, 1.05856251, 1.21015206]])

      Variances (σ²):
      array([[0.10052701, 0.05257398, 1.46897151, 1.15205355, 1.21136009], [2.59753598, 2.63662321, 1.37655689, 2.24527758, 2.14010336], [0.00360072, 0.01020254, 0.6918706 , 0.39087167, 0.14477049], [0.21306154, 0.13536277, 0.43291776, 0.91096815, 0.01773214]])
    • b
      (y, x)
      float64
      m/s
      0.0, -0.396, ..., 1.059, 1.210
      σ = 0.317, 0.229, ..., 0.954, 0.133
      Values:
      array([[ 0. , -0.39592794, -0.46655685, 0.55788309, -0.53592226], [ 0. , 0.24075678, -0.01551651, 0.33543174, -0.04294979], [ 0.60651478, 0.96086767, 0.06663793, 1.02925119, 0.18532387], [ 0.01359633, 0.38927594, 0.20449903, 1.05856251, 1.21015206]])

      Variances (σ²):
      array([[0.10052701, 0.05257398, 1.46897151, 1.15205355, 1.21136009], [2.59753598, 2.63662321, 1.37655689, 2.24527758, 2.14010336], [0.00360072, 0.01020254, 0.6918706 , 0.39087167, 0.14477049], [0.21306154, 0.13536277, 0.43291776, 0.91096815, 0.01773214]])
    • c
      (y)
      float64
      m/s
      -0.467, -0.016, 0.067, 0.204
      σ = 1.212, 1.173, 0.832, 0.658
        • aux
          ()
          int64
          m
          2
          Values:
          array(2)
        • x
          ()
          int64
          m
          2
          Values:
          array(2)
      Values:
      array([-0.46655685, -0.01551651, 0.06663793, 0.20449903])

      Variances (σ²):
      array([1.46897151, 1.37655689, 0.6918706 , 0.43291776])
    • scalar
      ()
      float64
      m/s
      1.23
      Values:
      array(1.23)
[13]:
<module 'scipp' from '/home/runner/work/scipp/scipp/.tox/docs/lib/python3.8/site-packages/scipp/__init__.py'>