0
# Array Creation
1
2
Functions for creating arrays, scalars, vectors, and structured data with comprehensive support for physical units, dimensions, and uncertainty propagation. These functions provide the building blocks for all scipp data structures.
3
4
## Capabilities
5
6
### Basic Array Creation
7
8
Create arrays from data with explicit dimension labels, units, and optional variance information.
9
10
```python { .api }
11
def array(dims, values, *, variances=None, unit=None, dtype=None):
12
"""
13
Create a Variable from array-like data
14
15
Args:
16
dims (str or Sequence[str]): Dimension labels
17
values (array-like): Data values
18
variances (array-like, optional): Variance values for uncertainty
19
unit (Unit or str, optional): Physical unit
20
dtype (DType or str, optional): Data type override
21
22
Returns:
23
Variable: New variable with specified data
24
"""
25
26
def scalar(value, *, variance=None, unit=None, dtype=None):
27
"""
28
Create a zero-dimensional Variable (scalar)
29
30
Args:
31
value: Scalar value
32
variance (optional): Scalar variance for uncertainty
33
unit (Unit or str, optional): Physical unit
34
dtype (DType or str, optional): Data type override
35
36
Returns:
37
Variable: Zero-dimensional variable
38
"""
39
40
def index(value):
41
"""
42
Create an integer index scalar
43
44
Args:
45
value (int): Index value
46
47
Returns:
48
Variable: Integer scalar variable
49
"""
50
```
51
52
### Filled Array Creation
53
54
Create arrays filled with specific values (zeros, ones, or custom values) with specified shapes and dimensions.
55
56
```python { .api }
57
def zeros(dims, shape, *, unit=None, dtype=None):
58
"""
59
Create array filled with zeros
60
61
Args:
62
dims (str or Sequence[str]): Dimension labels
63
shape (int or Sequence[int]): Shape along each dimension
64
unit (Unit or str, optional): Physical unit
65
dtype (DType or str, optional): Data type
66
67
Returns:
68
Variable: Array filled with zeros
69
"""
70
71
def ones(dims, shape, *, unit=None, dtype=None):
72
"""
73
Create array filled with ones
74
75
Args:
76
dims (str or Sequence[str]): Dimension labels
77
shape (int or Sequence[int]): Shape along each dimension
78
unit (Unit or str, optional): Physical unit
79
dtype (DType or str, optional): Data type
80
81
Returns:
82
Variable: Array filled with ones
83
"""
84
85
def empty(dims, shape, *, unit=None, dtype=None):
86
"""
87
Create uninitialized array
88
89
Args:
90
dims (str or Sequence[str]): Dimension labels
91
shape (int or Sequence[int]): Shape along each dimension
92
unit (Unit or str, optional): Physical unit
93
dtype (DType or str, optional): Data type
94
95
Returns:
96
Variable: Uninitialized array
97
"""
98
99
def full(dims, shape, value, *, unit=None, dtype=None):
100
"""
101
Create array filled with specified value
102
103
Args:
104
dims (str or Sequence[str]): Dimension labels
105
shape (int or Sequence[int]): Shape along each dimension
106
value: Fill value
107
unit (Unit or str, optional): Physical unit
108
dtype (DType or str, optional): Data type
109
110
Returns:
111
Variable: Array filled with value
112
"""
113
```
114
115
### Template-Based Creation
116
117
Create arrays with the same shape and structure as existing variables.
118
119
```python { .api }
120
def zeros_like(x):
121
"""
122
Create zeros array with same shape as input
123
124
Args:
125
x (Variable or DataArray): Template variable
126
127
Returns:
128
Variable: Zeros array with same shape and dimensions
129
"""
130
131
def ones_like(x):
132
"""
133
Create ones array with same shape as input
134
135
Args:
136
x (Variable or DataArray): Template variable
137
138
Returns:
139
Variable: Ones array with same shape and dimensions
140
"""
141
142
def empty_like(x):
143
"""
144
Create uninitialized array with same shape as input
145
146
Args:
147
x (Variable or DataArray): Template variable
148
149
Returns:
150
Variable: Uninitialized array with same shape and dimensions
151
"""
152
153
def full_like(x, value):
154
"""
155
Create filled array with same shape as input
156
157
Args:
158
x (Variable or DataArray): Template variable
159
value: Fill value
160
161
Returns:
162
Variable: Filled array with same shape and dimensions
163
"""
164
```
165
166
### Range and Sequence Creation
167
168
Generate sequences and ranges with specified spacing and physical units.
169
170
```python { .api }
171
def linspace(dim, start, stop, num, *, unit=None, dtype=None, endpoint=True):
172
"""
173
Create linearly spaced values
174
175
Args:
176
dim (str): Dimension label
177
start: Start value
178
stop: Stop value
179
num (int): Number of values
180
unit (Unit or str, optional): Physical unit
181
dtype (DType or str, optional): Data type
182
endpoint (bool): Include stop value
183
184
Returns:
185
Variable: Linearly spaced values
186
"""
187
188
def geomspace(dim, start, stop, num, *, unit=None, dtype=None, endpoint=True):
189
"""
190
Create geometrically spaced values
191
192
Args:
193
dim (str): Dimension label
194
start: Start value (must be positive)
195
stop: Stop value (must be positive)
196
num (int): Number of values
197
unit (Unit or str, optional): Physical unit
198
dtype (DType or str, optional): Data type
199
endpoint (bool): Include stop value
200
201
Returns:
202
Variable: Geometrically spaced values
203
"""
204
205
def logspace(dim, start, stop, num, *, base=10.0, unit=None, dtype=None, endpoint=True):
206
"""
207
Create logarithmically spaced values
208
209
Args:
210
dim (str): Dimension label
211
start: Start exponent
212
stop: Stop exponent
213
num (int): Number of values
214
base (float): Base of logarithm
215
unit (Unit or str, optional): Physical unit
216
dtype (DType or str, optional): Data type
217
endpoint (bool): Include stop value
218
219
Returns:
220
Variable: Logarithmically spaced values
221
"""
222
223
def arange(dim, start, stop=None, step=None, *, unit=None, dtype=None):
224
"""
225
Create range with specified step
226
227
Args:
228
dim (str): Dimension label
229
start: Start value (or stop if stop is None)
230
stop (optional): Stop value
231
step (optional): Step size
232
unit (Unit or str, optional): Physical unit
233
dtype (DType or str, optional): Data type
234
235
Returns:
236
Variable: Range of values
237
"""
238
```
239
240
### Vector and Matrix Creation
241
242
Create specialized data types for 3D vectors and transformation matrices.
243
244
```python { .api }
245
def vector(value, *, unit=None):
246
"""
247
Create a scalar 3D vector variable
248
249
Args:
250
value (array-like): 3-element vector [x, y, z]
251
unit (Unit or str, optional): Physical unit
252
253
Returns:
254
Variable: Scalar variable with vector3 dtype
255
"""
256
257
def vectors(dims, values, *, unit=None):
258
"""
259
Create array of 3D vectors
260
261
Args:
262
dims (str or Sequence[str]): Dimension labels
263
values (array-like): Array of 3-element vectors
264
unit (Unit or str, optional): Physical unit
265
266
Returns:
267
Variable: Array variable with vector3 dtype
268
"""
269
```
270
271
### Time and Date Creation
272
273
Create datetime variables for time-series data with proper temporal units.
274
275
```python { .api }
276
def datetime(year=1970, month=1, day=1, hour=0, minute=0, second=0, *, unit='s'):
277
"""
278
Create datetime scalar
279
280
Args:
281
year (int): Year
282
month (int): Month
283
day (int): Day
284
hour (int): Hour
285
minute (int): Minute
286
second (int): Second
287
unit (str): Time unit
288
289
Returns:
290
Variable: Datetime scalar
291
"""
292
293
def datetimes(dims, values, *, unit='s'):
294
"""
295
Create array of datetimes
296
297
Args:
298
dims (str or Sequence[str]): Dimension labels
299
values (array-like): Datetime values
300
unit (str): Time unit
301
302
Returns:
303
Variable: Datetime array
304
"""
305
306
def epoch(*, unit='s'):
307
"""
308
Unix epoch time reference
309
310
Args:
311
unit (str): Time unit
312
313
Returns:
314
Variable: Unix epoch reference time
315
"""
316
```
317
318
## Usage Examples
319
320
### Creating Basic Arrays
321
322
```python
323
import scipp as sc
324
import numpy as np
325
326
# Create 1D array with units
327
data = sc.array(dims=['x'], values=[1, 2, 3, 4, 5], unit='m')
328
329
# Create 2D array with uncertainties
330
measurements = sc.array(
331
dims=['y', 'x'],
332
values=np.random.random((3, 5)),
333
variances=np.random.random((3, 5)) * 0.01,
334
unit='counts'
335
)
336
337
# Create scalar with uncertainty
338
reference = sc.scalar(value=1.23, variance=0.01, unit='kg')
339
```
340
341
### Creating Filled Arrays
342
343
```python
344
# Create zero-filled 2D array
345
zeros_2d = sc.zeros(dims=['y', 'x'], shape=[10, 20], unit='V')
346
347
# Create ones with specific data type
348
ones_int = sc.ones(dims=['time'], shape=[100], dtype='int32')
349
350
# Create array filled with specific value
351
baseline = sc.full(dims=['detector'], shape=[256], value=1.5, unit='counts')
352
```
353
354
### Creating Coordinate Arrays
355
356
```python
357
# Time coordinate with regular spacing
358
time = sc.linspace(dim='time', start=0, stop=10, num=101, unit='s')
359
360
# Energy coordinate with logarithmic spacing
361
energy = sc.geomspace(dim='energy', start=1e-3, stop=1e3, num=50, unit='eV')
362
363
# Detector positions as 3D vectors
364
positions = sc.vectors(
365
dims=['detector'],
366
values=np.random.random((100, 3)),
367
unit='m'
368
)
369
```
370
371
### Creating Time Series Data
372
373
```python
374
from datetime import datetime
375
376
# Create time stamps
377
start_time = sc.datetime(2023, 1, 1, 12, 0, 0, unit='s')
378
379
# Create time series with regular intervals
380
time_series = start_time + sc.arange(dim='time', start=0, stop=3600, step=60, unit='s')
381
382
# Create measurement data with time coordinate
383
temperature_data = sc.array(
384
dims=['time'],
385
values=20 + np.random.random(60) * 5,
386
unit='degC'
387
)
388
389
temperature_series = sc.DataArray(
390
data=temperature_data,
391
coords={'time': time_series}
392
)
393
```
394
395
### Working with Templates
396
397
```python
398
# Create template array
399
template = sc.zeros(dims=['y', 'x'], shape=[5, 10], unit='m')
400
401
# Create similar arrays
402
field_x = sc.ones_like(template) # Same shape, filled with ones
403
field_y = sc.full_like(template, -1.5) # Same shape, filled with -1.5
404
405
# Create uninitialized array for computation results
406
result = sc.empty_like(template)
407
```