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]:
rng = np.random.default_rng(12345)
var = sc.array(dims=['y', 'x'], values=rng.random((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 representation:

[3]:
var
[3]:
Show/Hide data repr Show/Hide attributes
scipp.Variable (416 Bytes)
    • (y: 4, x: 5)
      float64
      𝟙
      0.227, 0.317, ..., 0.734, 0.220
      Values:
      array([[0.22733602, 0.31675834, 0.79736546, 0.67625467, 0.39110955], [0.33281393, 0.59830875, 0.18673419, 0.67275604, 0.94180287], [0.24824571, 0.94888115, 0.66723745, 0.09589794, 0.44183967], [0.88647992, 0.6974535 , 0.32647286, 0.73392816, 0.22013496]])
[4]:
x = sc.arange('x', 5, unit='m')
y = sc.arange('y', 4, unit='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.227, 0.317, ..., 0.734, 0.220
      Values:
      array([[0.22733602, 0.31675834, 0.79736546, 0.67625467, 0.39110955], [0.33281393, 0.59830875, 0.18673419, 0.67275604, 0.94180287], [0.24824571, 0.94888115, 0.66723745, 0.09589794, 0.44183967], [0.88647992, 0.6974535 , 0.32647286, 0.73392816, 0.22013496]])

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

[6]:
array = array.copy()
array.variances = np.square(rng.random((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.Unit('m/s')
sc.show(dataset)
aa(dims=('y', 'x'), shape=(4, 5), unit=dimensionless, variances=False)values 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=False)values 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.12 KB out of 5.44 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.227, 0.317, ..., 0.734, 0.220
      Values:
      array([[0.22733602, 0.31675834, 0.79736546, 0.67625467, 0.39110955], [0.33281393, 0.59830875, 0.18673419, 0.67275604, 0.94180287], [0.24824571, 0.94888115, 0.66723745, 0.09589794, 0.44183967], [0.88647992, 0.6974535 , 0.32647286, 0.73392816, 0.22013496]])
    • b
      (y, x)
      float64
      𝟙
      0.227, 0.317, ..., 0.734, 0.220
      σ = 0.082, 0.160, ..., 0.495, 0.274
      Values:
      array([[0.22733602, 0.31675834, 0.79736546, 0.67625467, 0.39110955], [0.33281393, 0.59830875, 0.18673419, 0.67275604, 0.94180287], [0.24824571, 0.94888115, 0.66723745, 0.09589794, 0.44183967], [0.88647992, 0.6974535 , 0.32647286, 0.73392816, 0.22013496]])

      Variances (σ²):
      array([[0.00665767, 0.0255666 , 0.11566814, 0.21640467, 0.07098016], [0.66549114, 0.03736272, 0.01676224, 0.00840243, 0.35828367], [0.73058372, 0.36194812, 0.86860231, 0.52530802, 0.74054857], [0.86366875, 0.29831916, 0.87923058, 0.24501306, 0.07495176]])
    • c
      (y)
      float64
      𝟙
      0.797, 0.187, 0.667, 0.326
      σ = 0.340, 0.129, 0.932, 0.938
        • aux
          ()
          int64
          m
          2
          Values:
          array(2)
        • x
          ()
          int64
          m
          2
          Values:
          array(2)
      Values:
      array([0.79736546, 0.18673419, 0.66723745, 0.32647286])

      Variances (σ²):
      array([0.11566814, 0.01676224, 0.86860231, 0.87923058])
    • 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.2480.248±0.855
110.9490.949±0.602
220.6670.667±0.932
330.0960.096±0.725
440.4420.442±0.861
[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.227336, 0.316758, ..., 0.733928, 0.220135]
  b                         float64  [dimensionless]  (y, x)  [0.227336, 0.316758, ..., 0.733928, 0.220135]  [0.00665767, 0.0255666, ..., 0.245013, 0.0749518]
  c                         float64  [dimensionless]  (y)  [0.797365, 0.186734, 0.667237, 0.326473]  [0.115668, 0.0167622, 0.868602, 0.879231]
    Attributes:
        aux                         int64              [m]  ()  [2]
        x                           int64              [m]  ()  [2]
  scalar                    float64            [m/s]  ()  [1.23]


[12]:
dataset['a']['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  [dimensionless]  (y, x)  [0, 0.0894223, ..., 0.733928, 0.220135]
  b                         float64            [m/s]  (y, x)  [0.279623, 0.389613, ..., 0.902732, 0.270766]  [0.0100724, 0.0386797, ..., 0.37068, 0.113395]
  c                         float64            [m/s]  (y)  [0.98076, 0.229683, 0.820702, 0.401562]  [0.174994, 0.0253596, 1.31411, 1.33019]
    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 (416 Bytes)
    • (y: 4, x: 5)
      float64
      𝟙
      0.0, 0.089, ..., 0.734, 0.220
      Values:
      array([[ 0. , 0.08942232, 0.57002943, 0.44891865, 0.16377353], [ 0. , 0.26549483, -0.14607974, 0.33994212, 0.60898894], [ 0.24824571, 0.94888115, 0.66723745, 0.09589794, 0.44183967], [ 0.88647992, 0.6974535 , 0.32647286, 0.73392816, 0.22013496]])
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.280, 0.390, ..., 0.903, 0.271
      σ = 0.100, 0.197, ..., 0.609, 0.337
      Values:
      array([[0.27962331, 0.38961276, 0.98075951, 0.83179325, 0.48106475], [0.40936113, 0.73591977, 0.22968305, 0.82748993, 1.15841752], [0.30534223, 1.16712382, 0.82070207, 0.11795446, 0.54346279], [1.0903703 , 0.8578678 , 0.40156162, 0.90273164, 0.270766 ]])

      Variances (σ²):
      array([[0.01007239, 0.03867971, 0.17499432, 0.32739863, 0.10738589], [1.00682155, 0.05652606, 0.0253596 , 0.01271203, 0.54204736], [1.10530011, 0.54759131, 1.31410843, 0.79473851, 1.12037593], [1.30664445, 0.45132705, 1.33018794, 0.37068026, 0.11339451]])
Datasets:(1)
dataset
Show/Hide data repr Show/Hide attributes
scipp.Dataset (5.12 KB out of 5.44 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.0, 0.089, ..., 0.734, 0.220
      Values:
      array([[ 0. , 0.08942232, 0.57002943, 0.44891865, 0.16377353], [ 0. , 0.26549483, -0.14607974, 0.33994212, 0.60898894], [ 0.24824571, 0.94888115, 0.66723745, 0.09589794, 0.44183967], [ 0.88647992, 0.6974535 , 0.32647286, 0.73392816, 0.22013496]])
    • b
      (y, x)
      float64
      m/s
      0.280, 0.390, ..., 0.903, 0.271
      σ = 0.100, 0.197, ..., 0.609, 0.337
      Values:
      array([[0.27962331, 0.38961276, 0.98075951, 0.83179325, 0.48106475], [0.40936113, 0.73591977, 0.22968305, 0.82748993, 1.15841752], [0.30534223, 1.16712382, 0.82070207, 0.11795446, 0.54346279], [1.0903703 , 0.8578678 , 0.40156162, 0.90273164, 0.270766 ]])

      Variances (σ²):
      array([[0.01007239, 0.03867971, 0.17499432, 0.32739863, 0.10738589], [1.00682155, 0.05652606, 0.0253596 , 0.01271203, 0.54204736], [1.10530011, 0.54759131, 1.31410843, 0.79473851, 1.12037593], [1.30664445, 0.45132705, 1.33018794, 0.37068026, 0.11339451]])
    • c
      (y)
      float64
      m/s
      0.981, 0.230, 0.821, 0.402
      σ = 0.418, 0.159, 1.146, 1.153
        • aux
          ()
          int64
          m
          2
          Values:
          array(2)
        • x
          ()
          int64
          m
          2
          Values:
          array(2)
      Values:
      array([0.98075951, 0.22968305, 0.82070207, 0.40156162])

      Variances (σ²):
      array([0.17499432, 0.0253596 , 1.31410843, 1.33018794])
    • 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'>