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.306, 0.385, ..., 0.741, 0.773
      Values:
      array([[0.3056497 , 0.38499749, 0.28945265, 0.27097174, 0.3122865 ], [0.08737064, 0.71477773, 0.0032627 , 0.22678399, 0.08828314], [0.4803476 , 0.73943864, 0.53256805, 0.76781421, 0.86446501], [0.28404209, 0.7781545 , 0.27349941, 0.74124038, 0.77274038]])
[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.306, 0.385, ..., 0.741, 0.773
      Values:
      array([[0.3056497 , 0.38499749, 0.28945265, 0.27097174, 0.3122865 ], [0.08737064, 0.71477773, 0.0032627 , 0.22678399, 0.08828314], [0.4803476 , 0.73943864, 0.53256805, 0.76781421, 0.86446501], [0.28404209, 0.7781545 , 0.27349941, 0.74124038, 0.77274038]])

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.306, 0.385, ..., 0.741, 0.773
      σ = 0.269, 0.037, ..., 0.475, 0.902
      Values:
      array([[0.3056497 , 0.38499749, 0.28945265, 0.27097174, 0.3122865 ], [0.08737064, 0.71477773, 0.0032627 , 0.22678399, 0.08828314], [0.4803476 , 0.73943864, 0.53256805, 0.76781421, 0.86446501], [0.28404209, 0.7781545 , 0.27349941, 0.74124038, 0.77274038]])

      Variances (σ²):
      array([[7.21478395e-02, 1.39698023e-03, 9.49920088e-02, 2.15991929e-01, 7.34821668e-01], [5.75967409e-03, 1.37710085e-01, 5.58365934e-01, 3.81241935e-01, 8.38396969e-01], [3.84343801e-01, 8.33828965e-01, 5.99326029e-01, 3.48084571e-01, 8.33994101e-01], [7.71400030e-02, 7.47606787e-04, 1.52643060e-01, 2.25421432e-01, 8.13443192e-01]])
    • b
      (y, x)
      float64
      𝟙
      0.306, 0.385, ..., 0.741, 0.773
      σ = 0.269, 0.037, ..., 0.475, 0.902
      Values:
      array([[0.3056497 , 0.38499749, 0.28945265, 0.27097174, 0.3122865 ], [0.08737064, 0.71477773, 0.0032627 , 0.22678399, 0.08828314], [0.4803476 , 0.73943864, 0.53256805, 0.76781421, 0.86446501], [0.28404209, 0.7781545 , 0.27349941, 0.74124038, 0.77274038]])

      Variances (σ²):
      array([[7.21478395e-02, 1.39698023e-03, 9.49920088e-02, 2.15991929e-01, 7.34821668e-01], [5.75967409e-03, 1.37710085e-01, 5.58365934e-01, 3.81241935e-01, 8.38396969e-01], [3.84343801e-01, 8.33828965e-01, 5.99326029e-01, 3.48084571e-01, 8.33994101e-01], [7.71400030e-02, 7.47606787e-04, 1.52643060e-01, 2.25421432e-01, 8.13443192e-01]])
    • c
      (y)
      float64
      𝟙
      0.289, 0.003, 0.533, 0.273
      σ = 0.308, 0.747, 0.774, 0.391
        • aux
          ()
          int64
          m
          2
          Values:
          array(2)
        • x
          ()
          int64
          m
          2
          Values:
          array(2)
      Values:
      array([0.28945265, 0.0032627 , 0.53256805, 0.27349941])

      Variances (σ²):
      array([0.09499201, 0.55836593, 0.59932603, 0.15264306])
    • 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.480±0.6200.480±0.620
110.739±0.9130.739±0.913
220.533±0.7740.533±0.774
330.768±0.5900.768±0.590
440.864±0.9130.864±0.913
[10]:
sc.plot(dataset)
[10]:

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.30565, 0.384997, ..., 0.74124, 0.77274]  [0.0721478, 0.00139698, ..., 0.225421, 0.813443]
  b                         float64  [dimensionless]  (y, x)  [0.30565, 0.384997, ..., 0.74124, 0.77274]  [0.0721478, 0.00139698, ..., 0.225421, 0.813443]
  c                         float64  [dimensionless]  (y)  [0.289453, 0.0032627, 0.532568, 0.273499]  [0.094992, 0.558366, 0.599326, 0.152643]
    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.0975978, ..., 0.911726, 0.950471]  [0.218305, 0.111266, ..., 0.34104, 1.23066]
  b                         float64            [m/s]  (y, x)  [0, 0.0975978, ..., 0.911726, 0.950471]  [0.218305, 0.111266, ..., 0.34104, 1.23066]
  c                         float64            [m/s]  (y)  [-0.0199224, -0.103453, 0.655059, 0.336404]  [0.252866, 0.853466, 0.90672, 0.230934]
    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.098, ..., 0.912, 0.950
      σ = 0.467, 0.334, ..., 0.584, 1.109
      Values:
      array([[ 0. , 0.09759778, -0.01992237, -0.04265389, 0.00816326], [ 0. , 0.77171072, -0.10345276, 0.17147843, 0.00112238], [ 0.59082755, 0.90950953, 0.65505871, 0.94441147, 1.06329196], [ 0.34937177, 0.95713004, 0.33640427, 0.91172567, 0.95047067]])

      Variances (σ²):
      array([[2.18304933e-01, 1.11265958e-01, 2.52865877e-01, 4.35926655e-01, 1.22086417e+00], [1.74276219e-02, 2.17055399e-01, 8.53465632e-01, 5.85494735e-01, 1.27712459e+00], [5.81473737e-01, 1.26149984e+00, 9.06720349e-01, 5.26617148e-01, 1.26174968e+00], [1.16705110e-01, 1.13105431e-03, 2.30933686e-01, 3.41040085e-01, 1.23065821e+00]])
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.098, ..., 0.912, 0.950
      σ = 0.467, 0.334, ..., 0.584, 1.109
      Values:
      array([[ 0. , 0.09759778, -0.01992237, -0.04265389, 0.00816326], [ 0. , 0.77171072, -0.10345276, 0.17147843, 0.00112238], [ 0.59082755, 0.90950953, 0.65505871, 0.94441147, 1.06329196], [ 0.34937177, 0.95713004, 0.33640427, 0.91172567, 0.95047067]])

      Variances (σ²):
      array([[2.18304933e-01, 1.11265958e-01, 2.52865877e-01, 4.35926655e-01, 1.22086417e+00], [1.74276219e-02, 2.17055399e-01, 8.53465632e-01, 5.85494735e-01, 1.27712459e+00], [5.81473737e-01, 1.26149984e+00, 9.06720349e-01, 5.26617148e-01, 1.26174968e+00], [1.16705110e-01, 1.13105431e-03, 2.30933686e-01, 3.41040085e-01, 1.23065821e+00]])
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.098, ..., 0.912, 0.950
      σ = 0.467, 0.334, ..., 0.584, 1.109
      Values:
      array([[ 0. , 0.09759778, -0.01992237, -0.04265389, 0.00816326], [ 0. , 0.77171072, -0.10345276, 0.17147843, 0.00112238], [ 0.59082755, 0.90950953, 0.65505871, 0.94441147, 1.06329196], [ 0.34937177, 0.95713004, 0.33640427, 0.91172567, 0.95047067]])

      Variances (σ²):
      array([[2.18304933e-01, 1.11265958e-01, 2.52865877e-01, 4.35926655e-01, 1.22086417e+00], [1.74276219e-02, 2.17055399e-01, 8.53465632e-01, 5.85494735e-01, 1.27712459e+00], [5.81473737e-01, 1.26149984e+00, 9.06720349e-01, 5.26617148e-01, 1.26174968e+00], [1.16705110e-01, 1.13105431e-03, 2.30933686e-01, 3.41040085e-01, 1.23065821e+00]])
    • b
      (y, x)
      float64
      m/s
      0.0, 0.098, ..., 0.912, 0.950
      σ = 0.467, 0.334, ..., 0.584, 1.109
      Values:
      array([[ 0. , 0.09759778, -0.01992237, -0.04265389, 0.00816326], [ 0. , 0.77171072, -0.10345276, 0.17147843, 0.00112238], [ 0.59082755, 0.90950953, 0.65505871, 0.94441147, 1.06329196], [ 0.34937177, 0.95713004, 0.33640427, 0.91172567, 0.95047067]])

      Variances (σ²):
      array([[2.18304933e-01, 1.11265958e-01, 2.52865877e-01, 4.35926655e-01, 1.22086417e+00], [1.74276219e-02, 2.17055399e-01, 8.53465632e-01, 5.85494735e-01, 1.27712459e+00], [5.81473737e-01, 1.26149984e+00, 9.06720349e-01, 5.26617148e-01, 1.26174968e+00], [1.16705110e-01, 1.13105431e-03, 2.30933686e-01, 3.41040085e-01, 1.23065821e+00]])
    • c
      (y)
      float64
      m/s
      -0.020, -0.103, 0.655, 0.336
      σ = 0.503, 0.924, 0.952, 0.481
        • aux
          ()
          int64
          m
          2
          Values:
          array(2)
        • x
          ()
          int64
          m
          2
          Values:
          array(2)
      Values:
      array([-0.01992237, -0.10345276, 0.65505871, 0.33640427])

      Variances (σ²):
      array([0.25286588, 0.85346563, 0.90672035, 0.23093369])
    • 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'>