Debian Codegraph @

doc/source/xraytomo.rst

raw
1 .. role:: math(raw)
2 :format: html latex
3
4 ================
5 X-ray Tomography
6 ================
7
8 This section describes extensions and additions to the core Data
9 Exchange format for X-ray Tomography. We begin with the extensions to
10 the exchange and instrument groups, and then describe the possible
11 tomography data collection schemes and corresponding data structures.
12
13 Top level (root)
14 ================
15
16 This node represents the top level of the HDF5 file and holds some
17 general information about the file.
18
19
20 +------------------------------+----------------------------+-----------------------------------------+
21 | Member | Type | Example |
22 +==============================+============================+=========================================+
23 | **implements** | string dataset | **exchange**:*measurement*:*process* |
24 +------------------------------+----------------------------+-----------------------------------------+
25 | **exchange** | group | |
26 +------------------------------+----------------------------+-----------------------------------------+
27 | *measurement* | group | |
28 +------------------------------+----------------------------+-----------------------------------------+
29 | *process* | group | |
30 +------------------------------+----------------------------+-----------------------------------------+
31
32 implements
33 |
34 | A colon separated list that shows which components are present in
35 the file. The only **mandatory** component is **exchange**. A more
36 general Data Exchange file also contains *measurement* and
37 *process* information, if so these will be declared in **implements**
38 as **exchange**:*measurement*:*process*
39
40 exchange or exchange_N
41 |
42 | The data taken from measurements or processing. Dimension
43 descriptors within the group may also serve to describe
44 “positioner” values involved in a scan.
45
46 measurement or measurement_N
47 |
48 | Description of the sample and instrument as configured for the
49 measurement. This group is appropriate for relatively static
50 metadata. For measurements where there are many “positioner”
51 values (aka a “scan”), it is more sensible to add dimension(s) to
52 the exchange dataset, and describe the “positioner” values as
53 dimension scales rather than record the data via multiple matching
54 *measurement* and **exchange** groups. This is a judgement left to
55 the user.
56
57 process
58 |
59 | The Process group describes all the "work" that has been done. This
60 includes data processing steps that have been applied to the data as
61 well as experimental steps (e.g. data collection strategy etc.)
62 and sample preparation ahead of the experiment and during the
63 measurement (e.g. environment conditions etc.).
64
65
66 **exchange**
67 ============
68
69 In X-ray tomography, the 3D arrays representing the most basic version
70 of the data include projections, dark, and white fields. It is
71 **mandatory** that there is at least one dataset named **data** in each
72 exchange group. Most data analysis and plotting programs will primarily
73 focus in this group.
74
75 +------------------+---------------------------------------------------------+-----------------------------+
76 | Member | Type | Example/Attributes |
77 +==================+=========================================================+=============================+
78 | *name* | string dataset | "absorption_tomography" |
79 +------------------+---------------------------------------------------------+-----------------------------+
80 | *description* | string dataset | "raw absorption tomo" |
81 +------------------+---------------------------------------------------------+-----------------------------+
82 | **data** | 3D dataset | axes: *theta:y:x* |
83 +------------------+---------------------------------------------------------+-----------------------------+
84 | *theta* | 1D dataset | units: "deg" |
85 +------------------+---------------------------------------------------------+-----------------------------+
86 | *data_dark* | 3D dataset | axes: *theta_dark:y:x* |
87 +------------------+---------------------------------------------------------+-----------------------------+
88 | *theta_dark* | 1D dataset | units: "deg" |
89 +------------------+---------------------------------------------------------+-----------------------------+
90 | *data_white* | 3D dataset | axes: *theta_white:y:x* |
91 +------------------+---------------------------------------------------------+-----------------------------+
92 | *theta_white* | 1D dataset | units: "deg" |
93 +------------------+---------------------------------------------------------+-----------------------------+
94 | *data_shift_x* | relative x shift of data at each angular position | |
95 +------------------+---------------------------------------------------------+-----------------------------+
96 | *data_shift_y* | relative y shift of data at each angular position | |
97 +------------------+---------------------------------------------------------+-----------------------------+
98
99 Table: Exchange Group Members for Tomography
100
101
102 name
103 |
104 | Descriptive *name* for **data** dataset. Current types include:
105 absorption_tomography, phase_tomography, dpc_tomography
106
107 description
108 |
109 | Description.
110
111 data
112 |
113 | A tomographic data set consists of a series of projections (**data**),
114 dark field (*data_dark*), and white field (*data_white*) images. The
115 dark and white fields must have the same projection image
116 dimensions and can be collected at any time before, after or
117 during the projection data collection. The angular position of the
118 tomographic rotation axis, theta, can be used to keep track of
119 when the dark and white images are collected. These datasets are
120 saved in 3D arrays using, by default, the natural HDF5 order of a
121 multidimensional array (rotation axis, ccd y, ccd x), i.e. with
122 the fastest changing dimension being the last dimension, and the
123 slowest changing dimension being the first dimension. If using the
124 default dimension order, the axes attribute *theta:y:x* can be
125 omitted. The attribute is **mandatory** if the 3D arrays use a
126 different axes order. This could be the case when, for example,
127 the arrays are optimized for sinogram read ( = *y:theta:x*). As no
128 units are specified the data is assumed to be in *counts* with the
129 axes (x, y) in pixels.
130
131 data_dark, data_white
132 |
133 | The dark field and white fields must have the same dimensions as
134 the projection images and can be collected at any time before,
135 during, or after the projection data collection. To specify where
136 dark and white images were taken, specify the axes attribute with
137 “theta_dark:y:x” and “theta_white:y:x” and provide *theta_dark*
138 and *theta_white* vector datasets that specify the rotation angles
139 where they were collected.
140
141 theta, theta dark, theta_white
142 |
143 | Theta is a vector dataset storing the projection angular
144 positions. If theta is not defined the projections are assumed to
145 be collected at equally spaced angular interval between 0 and 180
146 degree. The dark field and white fields can be collected at any
147 time before, during, or after the projection data. *theta_dark*,
148 and *theta_white* store the position of the tomographic rotation
149 axis when the corresponding dark and white images are collected.
150 If *theta_dark* and *theta_white* are missing the corresponding
151 *data_dark* and *data_white* are assumed to be collected all at the
152 beginning or at the end of the projection data collection.
153
154 data_shift_x, data_shift_y
155 |
156 | Data_shift_x and data_shift_y are the vectors storing at each
157 projection angular positions the image relative shift in x and y.
158 These vectors are used in high resolution CT when at each angular
159 position the sample x and y are moved to keep the sample in the
160 field of view based on a pre-calibration of rotary stage runout.
161 If the unit is not defined are assumed to be in pixels.
162
163 Attribute
164 ---------
165
166 Description and units can be added as attribute to any data, both array or values,
167 inside a data exchange file. If units is omitted default is SI.
168
169 +---------------+------------------------+------------------------+
170 | Member | Type | Example |
171 +===============+========================+========================+
172 | *description* | string attribute | “transmission” |
173 +---------------+------------------------+------------------------+
174 | *units* | string attribute | *counts* |
175 +---------------+------------------------+------------------------+
176
177 Table: data attributes
178
179 *measurement*
180 =============
181
182 This group holds sample and instrument information. These groups are
183 designed to hold relatively static data about the sample and instrument
184 configuration at the time of the measurement. Rapidly changing
185 *positioner* values (aka scan) are better represented in the exchange
186 group dataset.
187
188 +---------------+----------------------+------------------------+
189 | Member | Type | Example |
190 +===============+======================+========================+
191 | instrument_ | group | |
192 +---------------+----------------------+------------------------+
193 | sample_ | group | |
194 +---------------+----------------------+------------------------+
195
196 Table: Measurement Group Members
197
198 instrument
199 |
200 | The instrument used to collect this data.
201
202 sample
203 |
204 | The sample measured.
205
206
207 .. _instrument:
208
209 *instrument*
210 ------------
211
212 The instrument group stores all relevant beamline components status at
213 the beginning of a measurement. While all these fields are optional, if
214 you do intend to include them they should appear within this parentage
215 of groups.
216
217
218 +---------------------------------------------+-------------------------+-------------------------+
219 | Member | Type | Example |
220 +=============================================+=========================+=========================+
221 | *name* | string dataset | "XSD/32-ID/TXM" |
222 +---------------------------------------------+-------------------------+-------------------------+
223 | *description* | string dataset | "X-ray Microscope" |
224 +---------------------------------------------+-------------------------+-------------------------+
225 | attenuator_ | group | |
226 +---------------------------------------------+-------------------------+-------------------------+
227 | beam_monitor_ | group | |
228 +---------------------------------------------+-------------------------+-------------------------+
229 | beam_stop_ | group | |
230 +---------------------------------------------+-------------------------+-------------------------+
231 | bertrand_lens_ | group | |
232 +---------------------------------------------+-------------------------+-------------------------+
233 | condenser_ | group | |
234 +---------------------------------------------+-------------------------+-------------------------+
235 | crl_ | group | |
236 +---------------------------------------------+-------------------------+-------------------------+
237 | detection_system_ | group | |
238 +---------------------------------------------+-------------------------+-------------------------+
239 | detector_ | group | |
240 +---------------------------------------------+-------------------------+-------------------------+
241 | diffuser_ | group | |
242 +---------------------------------------------+-------------------------+-------------------------+
243 | flight_tube_ | group | |
244 +---------------------------------------------+-------------------------+-------------------------+
245 | interferometer_ | group | |
246 +---------------------------------------------+-------------------------+-------------------------+
247 | mirror_ | group | |
248 +---------------------------------------------+-------------------------+-------------------------+
249 | monochromator_ | group | |
250 +---------------------------------------------+-------------------------+-------------------------+
251 | pin_hole_ | group | |
252 +---------------------------------------------+-------------------------+-------------------------+
253 | samplee_ | group | |
254 +---------------------------------------------+-------------------------+-------------------------+
255 | shutter_ | group | |
256 +---------------------------------------------+-------------------------+-------------------------+
257 | source_ | group | |
258 +---------------------------------------------+-------------------------+-------------------------+
259 | slits_ | group | |
260 +---------------------------------------------+-------------------------+-------------------------+
261 | table_ | group | |
262 +---------------------------------------------+-------------------------+-------------------------+
263 | zone_plate_ | group | |
264 +---------------------------------------------+-------------------------+-------------------------+
265 | setup_ | group | |
266 +---------------------------------------------+-------------------------+-------------------------+
267
268 Table: Instrument Group for Tomography
269
270 name
271 |
272 | Name of the instrument.
273
274 source
275 |
276 | The source used by the instrument.
277
278 shutter
279 |
280 | The shutter(s) used by the instrument.
281
282 attenuator
283 |
284 | The attenuators that are part of the instrument.
285
286 monochromator
287 |
288 | The monochromator used by the instrument.
289
290 detector
291 |
292 | The detectors that compose the instrument.
293
294
295
296 .. _attenuator:
297
298 *attenuator*
299 ~~~~~~~~~~~~
300
301 This class describes the beamline attenuator(s) used during data
302 collection. If more than one attenuators are used they will be named as
303 attenuator_1, attenuator_2 etc.
304
305 +---------------------------+-------------------------+-------------------------------+
306 | Member | Type | Example |
307 +===========================+=========================+===============================+
308 | *name* | string dataset | “Filter Set 1" |
309 +---------------------------+-------------------------+-------------------------------+
310 | *description* | string dataset | “Al" |
311 +---------------------------+-------------------------+-------------------------------+
312 | *thickness* | float dataset | 1e-3 |
313 +---------------------------+-------------------------+-------------------------------+
314 | *transmission* | float dataset | unit-less |
315 +---------------------------+-------------------------+-------------------------------+
316 | geometry_ | group | |
317 +---------------------------+-------------------------+-------------------------------+
318 | setup_ | group | |
319 +---------------------------+-------------------------+-------------------------------+
320
321 Table: Attenuator Group Members
322
323
324 name
325 |
326 | Name.
327
328 description
329 |
330 | Description.
331
332 thickness
333 |
334 | Thickness of attenuator along beam direction.
335
336 attenuator_transmission
337 |
338 | The nominal amount of the beam that gets through (transmitted
339 | intensity)/(incident intensity).
340
341 description
342 |
343 | Type or composition of attenuator.
344
345 .. _beam_monitor:
346
347 *beam_monitor*
348 ~~~~~~~~~~~~~~
349
350 Class describing the beam monitor being used, if there is more than one append _##
351
352 +--------------------+-------------------------+-------------------------------+
353 | Member | Type | Example |
354 +====================+=========================+===============================+
355 | *name* | string dataset | “Beam Monitor" |
356 +--------------------+-------------------------+-------------------------------+
357 | *description* | string dataset | “optional” |
358 +--------------------+-------------------------+-------------------------------+
359 | geometry_ | group | |
360 +--------------------+-------------------------+-------------------------------+
361 | setup_ | group | |
362 +--------------------+-------------------------+-------------------------------+
363
364 Table: Beam Monitor Group Members
365
366 .. _beam_stop:
367
368 *beam_stop*
369 ~~~~~~~~~~~
370
371 Class describing the beam stop being used, if there is more than one append _##
372
373 +--------------------+-------------------------+-------------------------------+
374 | Member | Type | Example |
375 +====================+=========================+===============================+
376 | *name* | string dataset | “Beam Stop" |
377 +--------------------+-------------------------+-------------------------------+
378 | *description* | string dataset | “optional” |
379 +--------------------+-------------------------+-------------------------------+
380 | geometry_ | group | |
381 +--------------------+-------------------------+-------------------------------+
382 | setup_ | group | |
383 +--------------------+-------------------------+-------------------------------+
384
385 Table: Beam Stop Group Members
386
387 .. _bertrand_lens:
388
389 *bertrand_lens*
390 ~~~~~~~~~~~~~~~
391
392 Class describing the Bertrand lens being used, if there is more than one append _##
393
394 +--------------------+-------------------------+-------------------------------+
395 | Member | Type | Example |
396 +====================+=========================+===============================+
397 | *name* | string dataset | “Bertrand Lens" |
398 +--------------------+-------------------------+-------------------------------+
399 | *description* | string dataset | “optional” |
400 +--------------------+-------------------------+-------------------------------+
401 | geometry_ | group | |
402 +--------------------+-------------------------+-------------------------------+
403 | setup_ | group | |
404 +--------------------+-------------------------+-------------------------------+
405
406 Table: Bertrand Lens Group Members
407
408 .. _condenser:
409
410 *condenser*
411 ~~~~~~~~~~~
412
413 Class describing the condenser being used, if there is more than one append _##
414
415 +--------------------+-------------------------+-------------------------------+
416 | Member | Type | Example |
417 +====================+=========================+===============================+
418 | *name* | string dataset | “Condenser" |
419 +--------------------+-------------------------+-------------------------------+
420 | *description* | string dataset | “optional” |
421 +--------------------+-------------------------+-------------------------------+
422 | geometry_ | group | |
423 +--------------------+-------------------------+-------------------------------+
424 | setup_ | group | |
425 +--------------------+-------------------------+-------------------------------+
426
427 Table: Condenser Group Members
428
429 .. _crl:
430
431 crl
432 ~~~
433
434 Class describing the compound refractive lenses being used, if there is more than one append _##
435
436 +--------------------+-------------------------+-------------------------------+
437 | Member | Type | Example |
438 +====================+=========================+===============================+
439 | *name* | string dataset | “CRL" |
440 +--------------------+-------------------------+-------------------------------+
441 | *description* | string dataset | “optional” |
442 +--------------------+-------------------------+-------------------------------+
443 | geometry_ | group | |
444 +--------------------+-------------------------+-------------------------------+
445 | setup_ | group | |
446 +--------------------+-------------------------+-------------------------------+
447
448 Table: CRL Group Members
449
450 .. _detection_system:
451
452 *detection_system*
453 ~~~~~~~~~~~~~~~~~~
454
455 In full field imaging the detector consists of microscope objective and a scintillator screen.
456
457 +----------------------------------------------+----------------------------------+----------------------------------+
458 | Member | Type | Example |
459 +==============================================+==================================+==================================+
460 | *name* | string dataset | "Detection 1" |
461 +----------------------------------------------+----------------------------------+----------------------------------+
462 | *description* | string dataset | "Standard microCT" |
463 +----------------------------------------------+----------------------------------+----------------------------------+
464 | objective_ | group | |
465 +----------------------------------------------+----------------------------------+----------------------------------+
466 | scintillator_ | group | |
467 +----------------------------------------------+----------------------------------+----------------------------------+
468
469 Table: Detection System Group Members
470
471 name
472 |
473 | Name.
474
475 description
476 |
477 | Description.
478
479 objective_N
480 |
481 | List of the visible light objectives mounted between the detector and the scintillator screen.
482
483 scintillator
484 |
485 | Scintillator screen
486
487
488 .. _detector:
489
490 *detector*
491 ~~~~~~~~~~
492
493 This class holds information about the detector used during the
494 experiment. If more than one detector are used they will be all listed
495 as detector_N. In full field imaging the detector consists of
496 a CCD camera, microscope objective and a scintillator screen. Raw data
497 recorded by a detector as well as its position and geometry should be
498 stored in this class.
499
500 +----------------------------------------------+----------------------------------+----------------------------------+
501 | Member | Type | Example |
502 +==============================================+==================================+==================================+
503 | *name* | string dataset | "DIMAX 1" |
504 +----------------------------------------------+----------------------------------+----------------------------------+
505 | *description* | string dataset | "description" |
506 +----------------------------------------------+----------------------------------+----------------------------------+
507 | *manufacturer* | string dataset | "CooKe Corporation" |
508 +----------------------------------------------+----------------------------------+----------------------------------+
509 | *model* | string dataset | "pco dimax" |
510 +----------------------------------------------+----------------------------------+----------------------------------+
511 | *serial_number* | string dataset | "1234XW2" |
512 +----------------------------------------------+----------------------------------+----------------------------------+
513 | *firmware_version* | string dataset | "3.7.9" |
514 +----------------------------------------------+----------------------------------+----------------------------------+
515 | *software_version* | string dataset | "1.3.14" |
516 +----------------------------------------------+----------------------------------+----------------------------------+
517 | *bit_depth* | integer | 12 |
518 +----------------------------------------------+----------------------------------+----------------------------------+
519 | *pixel_size_x* | float | 6.7e-6 |
520 +----------------------------------------------+----------------------------------+----------------------------------+
521 | *pixel_size_y* | float | 6.7e-6 |
522 +----------------------------------------------+----------------------------------+----------------------------------+
523 | *actual_pixel_size_x* | float | 1.2e-6 |
524 +----------------------------------------------+----------------------------------+----------------------------------+
525 | *actual_pixel_size_y* | float | 1.2e-6 |
526 +----------------------------------------------+----------------------------------+----------------------------------+
527 | *dimension_x* | integer | 2048 |
528 +----------------------------------------------+----------------------------------+----------------------------------+
529 | *dimension_y* | integer | 2048 |
530 +----------------------------------------------+----------------------------------+----------------------------------+
531 | *binning_x* | integer | 1 |
532 +----------------------------------------------+----------------------------------+----------------------------------+
533 | *binning_y* | integer | 1 |
534 +----------------------------------------------+----------------------------------+----------------------------------+
535 | *operating_temperature* | float | 270 |
536 +----------------------------------------------+----------------------------------+----------------------------------+
537 | *exposure_time* | float | 1.7e-3 |
538 +----------------------------------------------+----------------------------------+----------------------------------+
539 | *delay_time* | float | 1.7e-3 |
540 +----------------------------------------------+----------------------------------+----------------------------------+
541 | *stabilization_time* | float | 1.7e-3 |
542 +----------------------------------------------+----------------------------------+----------------------------------+
543 | *frame_rate* | integer | 2 |
544 +----------------------------------------------+----------------------------------+----------------------------------+
545 | *output_data* | string dataset | "/exchange" |
546 +----------------------------------------------+----------------------------------+----------------------------------+
547 | roi_ | group | |
548 +----------------------------------------------+----------------------------------+----------------------------------+
549 | *counts_per_joule* | float | unitless |
550 +----------------------------------------------+----------------------------------+----------------------------------+
551 | *basis_vectors* | float array | length |
552 +----------------------------------------------+----------------------------------+----------------------------------+
553 | *corner_position* | 3 floats | length |
554 +----------------------------------------------+----------------------------------+----------------------------------+
555 | geometry_ | group | |
556 +----------------------------------------------+----------------------------------+----------------------------------+
557 | setup_ | group | |
558 +----------------------------------------------+----------------------------------+----------------------------------+
559
560 Table: Detector Group Members for Tomography
561
562 name
563 |
564 | Name.
565
566 description
567 |
568 | Description.
569
570 manufacturer
571 |
572 | The detector manufacturer.
573
574 model
575 |
576 | The detector model.
577
578 serial_number
579 |
580 | The detector serial number .
581
582 bit_depth
583 |
584 | The detector bit depth.
585
586 pixel_size_x, pixel_size_y
587 |
588 | Physical detector pixel size (m).
589
590 dimension_x, dimension_y
591 |
592 | The detector horiz./vertical dimension.
593
594 actual_pixel_size_x, actual_pixel_size_y
595 |
596 | Actual pixel size on the sample plane.
597
598 binning_x, binning_y
599 |
600 | If the data are collected binning the detector binning_x and binning_y store the binning factor.
601
602 operating_temperature
603 |
604 | The detector operating temperature (K).
605
606 exposure_time
607 |
608 | The detector exposure time (s).
609
610 delay_time
611 |
612 | Delay time between projections when using a mechanical shutter to reduce radiation damage of the sample (s).
613
614 stabilization_time
615 |
616 | Time required by the sample to stabilize (s).
617
618 frame_rate
619 |
620 | The detector frame rate (fps). This parameter is set for fly scan.
621
622 roi
623 |
624 | The detector selected Region Of Interest (ROI).
625
626 counts_per_joule
627 |
628 | Number of counts recorded per each joule of energy received by the detector. The number of incident photons can then be calculated by:
629
630 basis_vectors
631 |
632 | A matrix with the basis vectors of the detector data.
633
634 corner_position
635 |
636 | The x, y and z coordinates of the corner of the first data element.
637
638 geometry
639 |
640 | Position and orientation of the center of mass of the detector. This should only be specified for non pixel detectors. For pixel detectors use basis_vectors and corner_position.
641
642 .. _diffuser:
643
644 *diffuser*
645 ~~~~~~~~~~
646
647 Class describing the diffuser being used, if there is more than one append _##
648
649 +--------------------+-------------------------+-------------------------------+
650 | Member | Type | Example |
651 +====================+=========================+===============================+
652 | *name* | string dataset | “Diffuser" |
653 +--------------------+-------------------------+-------------------------------+
654 | *description* | string dataset | “optional” |
655 +--------------------+-------------------------+-------------------------------+
656 | geometry_ | group | |
657 +--------------------+-------------------------+-------------------------------+
658 | setup_ | group | |
659 +--------------------+-------------------------+-------------------------------+
660
661 Table: Diffuser Group Members
662
663 .. _flight_tube:
664
665 *flight_tube*
666 ~~~~~~~~~~~~~
667
668 Class describing the flight tube being used, if there is more than one append _##
669
670 +--------------------+-------------------------+-------------------------------+
671 | Member | Type | Example |
672 +====================+=========================+===============================+
673 | *name* | string dataset | “Flight Tube" |
674 +--------------------+-------------------------+-------------------------------+
675 | *description* | string dataset | “optional” |
676 +--------------------+-------------------------+-------------------------------+
677 | geometry_ | group | |
678 +--------------------+-------------------------+-------------------------------+
679 | setup_ | group | |
680 +--------------------+-------------------------+-------------------------------+
681
682 Table: Flight Tube Group Members
683
684 .. _interferometer:
685
686 *interferometer*
687 ~~~~~~~~~~~~~~~~
688
689 This group stores the interferometer parameters.
690
691 +----------------------------------------------+----------------------------------+----------------------------------+
692 | Member | Type | Example |
693 +==============================================+==================================+==================================+
694 | *name* | string dataset | “Inter 1” |
695 +----------------------------------------------+----------------------------------+----------------------------------+
696 | *description* | string dataset | “description” |
697 +----------------------------------------------+----------------------------------+----------------------------------+
698 | *grid_start* | float | 1.8 |
699 +----------------------------------------------+----------------------------------+----------------------------------+
700 | *grid_end* | float | 3.51 |
701 +----------------------------------------------+----------------------------------+----------------------------------+
702 | *number_of_grid_periods* | int | 1 |
703 +----------------------------------------------+----------------------------------+----------------------------------+
704 | *number_of_grid_steps* | int | 6 |
705 +----------------------------------------------+----------------------------------+----------------------------------+
706 | geometry_ | group | |
707 +----------------------------------------------+----------------------------------+----------------------------------+
708 | setup_ | group | |
709 +----------------------------------------------+----------------------------------+----------------------------------+
710
711 Table: Interferometer Group Members
712
713 name
714 |
715 | Name.
716
717 description
718 |
719 | Description.
720
721 start_angle
722 |
723 | Interferometer start angle.
724
725 grid_start
726 |
727 | Interferometer grid start angle.
728
729 grid_end
730 |
731 | Interferometer grid end angle.
732
733 grid_position_for_scan
734 |
735 | Interferometer grid position for scan.
736
737 number_of_grid_steps
738 |
739 | Number of grid steps.
740
741 .. _mirror:
742
743 *mirror*
744 ~~~~~~~~
745
746 Class describing the mirror being used, if there is more than one append _##
747
748 +--------------------+-------------------------+-------------------------------+
749 | Member | Type | Example |
750 +====================+=========================+===============================+
751 | *name* | string dataset | “M1" |
752 +--------------------+-------------------------+-------------------------------+
753 | *description* | string dataset | “optional” |
754 +--------------------+-------------------------+-------------------------------+
755 | *angle* | float | “optional” |
756 +--------------------+-------------------------+-------------------------------+
757 | geometry_ | group | |
758 +--------------------+-------------------------+-------------------------------+
759 | setup_ | group | |
760 +--------------------+-------------------------+-------------------------------+
761
762 Table: Mirror Group Members
763
764 .. _monochromator:
765
766 *monochromator*
767 ~~~~~~~~~~~~~~~
768
769 Define the monochromator used in the instrument.
770
771 +--------------------+-------------------------+-------------------------------+
772 | Member | Type | Example |
773 +====================+=========================+===============================+
774 | *name* | string dataset | “Mono 1” |
775 +--------------------+-------------------------+-------------------------------+
776 | *description* | string dataset | “Multilayer” |
777 +--------------------+-------------------------+-------------------------------+
778 | *energy* | float dataset | 1.602e-15 |
779 +--------------------+-------------------------+-------------------------------+
780 | *energy_error* | float dataset | 1.602e-17 |
781 +--------------------+-------------------------+-------------------------------+
782 | *mono_stripe* | string dataset | “Ru/C” |
783 +--------------------+-------------------------+-------------------------------+
784 | geometry_ | group | |
785 +--------------------+-------------------------+-------------------------------+
786 | setup_ | group | |
787 +--------------------+-------------------------+-------------------------------+
788
789 Table: Monochromator Group Members
790
791 name
792 |
793 | Name.
794
795 description
796 |
797 | Description.
798
799 energy
800 |
801 | Peak of the spectrum that the monochromator selects. Since units
802 | is not defined this field is in J and corresponds to 10 keV.
803
804 energy_error
805 |
806 | Standard deviation of the spectrum that the monochromator selects.
807 | Since units is not defined this field is in J.
808
809 mono_stripe
810 |
811 | Type of multilayer coating or crystal.
812
813 .. _pin_hole:
814
815 *pin_hole*
816 ~~~~~~~~~~
817
818 Class describing the pin hole being used, if there is more than one append _##
819
820 +--------------------+-------------------------+-------------------------------+
821 | Member | Type | Example |
822 +====================+=========================+===============================+
823 | *name* | string dataset | “Pin Hole" |
824 +--------------------+-------------------------+-------------------------------+
825 | *description* | string dataset | “optional” |
826 +--------------------+-------------------------+-------------------------------+
827 | geometry_ | group | |
828 +--------------------+-------------------------+-------------------------------+
829 | setup_ | group | |
830 +--------------------+-------------------------+-------------------------------+
831
832 Table: Pin Hole Group Members
833
834 .. _shutter:
835
836 *shutter*
837 ~~~~~~~~~
838
839 Class describing the shutter being used.
840
841 +--------------------+-------------------------+-------------------------------+
842 | Member | Type | Example |
843 +====================+=========================+===============================+
844 | *name* | string dataset | “Front End Shutter 1" |
845 +--------------------+-------------------------+-------------------------------+
846 | *description* | string dataset | “optional” |
847 +--------------------+-------------------------+-------------------------------+
848 | *status* | string dataset | “OPEN” |
849 +--------------------+-------------------------+-------------------------------+
850 | geometry_ | group | |
851 +--------------------+-------------------------+-------------------------------+
852 | setup_ | group | |
853 +--------------------+-------------------------+-------------------------------+
854
855 Table: Shutter Group Members
856
857 name
858 |
859 | Name.
860
861 description
862 |
863 | Description.
864
865 status
866 |
867 | “OPEN” or “CLOSED”
868
869 .. _samplee:
870
871 *sample*
872 ~~~~~~~~
873
874 Class describing the sample stage stack being used.
875
876 +--------------------+-------------------------+-------------------------------+
877 | Member | Type | Example |
878 +====================+=========================+===============================+
879 | *name* | string dataset | “TXM sample stack" |
880 +--------------------+-------------------------+-------------------------------+
881 | *description* | string dataset | “optional” |
882 +--------------------+-------------------------+-------------------------------+
883 |*detector_distance* | string dataset | “optional” |
884 +--------------------+-------------------------+-------------------------------+
885 | geometry_ | group | |
886 +--------------------+-------------------------+-------------------------------+
887 | setup_ | group | |
888 +--------------------+-------------------------+-------------------------------+
889
890 Table: Sample stage stack Group Members
891
892 .. _source:
893
894 *source*
895 ~~~~~~~~
896
897 Class describing the light source being used.
898
899 +-----------------------------+--------------------------------+---------------------------+
900 | Member | Type | Example |
901 +=============================+================================+===========================+
902 |*name* | string dataset | “APS” |
903 +-----------------------------+--------------------------------+---------------------------+
904 |*description* | float dataset | "optional" |
905 +-----------------------------+--------------------------------+---------------------------+
906 |*datetime* | string dataset (ISO 8601) | “2011-07-15T15:10Z” |
907 +-----------------------------+--------------------------------+---------------------------+
908 |*beamline* | string dataset | “2-BM” |
909 +-----------------------------+--------------------------------+---------------------------+
910 |*current* | float dataset | 0.094 |
911 +-----------------------------+--------------------------------+---------------------------+
912 |*energy* | float dataset | 4.807e-15 |
913 +-----------------------------+--------------------------------+---------------------------+
914 |*pulse_energy* | float dataset | 1.602e-15 |
915 +-----------------------------+--------------------------------+---------------------------+
916 |*pulse_width* | float dataset | 15e-11 |
917 +-----------------------------+--------------------------------+---------------------------+
918 |*mode* | string dataset | “TOPUP” |
919 +-----------------------------+--------------------------------+---------------------------+
920 |*beam_intensity_incident* | float dataset | 55.93 |
921 +-----------------------------+--------------------------------+---------------------------+
922 |*beam_intensity_transmitted* | float dataset | 100.0 |
923 +-----------------------------+--------------------------------+---------------------------+
924 | geometry_ | group | |
925 +-----------------------------+--------------------------------+---------------------------+
926 | setup_ | group | |
927 +-----------------------------+--------------------------------+---------------------------+
928
929 Table: Source
930
931
932 name
933 |
934 | Name.
935
936 description
937 |
938 | Description.
939
940 datetime
941 |
942 | Date and time source was measured.
943
944 beamline
945 |
946 | Name of the beamline.
947
948 current
949 |
950 | Electron beam current (A).
951
952 energy
953 |
954 | Characteristic photon energy of the source (J). For an APS bending
955 | magnet this is 30 keV or 4.807e-15 J.
956
957 pulse_energy
958 |
959 | Sum of the energy of all the photons in the pulse (J). pulse_width
960 | Duration of the pulse (s).
961
962 mode
963 |
964 | Beam mode: TOP-UP.
965
966 beam_intensity_incident
967 |
968 | Incident beam intensity in (photons per s).
969
970 beam_intensity_transmitted
971 |
972 | Transmitted beam intensity (photons per s).
973
974
975 .. _slits:
976
977 *slists*
978 ~~~~~~~~
979
980 Class describing the slits being used.
981
982 +--------------------+-------------------------+-------------------------------+
983 | Member | Type | Example |
984 +====================+=========================+===============================+
985 | *name* | string dataset | “A slits" |
986 +--------------------+-------------------------+-------------------------------+
987 | *description* | string dataset | “Horizontal Slits” |
988 +--------------------+-------------------------+-------------------------------+
989 | geometry_ | group | |
990 +--------------------+-------------------------+-------------------------------+
991 | setup_ | group | |
992 +--------------------+-------------------------+-------------------------------+
993
994 Table: Slits Group Members
995
996 name
997 |
998 | Name.
999
1000 description
1001 |
1002 | Description.
1003
1004
1005
1006 .. _table:
1007
1008 *table*
1009 ~~~~~~~
1010
1011 Class describing the zone plate being used, if there is more than one append _##
1012
1013 +--------------------+-------------------------+-------------------------------+
1014 | Member | Type | Example |
1015 +====================+=========================+===============================+
1016 | *name* | string dataset | “Optical Table" |
1017 +--------------------+-------------------------+-------------------------------+
1018 | *description* | string dataset | “optional” |
1019 +--------------------+-------------------------+-------------------------------+
1020 | geometry_ | group | |
1021 +--------------------+-------------------------+-------------------------------+
1022 | setup_ | group | |
1023 +--------------------+-------------------------+-------------------------------+
1024
1025 Table: Optical Table Group Members
1026
1027
1028 .. _zone_plate:
1029
1030 *zone_plate*
1031 ~~~~~~~~~~~~
1032
1033 Class describing the zone plate being used, if there is more than one append _##
1034
1035 +--------------------+-------------------------+-------------------------------+
1036 | Member | Type | Example |
1037 +====================+=========================+===============================+
1038 | *name* | string dataset | “Zone Plate" |
1039 +--------------------+-------------------------+-------------------------------+
1040 | *description* | string dataset | “optional” |
1041 +--------------------+-------------------------+-------------------------------+
1042 | geometry_ | group | |
1043 +--------------------+-------------------------+-------------------------------+
1044 | setup_ | group | |
1045 +--------------------+-------------------------+-------------------------------+
1046
1047 Table: Zone Plate Group Members
1048
1049 .. _roi:
1050
1051 *roi*
1052 ^^^^^
1053
1054 Group describing the region of interest (ROI) of the image actually
1055 collected, if smaller than the full CCD.
1056
1057 +----------------+----------------+-----------------+
1058 | Member | Type | Example |
1059 +================+================+=================+
1060 | *name* | string dataset | "ROI 04" |
1061 +----------------+----------------+-----------------+
1062 | *description* | string dataset | "center third" |
1063 +----------------+----------------+-----------------+
1064 | *min_x* | integer | 256 |
1065 +----------------+----------------+-----------------+
1066 | *size_x* | integer | 256 |
1067 +----------------+----------------+-----------------+
1068 | *min_y* | integer | 1792 |
1069 +----------------+----------------+-----------------+
1070 | *size_y* | integer | 1792 |
1071 +----------------+----------------+-----------------+
1072
1073 Table: ROI Group Members
1074
1075 name
1076 |
1077 | Name.
1078
1079 description
1080 |
1081 | Description.
1082
1083 min_x, min_y
1084 |
1085 | Top Left pixel x and y position.
1086
1087 size_x, size_y
1088 |
1089 | x and y image size.
1090
1091
1092
1093 .. _objective:
1094
1095 *objective*
1096 ^^^^^^^^^^^
1097
1098 Group describing the microscope objective lenses used.
1099
1100 +------------------------------------+----------------+-----------------+
1101 | Member | Type | Example |
1102 +====================================+================+=================+
1103 | *name* | string dataset | "Lens 01" |
1104 +------------------------------------+----------------+-----------------+
1105 | *description* | string dataset | "ZeissAx" |
1106 +------------------------------------+----------------+-----------------+
1107 | *manufacturer* | string dataset | "Zeiss" |
1108 +------------------------------------+----------------+-----------------+
1109 | *model* | string dataset | "Axioplan" |
1110 +------------------------------------+----------------+-----------------+
1111 | *magnification* | float dataset | 5 |
1112 +------------------------------------+----------------+-----------------+
1113 | *numerical_aperture* | float dataset | 0.8 |
1114 +------------------------------------+----------------+-----------------+
1115 | geometry_ | group | |
1116 +------------------------------------+----------------+-----------------+
1117 | setup_ | group | |
1118 +------------------------------------+----------------+-----------------+
1119
1120 Table: Objective Group Members
1121
1122 name
1123 |
1124 | Name.
1125
1126 description
1127 |
1128 | Description.
1129
1130 manufacturer
1131 |
1132 | Lens manufacturer.
1133
1134 model
1135 |
1136 | Lens model.
1137
1138 magnification
1139 |
1140 | Lens specified magnification.
1141
1142 numerical_aperture
1143 |
1144 | The numerical aperture (N.A.) is a measure of the light-gathering characteristics of the lens.
1145
1146 .. _scintillator:
1147
1148 *scintillator*
1149 ^^^^^^^^^^^^^^
1150
1151 Group describing the visible light scintillator coupled to the CCD
1152 camera objective lens.
1153
1154 +------------------------------------+----------------+-----------------+
1155 | Member | Type | Example |
1156 +====================================+================+=================+
1157 | *name* | string dataset | "Yag polished" |
1158 +------------------------------------+----------------+-----------------+
1159 | *description* | string dataset | "Yag on Yag" |
1160 +------------------------------------+----------------+-----------------+
1161 | *manufacturer* | string dataset | "Crytur" |
1162 +------------------------------------+----------------+-----------------+
1163 | *serial_number* | string dataset | "12" |
1164 +------------------------------------+----------------+-----------------+
1165 | *scintillating_thickness* | float dataset | 5e-6 |
1166 +------------------------------------+----------------+-----------------+
1167 | *substrate_thickness* | float dataset | 1e-4 |
1168 +------------------------------------+----------------+-----------------+
1169 | geometry_ | group | |
1170 +------------------------------------+----------------+-----------------+
1171 | setup_ | group | |
1172 +------------------------------------+----------------+-----------------+
1173
1174 Table: Scintillator Group Members
1175
1176 name
1177 |
1178 | Scintillator name.
1179
1180 description
1181 |
1182 | Scintillator description.
1183
1184 manufacturer
1185 |
1186 | Scintillator Manufacturer.
1187
1188 serial_number
1189 |
1190 | Scintillator serial number.
1191
1192 scintillating_thickness
1193 |
1194 | Scintillator thickness.
1195
1196 substrate_thickness
1197 |
1198 | Scintillator substrate thickness.
1199
1200
1201 .. _setup:
1202
1203 *setup*
1204 ~~~~~~~
1205
1206 Logging instrument and beamline component setup parameters (static setup values)
1207 is not defined by Data Exchange because is specific and different for each instrument
1208 and beamline. To capture this information Data Exchange requires to set a *setup*
1209 group under each beamline component and leaves each facility free to store what
1210 is relevant for each component (list of motor positions etc.).
1211 Ideally each component in the instrument list (source, shutter, attenuator etc.) should have
1212 included its setup group. For setup values not associated with a specific beamline component
1213 a *setup* group in the instrument group should be created.
1214
1215
1216 +----------------------------------------------+----------------------------------+----------------------------------+
1217 | Member | Type | Example |
1218 +==============================================+==================================+==================================+
1219 | *motor_x* | float | -10.107 |
1220 +----------------------------------------------+----------------------------------+----------------------------------+
1221 | *motor_y* | float | -17.900 |
1222 +----------------------------------------------+----------------------------------+----------------------------------+
1223 | *motor_z* | float | -5.950 |
1224 +----------------------------------------------+----------------------------------+----------------------------------+
1225 | *motor_xx* | float | -1.559 |
1226 +----------------------------------------------+----------------------------------+----------------------------------+
1227 | *motor_zz* | float | 1.307 |
1228 +----------------------------------------------+----------------------------------+----------------------------------+
1229
1230 .. _sample:
1231
1232 *sample*
1233 --------
1234
1235 This group holds basic information about the sample, its geometry,
1236 properties, the sample owner (user) and sample proposal information.
1237 While all these fields are optional, if you do intend to include them
1238 they should appear within this parentage of groups.
1239
1240 +-------------------------------------+------------------------------------+-----------------------------+
1241 | Member | Type | Example |
1242 +=====================================+====================================+=============================+
1243 | *name* | string dataset | "cells sample 1" |
1244 +-------------------------------------+------------------------------------+-----------------------------+
1245 | *description* | string dataset | "malaria cells" |
1246 +-------------------------------------+------------------------------------+-----------------------------+
1247 | *file_path* | string dataset | "/2016-03/tst/" |
1248 +-------------------------------------+------------------------------------+-----------------------------+
1249 | *preparation_date* | string dataset (ISO 8601) | "2012-07-31T21:15:22+0600" |
1250 +-------------------------------------+------------------------------------+-----------------------------+
1251 | *chemical_formula* | string dataset (abbr. CIF format) | "(Cd 2+)3, 2(H2 O)" |
1252 +-------------------------------------+------------------------------------+-----------------------------+
1253 | *mass* | float dataset | 0.25 |
1254 +-------------------------------------+------------------------------------+-----------------------------+
1255 | *concentration* | float dataset | 0.4 |
1256 +-------------------------------------+------------------------------------+-----------------------------+
1257 | *environment* | string dataset | "air" |
1258 +-------------------------------------+------------------------------------+-----------------------------+
1259 | *temperature* | float dataset | 25.4 |
1260 +-------------------------------------+------------------------------------+-----------------------------+
1261 | *temperature_set* | float dataset | 26.0 |
1262 +-------------------------------------+------------------------------------+-----------------------------+
1263 | *pressure* | float dataset | 101325 |
1264 +-------------------------------------+------------------------------------+-----------------------------+
1265 | *thickness* | float dataset | 0.001 |
1266 +-------------------------------------+------------------------------------+-----------------------------+
1267 | *position* | string dataset | "2D" APS robot coord. |
1268 +-------------------------------------+------------------------------------+-----------------------------+
1269 | geometry_ | group | |
1270 +-------------------------------------+------------------------------------+-----------------------------+
1271 | experiment_ | group | |
1272 +-------------------------------------+------------------------------------+-----------------------------+
1273 | experimenter_ | group | |
1274 +-------------------------------------+------------------------------------+-----------------------------+
1275
1276 Table: Sample Group Members
1277
1278 name
1279 |
1280 | Descriptive name of the sample.
1281
1282 file_path
1283 |
1284 | Directory path where the data were originally saved.
1285
1286 description
1287 |
1288 | Description of the sample.
1289
1290 preparation_date
1291 |
1292 | Date and time the sample was prepared.
1293
1294 chemical_formula
1295 |
1296 | Sample chemical formula using the CIF format.
1297
1298 mass
1299 |
1300 | Mass of the sample.
1301
1302 concentration
1303 |
1304 | Mass/volume.
1305
1306 environment
1307 |
1308 | Sample environment.
1309
1310 temperature
1311 |
1312 | Sample temperature.
1313
1314 temperature_set
1315 |
1316 | Sample temperature set point.
1317
1318 pressure
1319 |
1320 | Sample pressure.
1321
1322 thickness
1323 |
1324 | Sample thickness.
1325
1326 position
1327 |
1328 | Sample position in the sample changer/robot.
1329
1330 geometry
1331 |
1332 | Sample center of mass position and orientation.
1333
1334 experiment
1335 |
1336 | Facility experiment identifiers.
1337
1338 experimenter
1339 |
1340 | Experimenter identifiers.
1341
1342 *experiment*
1343 ~~~~~~~~~~~~
1344
1345 This provides references to facility ids for the proposal, scheduled
1346 activity, and safety form.
1347
1348 +---------------+-------------------------+----------------------+
1349 | Member | Type | Example |
1350 +===============+=========================+======================+
1351 | *proposal* | string dataset | “1234” |
1352 +---------------+-------------------------+----------------------+
1353 | *activity* | string dataset | “9876” |
1354 +---------------+-------------------------+----------------------+
1355 | *safety* | string dataset | “9876” |
1356 +---------------+-------------------------+----------------------+
1357 | *title* | string dataset | “Al 4D dynamic tomo” |
1358 +---------------+-------------------------+----------------------+
1359
1360 Table: Experiment Group Members
1361
1362 proposal
1363 |
1364 | Proposal reference number. For the APS this is the General User
1365 | Proposal number.
1366
1367 activity
1368 |
1369 | Proposal scheduler id. For the APS this is the beamline scheduler
1370 activity id.
1371
1372 safety
1373 |
1374 | Safety reference document. For the APS this is the Experiment
1375 | Safety Approval Form number.
1376
1377 title
1378 |
1379 | Proposal title.
1380
1381
1382 *experimenter*
1383 ~~~~~~~~~~~~~~
1384
1385 Description of a single experimenter. Multiple experimenters can be
1386 represented through numbered entries such as experimenter_1,
1387 experimenter_2.
1388
1389 +--------------------+-------------------------+--------------------------------------------+
1390 | Member | Type | Example |
1391 +====================+=========================+============================================+
1392 | *name* | string dataset | “John Doe” |
1393 +--------------------+-------------------------+--------------------------------------------+
1394 | *role* | string dataset | “Project PI” |
1395 +--------------------+-------------------------+--------------------------------------------+
1396 | *affiliation* | string dataset | “University of California, Berkeley” |
1397 +--------------------+-------------------------+--------------------------------------------+
1398 | *address* | string dataset | “EPS UC Berkeley CA 94720 4767 USA” |
1399 +--------------------+-------------------------+--------------------------------------------+
1400 | *phone* | string dataset | “+1 123 456 0000” |
1401 +--------------------+-------------------------+--------------------------------------------+
1402 | *email* | string dataset | “[email protected]” |
1403 +--------------------+-------------------------+--------------------------------------------+
1404 | *facility_user_id* | string dataset | “a123456” |
1405 +--------------------+-------------------------+--------------------------------------------+
1406
1407 Table: Experimenter Group Members
1408
1409 name: User name.
1410
1411 role: User role.
1412
1413 affiliation: User affiliation.
1414
1415 address: User address.
1416
1417 phoen: User phone number.
1418
1419 email: User e-mail address
1420
1421 facility_user_id: User badge number
1422
1423
1424 .. _geometry:
1425
1426 *geometry*
1427 ^^^^^^^^^^
1428
1429 The geometry group is common to many of the subgroups under
1430 measurement. The intent is to describe the translation and rotation
1431 (orientation) of the sample or instrument component relative to some
1432 coordinate system. Since we believe it is not possible to determine all
1433 possible uses at this time, we leave the precise definition of geometry
1434 up to the technique. We do encourage the use of separate translation and
1435 orientation subgroups within geometry. As such, we do not describe
1436 geometry further here. This class holds the general position and
1437 orientation of a component.
1438
1439 +----------------------------------------------+-----------------+----------------------------------+
1440 | Member | Type | Example |
1441 +==============================================+=================+==================================+
1442 | translation_ | group | |
1443 +----------------------------------------------+-----------------+----------------------------------+
1444 | orientation_ | group | |
1445 +----------------------------------------------+-----------------+----------------------------------+
1446
1447 translation
1448 |
1449 | The position of the object with respect to the origin of your coordinate system.
1450
1451 orientation
1452 |
1453 | The rotation of the object with respect to your coordinate system.
1454
1455 .. _translation:
1456
1457 *translation*
1458 `````````````
1459
1460 This is the description for the general spatial location of a component
1461 for tomography.
1462
1463 +----------------------------+------------------------+-----------------+
1464 | Member | Type | Example |
1465 +============================+========================+=================+
1466 | *distances* | 3 float array dataset | (0, 0.001, 0) |
1467 +----------------------------+------------------------+-----------------+
1468
1469 distances
1470 |
1471 | The x, y and z components of the translation of the origin of the object
1472 | relative to the origin of the global coordinate system (the place where
1473 | the X-ray beam meets the sample when the sample is first aligned in the beam).
1474 | If distances does not have the attribute units set then the units are in
1475 | meters.
1476
1477 .. _orientation:
1478
1479 *orientation*
1480 `````````````
1481
1482 This is the description for the orientation of a component for
1483 tomography.
1484
1485 +----------------------------+------------------------+-----------------+
1486 | Member | Type | Example |
1487 +============================+========================+=================+
1488 | *value* | 6 float array dataset | |
1489 +----------------------------+------------------------+-----------------+
1490
1491 value
1492 |
1493 | Dot products between the local and the global unit vectors. Unitless
1494
1495
1496 The orientation information is stored as direction cosines. The
1497 direction cosines will be between the local coordinate directions and
1498 the global coordinate directions. The unit vectors in both the local and
1499 global coordinates are right-handed and orthonormal.
1500
1501 Calling the local unit vectors (x', y',z') and the reference unit
1502 vectors (x, y, z) the six numbers will be
1503
1504
1505 .. math:: [x \cdot x, x' \cdot y, x' \cdot z, y' \cdot x, y' \cdot y, y' \cdot z]
1506
1507 where
1508
1509 .. math:: `\cdot`
1510
1511 is the scalar dot product (cosine of the angle between the unit vectors).
1512
1513 Notice that this corresponds to the first two rows of the rotation
1514 matrix that transforms from the global orientation to the local
1515 orientation. The third row can be recovered by using the fact that the
1516 basis vectors are orthonormal.
1517
1518 *process*
1519 =========
1520
1521 Process is the documentation of the data collection strategy
1522 (*acquisition*) steps, all transformations, analyses and interpretations
1523 of data performed by a sequence of process functions (*actor*) as well
1524 as any sample preparation step done ahead of the experiment and during the
1525 measurement (e.g. environment conditions etc.).
1526
1527 Maintaining this history, also called provenance, allows for reproducible
1528 data. The Data Exchange format tracks process by allowing each actor
1529 to append process information to a process table.
1530
1531 The process table tracks provenance in the execution order as a series
1532 of processing steps by appending sequential actor entries in the process
1533 table.
1534
1535
1536 +-------------------------------------+------------------------------------+-----------------------------+
1537 | Member | Type | Example |
1538 +=====================================+====================================+=============================+
1539 | *name* | string dataset | "name" |
1540 +-------------------------------------+------------------------------------+-----------------------------+
1541 | *description* | string dataset | "optional" |
1542 +-------------------------------------+------------------------------------+-----------------------------+
1543 | acquisition_ | group | |
1544 +-------------------------------------+------------------------------------+-----------------------------+
1545 | tomo_rec_ | group | |
1546 +-------------------------------------+------------------------------------+-----------------------------+
1547 | transfer_ | group | |
1548 +-------------------------------------+------------------------------------+-----------------------------+
1549 | table_ | group | |
1550 +-------------------------------------+------------------------------------+-----------------------------+
1551
1552 Table: Process Group Members
1553
1554 name
1555 |
1556 | Descriptive process task.
1557
1558 description
1559 |
1560 | Description of the process task.
1561
1562 .. _acquisition:
1563
1564 *acquisition*
1565 -------------
1566
1567 Logging acquisition parameters (static setup and per-image values) is not defined by Data Exchange
1568 because is specific and different for each instrument and beamline.
1569 In the table below we present the implementation adopted by the Swiss Light Source and
1570 Advanced Photon Source.
1571
1572 +----------------------------------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
1573 | Member | Type | Example |
1574 +==============================================+====================+======================================================================================================================================================+
1575 | *name* | string dataset | "mosaic" |
1576 +----------------------------------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
1577 | *description* | string dataset | "step scan" |
1578 +----------------------------------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
1579 | *output_data* | string dataset | "/exchange" |
1580 +----------------------------------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
1581 | *version* | string dataset | https://github.com/data_collection_scripts/b9ad87e17 |
1582 +----------------------------------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
1583 | *sample_position_x* | 1D array | Position of the sample axis x for each image collected |
1584 +----------------------------------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
1585 | *sample_position_y* | 1D array | Position of the sample axis y for each image collected |
1586 +----------------------------------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
1587 | *sample_position_z* | 1D array | Position of the sample axis z for each image collected |
1588 +----------------------------------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
1589 | *sample_image_shift_x* | 1D array | Vector containing the shift of the sample axis x at each projection on the detector plane. |
1590 +----------------------------------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
1591 | *sample_image_shift_y* | 1D array | Vector containing the shift of the sample axis y at each projection on the detector plane. |
1592 +----------------------------------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
1593 | *sample_image_shift_x* | 1D array | Vector containing the shift of the sample axis z at each projection on the detector plane. |
1594 +----------------------------------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
1595 | *image_theta* | 1D array | Vector containing the rotary stage angular position read from the encoder at each image. |
1596 +----------------------------------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
1597 | *scan_index* | 1D array | Vector containin for each image the identifier assigned by beamline controls to each individual series of images or scan. |
1598 +----------------------------------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
1599 | *scan_date* | 1D array | Vector containin for each image the wall date/time at start of scan in iso 8601. |
1600 +----------------------------------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
1601 | *image_date* | 1D array | Vector containing the date/time each image was acquired in iso 8601. |
1602 +----------------------------------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
1603 | *time_stamp* | 1D array | Vector containin for each image the relative time since scan_date |
1604 +----------------------------------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
1605 | *image_number* | 1D array | Vector containin for each image the the image serial number as assigned by the camera. Unique for each individual scan. Always starts at 0.0 |
1606 +----------------------------------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
1607 | *image_exposure_time* | 1D array | Vector containin for each image the the measured exposure time |
1608 +----------------------------------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
1609 | *image_is_complete* | 1D array | Vector containin for each image the boolen status of: is any pixel data missing? |
1610 +----------------------------------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
1611 | *image_type* | 1D array | Vector containin for each image contained in /exchange/data 0 for white, 1 for projection and 2 for dark. |
1612 +----------------------------------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
1613 | set-up_ | group | |
1614 +----------------------------------------------+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
1615
1616
1617 Table: Acquisition Group Members
1618
1619
1620 name
1621 |
1622 | Descriptive *name* for *acquisition*. Current name include:
1623 tomo, interlaced, mosaic.
1624
1625 description
1626 |
1627 | Description.
1628
1629
1630 .. _set-up:
1631
1632 *setup*
1633 ~~~~~~~
1634
1635 List of static scan setup values. In the table below we present the implementation adopted by the Swiss Light Source and
1636 Advanced Photon Source.
1637
1638 +----------------------------------------------+----------------------------------+----------------------------------+
1639 | Member | Type | Example |
1640 +==============================================+==================================+==================================+
1641 | *rotation_start_angle* | float | 0.0 |
1642 +----------------------------------------------+----------------------------------+----------------------------------+
1643 | *rotation_end_angle* | float | 180.0 |
1644 +----------------------------------------------+----------------------------------+----------------------------------+
1645 | *rotation_speed* | float | 180.0 |
1646 +----------------------------------------------+----------------------------------+----------------------------------+
1647 | *angular_step* | float | 0.125 |
1648 +----------------------------------------------+----------------------------------+----------------------------------+
1649 | *number_of_projections* | integer | 1441 |
1650 +----------------------------------------------+----------------------------------+----------------------------------+
1651 | *number_of_whites* | integer | 100 |
1652 +----------------------------------------------+----------------------------------+----------------------------------+
1653 | *number_of_darks* | integer | 32 |
1654 +----------------------------------------------+----------------------------------+----------------------------------+
1655 | *number_of_inter_whites* | integer | 1 |
1656 +----------------------------------------------+----------------------------------+----------------------------------+
1657 | *inner_scan_flag* | integer | 1 |
1658 +----------------------------------------------+----------------------------------+----------------------------------+
1659 | *white_frequency* | integer | 0 |
1660 +----------------------------------------------+----------------------------------+----------------------------------+
1661 | *sample_in* | float | 0.0 |
1662 +----------------------------------------------+----------------------------------+----------------------------------+
1663 | *sample_out* | float | 4.0 |
1664 +----------------------------------------------+----------------------------------+----------------------------------+
1665
1666
1667 Table: Static Setup Acquisition Group for Tomography
1668
1669
1670 .. _tomo_rec:
1671
1672 *tomo_rec* (APS)
1673 ----------------
1674
1675 The Reconstruction process description group contains metadata required
1676 to run a tomography reconstruction. The specific algorithm is described
1677 in a separate group under the reconstruction setup group.
1678 Here is where to log the algorithm setup parameters. In the case of tomoPy
1679 this can simply be the link to the scrip used to run the reconstruction.
1680
1681 +-------------------------------------+------------------------------------+---------------------------------------------+
1682 | Member | Type | Example |
1683 +=====================================+====================================+=============================================+
1684 | *name* | string dataset | "test rec" |
1685 +-------------------------------------+------------------------------------+---------------------------------------------+
1686 | *description* | string dataset | "optional" |
1687 +-------------------------------------+------------------------------------+---------------------------------------------+
1688 | *version* | string dataset | https://github.com/tomopy_scripts/b9ad87e17 |
1689 +-------------------------------------+------------------------------------+---------------------------------------------+
1690 | *input_data* | string dataset | "/exchange" |
1691 +-------------------------------------+------------------------------------+---------------------------------------------+
1692 | *output_data* | string dataset | "/exchange_1" |
1693 +-------------------------------------+------------------------------------+---------------------------------------------+
1694 | set_up_ | group | |
1695 +-------------------------------------+------------------------------------+---------------------------------------------+
1696
1697
1698 Table: Reconstruction Actor Group Members
1699
1700 name
1701 |
1702 | Descriptive actor task.
1703
1704 description
1705 |
1706 | Description of the actor task.
1707
1708 version
1709 |
1710 | Version of the actor task.
1711 |
1712 | If available this can be the repository link to the actor version used
1713 | https://github.com/tomopy_scripts/b9ad87e17
1714 input_data, output_data
1715 |
1716 | Origin and destination of the data processed by the reconstruction task.
1717
1718 .. _set_up:
1719
1720 *setup* (APS)
1721 ~~~~~~~~~~~~~
1722
1723 Here is where to log the algorithms used by the reconstruction actor.
1724
1725
1726 +-------------------------------------+------------------------------------+-----------------------------------------------+
1727 | Member | Type | Example |
1728 +=====================================+====================================+===============================================+
1729 | *astra* | string dataset | https://github.com/astra/b9ad87e17 |
1730 +-------------------------------------+------------------------------------+-----------------------------------------------+
1731 | *tomopy* | string dataset | https://github.com/tomopy/c9ad87e77 |
1732 +-------------------------------------+------------------------------------+-----------------------------------------------+
1733
1734 Table: Reconstruction Setup Group Members
1735
1736 .. _reconstruction_sls:
1737
1738 *tomo_rec (SLS)*
1739 ----------------
1740
1741 The reconstruction process description group contains metadata required
1742 to run a tomography reconstruction. The specific algorithm is described
1743 in a separate group under the reconstruction setup group.
1744 Here is where to log the algorithm setup parameters.
1745
1746 +-------------------------------------+------------------------------------+---------------------------------------------+
1747 | Member | Type | Example |
1748 +=====================================+====================================+=============================================+
1749 | *name* | string dataset | "sls rec" |
1750 +-------------------------------------+------------------------------------+---------------------------------------------+
1751 | *description* | string dataset | "optional" |
1752 +-------------------------------------+------------------------------------+---------------------------------------------+
1753 | *version* | string dataset | https://github.com/sls_scripts/b9ad87e17 |
1754 +-------------------------------------+------------------------------------+---------------------------------------------+
1755 | *input_data* | string dataset | "/exchange" |
1756 +-------------------------------------+------------------------------------+---------------------------------------------+
1757 | *output_data* | string dataset | "/exchange_1" |
1758 +-------------------------------------+------------------------------------+---------------------------------------------+
1759 | set_up_sls_ | group | |
1760 +-------------------------------------+------------------------------------+---------------------------------------------+
1761
1762
1763 Table: Reconstruction Actor Group Members
1764
1765 name
1766 |
1767 | Descriptive actor task.
1768
1769 description
1770 |
1771 | Description of the actor task.
1772
1773 version
1774 |
1775 | Version of the actor task.
1776 |
1777 | If available this can be the repository link to the actor version used
1778 | https://github.com/tomopy_scripts/b9ad87e17
1779 input_data, output_data
1780 |
1781 | Origin and destination of the data processed by the reconstruction task.
1782
1783 .. _set_up_sls:
1784
1785 *setup* (SLS)
1786 ~~~~~~~~~~~~~
1787
1788 Here is where to log the algorithms used by the reconstruction actor.
1789
1790
1791 +-------------------------------------+-----------------+----------------------------+
1792 | Member | Type | Example |
1793 +=====================================+=================+============================+
1794 | *reconstruction_slice_start* | int dataset | 1000 |
1795 +-------------------------------------+-----------------+----------------------------+
1796 | *reconstruction_slice_end* | int dataset | 1030 |
1797 +-------------------------------------+-----------------+----------------------------+
1798 | *rotation_center* | Float dataset | 1048.50 |
1799 +-------------------------------------+-----------------+----------------------------+
1800 | algorithm-sls_ | Group | |
1801 +-------------------------------------+-----------------+----------------------------+
1802
1803 Table: Reconstruction Setup SLS Group Members
1804
1805 reconstruction_slice_start
1806 |
1807 | First reconstruction slice.
1808
1809 reconstruction_slice_end
1810 |
1811 | Last reconstruction slice.
1812
1813 rotation_center
1814 |
1815 | Center of rotation in pixels.
1816
1817 algorithm
1818 |
1819 | Algorithm group describing reconstruction algorithm parameters.
1820
1821
1822 .. _algorithm-sls:
1823
1824 *algorithm* (SLS iterative)
1825 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
1826
1827 The Algorithm group contains information required to run a tomography
1828 reconstruction algorithm.
1829
1830 +----------------------------------------------+-----------------+-------------------+
1831 | Member | Type | Example |
1832 +==============================================+=================+===================+
1833 | *name* | string dataset | "SART" |
1834 +----------------------------------------------+-----------------+-------------------+
1835 | *version* | string dataset | "1.0" |
1836 +----------------------------------------------+-----------------+-------------------+
1837 | *implementation* | string dataset | "GPU" |
1838 +----------------------------------------------+-----------------+-------------------+
1839 | *number_of_nodes* | int dataset | 16 |
1840 +----------------------------------------------+-----------------+-------------------+
1841 | *type* | string dataset | "Iterative" |
1842 +----------------------------------------------+-----------------+-------------------+
1843 | *stop_condition* | string dataset | "iteration_max" |
1844 +----------------------------------------------+-----------------+-------------------+
1845 | *iteration_max* | int dataset | 200 |
1846 +----------------------------------------------+-----------------+-------------------+
1847 | *projection_threshold* | float dataset | |
1848 +----------------------------------------------+-----------------+-------------------+
1849 | *difference_threshold_percent* | float dataset | |
1850 +----------------------------------------------+-----------------+-------------------+
1851 | *difference_threshold_value* | float dataset | |
1852 +----------------------------------------------+-----------------+-------------------+
1853 | *regularization_type* | string dataset | "total_variation" |
1854 +----------------------------------------------+-----------------+-------------------+
1855 | *regularization_parameter* | float dataset | |
1856 +----------------------------------------------+-----------------+-------------------+
1857 | *step_size* | float dataset | 0.3 |
1858 +----------------------------------------------+-----------------+-------------------+
1859 | *sampling_step_size* | float dataset | 0.2 |
1860 +----------------------------------------------+-----------------+-------------------+
1861
1862 Table: Algorithm Group Members
1863
1864 name
1865 |
1866 | Reconstruction method name: SART, EM, FBP.
1867
1868 version
1869 |
1870 | Algorithm version.
1871
1872 implementation
1873 |
1874 | CPU or GPU.
1875
1876 number_of_nodes
1877 |
1878 | Number of nodes to use on cluster. This parameter is set when the reconstruction is parallelized and run on a cluster.
1879
1880 type
1881 |
1882 | Tomography reconstruction method: iterative.
1883
1884 stop_condition
1885 |
1886 | iteration_max, projection_threshold, difference_threshold_percent, difference_threshold_value.
1887
1888 iteration_max
1889 |
1890 | Maximum number of iterations.
1891
1892 projection_threshold
1893 |
1894 | The threshold of projection difference to stop the iterations as
1895
1896 .. math:: | y - Ax_{\mathrm{n}}| < p
1897
1898 difference_threshold_percent
1899 |
1900 | The threshold of reconstruction difference to stop the iterations as
1901
1902 .. math:: | x_{\mathrm{n+1}}|/ |x_{\mathrm{n}}| < p
1903
1904 difference_threshold_value
1905 |
1906 | The threshold of reconstruction difference to stop the iterations as:
1907
1908 .. math:: | x_{\mathrm{n+1}}| - |x_{\mathrm{n}}| < p
1909
1910 regularization_type
1911 |
1912 | total_variation, none.
1913
1914 regularization_parameter
1915 |
1916 |
1917
1918 step_size
1919 |
1920 | Step size between iterations in iterative methods
1921
1922 sampling_step_size
1923 |
1924 | Step size used for forward projection calculation in iterative methods.
1925
1926
1927 *algorithm* (SLS analytic)
1928 ^^^^^^^^^^^^^^^^^^^^^^^^^^
1929
1930 The Algorithm group contains information required to run a tomography
1931 reconstruction algorithm.
1932
1933 +----------------------------------------------+-----------------+-------------------+
1934 | Member | Type | Example |
1935 +==============================================+=================+===================+
1936 | name | string dataset | "gridrec" |
1937 +----------------------------------------------+-----------------+-------------------+
1938 | version | string dataset | "1.0" |
1939 +----------------------------------------------+-----------------+-------------------+
1940 | implementation | string dataset | "CPU" |
1941 +----------------------------------------------+-----------------+-------------------+
1942 | number_of_nodes | int dataset | 16 |
1943 +----------------------------------------------+-----------------+-------------------+
1944 | type | string dataset | "analytic" |
1945 +----------------------------------------------+-----------------+-------------------+
1946 | filter | string dataset | "Parzen" |
1947 +----------------------------------------------+-----------------+-------------------+
1948 | padding | float dataset | 0.50 |
1949 +----------------------------------------------+-----------------+-------------------+
1950
1951 Table: Algorithm Group Members
1952
1953 name
1954 |
1955 | Reconstruction method name: GridRec.
1956
1957 version
1958 |
1959 | Algorithm version.
1960
1961 implementation
1962 |
1963 | CPU or GPU.
1964
1965 number_of_nodes
1966 |
1967 | Number of nodes to use on cluster. This parameter is set when the reconstruction is parallelized and run on a cluster.
1968
1969 type
1970 |
1971 | Tomography reconstruction method: analytic.
1972
1973 filter
1974 |
1975 | Filter type.
1976
1977 padding
1978
1979
1980 .. _transfer:
1981
1982 *transfer*
1983 ----------
1984
1985 The transfer process description group contains metadata required
1986 to trasfer data from source (data analysis machine) to destination
1987 (data distribution server).
1988
1989 +-------------------------------------+------------------------------------+---------------------------------------------+
1990 | Member | Type | Example |
1991 +=====================================+====================================+=============================================+
1992 | *name* | string dataset | "Globus" |
1993 +-------------------------------------+------------------------------------+---------------------------------------------+
1994 | *description* | string dataset | "data distribution to users" |
1995 +-------------------------------------+------------------------------------+---------------------------------------------+
1996 | *version* | string dataset | https://github.com/globus/b9ad87e17 |
1997 +-------------------------------------+------------------------------------+---------------------------------------------+
1998 | *input_data* | string dataset | "gsiftp://host1/path" |
1999 +-------------------------------------+------------------------------------+---------------------------------------------+
2000 | *output_data* | string dataset | "gsiftp://host2/path" |
2001 +-------------------------------------+------------------------------------+---------------------------------------------+
2002 | *setup* | group | |
2003 +-------------------------------------+------------------------------------+---------------------------------------------+
2004
2005
2006 Table: Transfer Actor Group Members
2007
2008 name
2009 |
2010 | Descriptive actor task.
2011
2012 description
2013 |
2014 | Description of the actor task.
2015
2016 version
2017 |
2018 | Version of the actor task.
2019 |
2020 | If available this can be the repository link to the actor version used
2021 | https://github.com/globus/b9ad87e17
2022
2023 input_data, output_data
2024 |
2025 | Origin and destination of the data processed by the trasnfer task.
2026
2027 setup
2028 |
2029 | Group containing the specific data transfer protocol paramenters.
2030
2031
2032 .. table:
2033
2034 *table*
2035 -------
2036
2037 Scientific users will not generally be expected to maintain data in this
2038 group. The expectation is that analysis pipeline tools will
2039 automatically record process steps using this group. In addition, it is
2040 possible to re-run an analysis using the information provided here.
2041
2042 +---------------+-------------------+-------------------+---------------+----------------------------+-------------------------------+--------------------------+
2043 | actor | start_time | end_time | status | message | reference | description |
2044 +===============+===================+===================+===============+============================+===============================+==========================+
2045 | acquisition | 21:15:22 | 21:15:23 | FAILED | beamline off line | /process/acquisition | raw data collection |
2046 +---------------+-------------------+-------------------+---------------+----------------------------+-------------------------------+--------------------------+
2047 | acquisition | 21:15:26 | 21:15:27 | FAILED | beamline off line | /process/acquisition | raw data collection |
2048 +---------------+-------------------+-------------------+---------------+----------------------------+-------------------------------+--------------------------+
2049 | acquisition | 21:17:28 | 22:15:22 | SUCCESS | OK | /process/acquisition | raw data collection |
2050 +---------------+-------------------+-------------------+---------------+----------------------------+-------------------------------+--------------------------+
2051 | tomo_rec | 22:30:23 | 22:50:22 | SUCCESS | OK | /process/tomo_rec | reconstruct |
2052 +---------------+-------------------+-------------------+---------------+----------------------------+-------------------------------+--------------------------+
2053 | transfer | | | QUEUED | | /process/transfer | transfer data to user |
2054 +---------------+-------------------+-------------------+---------------+----------------------------+-------------------------------+--------------------------+
2055
2056 Table: Process table to log actors activity
2057
2058 actor
2059 |
2060 | Name of the process in the pipeline stage that is executed at this step.
2061
2062 *start_time*
2063 |
2064 | Time the process started.
2065
2066 *end_time*
2067 |
2068 | TIme the process ended.
2069
2070 *status*
2071 |
2072 | Current process status. May be one of the following: QUEUED,
2073 | RUNNING, FAILED, or SUCCESS.
2074
2075 *message*
2076 |
2077 | A process specific message generated by the process. It may be a
2078 | confirmation that the process was successful, or a detailed error
2079 | message, for example.
2080
2081 *reference*
2082 |
2083 | Path to the actor description group. The process description group
2084 | contains all metadata to perform the specific process. This
2085 | reference is simply the HDF5 path within this file of the
2086 | technique specific process description group. The process
2087 | description group should contain all parameters necessary to run
2088 | the process, including the name and version of any external
2089 | analysis tool used to process the data. It should also contain
2090 | input and output references that point to the
2091 | **exchange_N** groups that contain the input and output
2092 | datasets of the process.
2093
2094 *description*
2095 |
2096 | Process description.