Changeset 227 for canSAS2012


Ignore:
Timestamp:
Aug 2, 2012 10:15:36 PM (7 years ago)
Author:
prjemian
Message:

re-arrange the examples and start adding content to the structural parts.

Location:
canSAS2012/docs/source
Files:
2 added
5 edited

Legend:

Unmodified
Added
Removed
  • canSAS2012/docs/source/contents.rst

    r226 r227  
    1414   examples 
    1515 
     16About this documentation 
     17======================== 
     18 
     19This documentation was prepared using Sphinx (see the link at the bottom of every HTML page 
     20or browse to http://sphinx.pocoo.org).  The source of this documentation is in the canSAS  
     21subversion repository, available for world-readable checkout:: 
     22 
     23        svn co http://svn.smallangles.net/svn/canSAS/canSAS2012 ./canSAS2012 
     24 
     25Look in the ``docs/source`` directory for the source code files. 
     26 
    1627 
    1728.. rubric:: Index 
  • canSAS2012/docs/source/examples.rst

    r226 r227  
    22 
    33.. _examples: 
    4  
    5 .. TODO: reorganize this as I(Q), then I(Q,t), then ... 
    64 
    75================================================== 
     
    97================================================== 
    108 
    11 Describe, in general, the examples.  Explain how they were created and  
    12 what assumptions were involved. 
    13  
    14 .. rubric: List of key Examples 
    15  
    16 * `minimum recommended 1-D example`_ 
    17  
    18  
    19 .. _1-D Examples: 
    20  
    21 1-D Examples 
    22 ========================== 
    23  
    24 simple 1D SAS data: :math:`I(Q)` 
    25 --------------------------------------------------------------------------------------------------- 
     9.. sidebar:: TODO:  
     10 
     11        Describe, in general, the examples.  Explain how they were created and  
     12        what assumptions were involved. 
     13         
     14It is useful to express the canSAS2012 data structure in terms of some common  
     15data models used for the analysis of small-angle scattering data.  These models 
     16describe some common data structures in use for current SAS data.  Later models  
     17describe various possibilities for data in which many parameters are varied. 
     18 
     19The models start first with :math:`I(Q)` data for 1-D and 2-D SAS, then show 
     20the effect of time-dependent data, and then add additional complexities. 
     21 
     22A few key example models have been identified, as shown next. 
     23 
     24.. rubric:: List of key Examples 
     25 
     26* `minimum recommended 1-D I(Q)`_ 
     27* `generic 2-D I(Q)`_ 
     28* `simple 2-D (image) I(Q)`_ 
     29* `1D SAS data in a time series I(t,Q)`_ 
     30 
     31 
     32 
     33:math:`I(Q)` models 
     34============================= 
     35 
     36.. _minimum recommended 1-d I(Q): 
     37 
     381-D :math:`I(Q)` 
     39---------------- 
     40 
     41.. sidebar::  Compare... 
     42 
     43        This model could describe data stored in the the canSAS1d/1.0 format (with the addition of  
     44        *uncertainty* data and some additional metadata). 
     45 
     46 
     47Examples: 
     48:download:`HDF5 <../../examples/hdf5/simpleexamplefile.h5>` 
     49:download:`XML <../../examples/xml/simpleexamplefile.xml>`  
    2650 
    2751.. code-block:: text 
     
    3458                                @I_axes="Q" 
    3559                                I: float[100] 
    36                                 Q: float[100] 
    37  
    38 Examples:  :download:`XML <../../examples/xml/simpleexamplefile.xml>`   :download:`HDF5 <../../examples/hdf5/simpleexamplefile.h5>` 
    39  
    40 An implementation of this structure in XML using the minimum recommended metadata is: 
    41  
    42         .. _minimum recommended 1-D example: 
    43         .. rubric:  1-D example using (the intensity standard) glassy carbon data and the minimum recommended metadata 
    44         .. literalinclude:: example-1d.xml 
    45             :tab-width: 4 
    46             :linenos: 
    47             :language: xml 
    48  
    49 simple 1D SAS data in a time series: :math:`I(Q, t)` 
    50 --------------------------------------------------------------------------------------------------- 
    51  
    52 .. code-block:: text 
    53         :linenos: 
    54          
    55         SASroot 
    56                 SASentry 
    57                         SASdata 
    58                                 @Q_indices=1 
    59                                 @I_axes="Time,Q" 
    60                                 I: float[nTime,100] 
    61                                 Q: float[100] 
    62                                 Time: float[nTime] 
    63  
    64 Examples:  :download:`XML <../../examples/xml/simple1dtimeseries.xml>`  :download:`HDF5 <../../examples/hdf5/simple1dtimeseries.h5>` 
    65  
    66 generic 1D SAS data in a time series: :math:`I(Q(t), t)` 
    67 --------------------------------------------------------------------------------------------------- 
    68  
    69 This example is slightly more complex, showing data where :math:`Q` is also time-dependent. 
    70  
    71 .. code-block:: text 
    72         :linenos: 
    73                  
    74         SASroot 
    75                 SASentry 
    76                         SASdata 
    77                                 @Q_indices=0,1 
    78                                 @I_axes="Time,Q" 
    79                                 I: float[nTime,100] 
    80                                 Q: float[nTime,100] 
    81                                 Time: float[nTime] 
    82  
    83  
    84 .. _2-D Examples: 
    85  
    86 2-D Examples 
    87 ========================= 
    88  
    89 simple 2D (image) SAS data: :math:`I(Q)` 
    90 --------------------------------------------------------------------------------------------------- 
     60                                Q: float[100]    
     61 
     62 
     63An XML implementation of this structure using the minimum recommended  
     64set of metadata (:math:`I(Q)\pm\sigma(Q)`, title, wavelength,  
     65radiation probe type, some text of historical value, and some basic  
     66sample information) is shown :download:`here <example-1d.xml>` using  
     67the 1-D (intensity standard) glassy carbon data. 
     68 
     69.. note:: For clarity, the other possible metadata has been left out  
     70                from the remainder of the examples here. 
     71 
     72 
     73.. _simple 2-D (image) I(Q): 
     74 
     752-D image 
     76--------- 
     77 
     78Examples:        
     79:download:`HDF5 <../../examples/hdf5/simple2dcase.h5>` 
     80:download:`XML <../../examples/xml/simple2dcase.xml>`  
    9181 
    9282.. code-block:: text 
     
    10393                                Qx: float[100, 512] 
    10494 
    105 Examples:  :download:`XML <../../examples/xml/simple2dcase.xml>`        :download:`HDF5 <../../examples/hdf5/simple2dcase.h5>` 
    106  
    107 simple masked 2D (image) SAS data: :math:`I(Q)` 
    108 --------------------------------------------------------------------------------------------------- 
     952-D SAS/WAS images 
     96------------------ 
     97 
     98Consider the multi-technique experiment that produces  
     99small-angle and wide-angle scattering data images.   
     100The reduced data results in images as well.   
     101Each image might be described separately (see the model for SAS using  
     102`several detectors`_  for an alternative).   
     103Here the SAS data image is 100 x 512 pixels.   
     104The WAS data (not covered by this canSAS standard) is 256 x 256 pixels. 
     105 
     106.. code-block:: text 
     107        :linenos: 
     108                 
     109        SASroot 
     110                SASentry 
     111                        SASdata 
     112                                @name="sasdata" 
     113                                @Q_indices=0,1 
     114                                @I_axes="Q,Q" 
     115                                I: float[100, 512] 
     116                                Qx: float[100, 512] 
     117                                Qy: float[100, 512] 
     118                                Qz: float[100, 512] 
     119                        SASdata 
     120                                @name="wasdata" 
     121                                @Q_indices=0,1 
     122                                @I_axes="Q,Q" 
     123                                I: float[256, 256] 
     124                                Qx: float[256, 256] 
     125                                Qy: float[256, 256] 
     126                                Qz: float[256, 256] 
     127 
     1282-D masked image 
     129---------------- 
     130 
     131Examples:        
     132:download:`HDF5 <../../examples/hdf5/simple2dmaskedcase.h5>` 
     133:download:`XML <../../examples/xml/simple2dmaskedcase.xml>`  
    109134 
    110135.. code-block:: text 
     
    123148                                Mask: int[100, 512] 
    124149 
    125 Examples:  :download:`XML <../../examples/xml/simple2dmaskedcase.xml>`  :download:`HDF5 <../../examples/hdf5/simple2dmaskedcase.h5>` 
    126  
    127 generic 2D SAS data: :math:`I(Q)` 
    128 --------------------------------------------------------------------------------------------------- 
     150 
     151 
     152.. _generic 2-D I(Q): 
     153 
     1542-D generic :math:`I(Q)` 
     155------------------------ 
    129156 
    130157Could use this model, for example, to describe data from multiple detectors (by listing individual  
    131158pixels from all detectors retained after any masking).  Or, could describe data from one detector  
    132159of any geometry.  This is the most flexible. 
     160 
     161Examples:        
     162:download:`HDF5 <../../examples/hdf5/generic2dcase.h5>` 
     163:download:`XML <../../examples/xml/generic2dcase.xml>` 
    133164 
    134165.. code-block:: text 
     
    145176                                Qz: float[100*512] 
    146177 
    147 Examples:  :download:`XML <../../examples/xml/generic2dcase.xml>`       :download:`HDF5 <../../examples/hdf5/generic2dcase.h5>` 
    148  
    149 simple 2D SAS/WAS data: :math:`Isas(Q) & Iwas(Q)` 
    150 --------------------------------------------------------------------------------------------------- 
    151  
    152 Consider the multi-technique experiment that produces  
    153 small-angle and wide-angle scattering data images.   
    154 The reduced data results in images as well.   
    155 Each image might be described separately (see  
    156 ``[[2012_Data_Discussion_Examples#example_of_SAS_data_with_several_detectors.2C_I.28Q.29  
    157 | example of SAS data with several detectors]]`` for an alternative).   
    158 Here the SAS data image is 100 x 512 pixels.   
    159 The WAS data (not covered by this canSAS standard) is 256 x 256 pixels. 
    160  
    161 .. code-block:: text 
    162         :linenos: 
    163                  
    164         SASroot 
    165                 SASentry 
    166                         SASdata 
    167                                 @name="sasdata" 
    168                                 @Q_indices=0,1 
    169                                 @I_axes="Q,Q" 
    170                                 I: float[100, 512] 
    171                                 Qx: float[100, 512] 
    172                                 Qy: float[100, 512] 
    173                         SASdata 
    174                                 @name="wasdata" 
    175                                 @Q_indices=0,1 
    176                                 @I_axes="Q,Q" 
    177                                 I: float[256, 256] 
    178                                 Qx: float[256, 256] 
    179                                 Qy: float[256, 256] 
    180  
    181 2D SANS and 2D SAXS: :math:`I_n(Q) & I_x(Q)` 
    182 --------------------------------------------------------------------------------------------------- 
     1782-D SANS and SAXS 
     179----------------- 
    183180 
    184181Consider the multi-technique experiment that produces  
     
    199196                                Qx: float[100*512] 
    200197                                Qy: float[100*512] 
     198                                Qz: float[100*512] 
    201199                        SASdata 
    202200                                @name="saxs" 
     
    206204                                Qx: float[256*256] 
    207205                                Qy: float[256*256] 
    208  
    209 2D with additional varied parameters 
    210 ========================================== 
    211  
    212 generic 2D SAS data in a time series: :math:`I(Q,t)` 
    213 --------------------------------------------------------------------------------------------------- 
     206                                Qz: float[256*256] 
     207 
     208 
     209.. _several detectors: 
     210 
     211several detectors 
     212----------------- 
     213 
     214Here, the data are appended to a common ``I`` data object. 
     215This hypothetical case has reduced data derived from  
     216three detectors, :math:`I_a(Q)`, :math:`I_b(Q)`, and :math:`I_c(Q)`. 
     217Also, a certain number of pixels (``nDiscardedPixels``) have been discarded 
     218previously from the data for various reasons. 
     219         
     220        .. tip::  Typical data might have fewer useful pixels due to various 
     221                detector artifacts such as zingers, streaks, and dead spots, as well 
     222                as an applied intensity mask.  There is no need to write such useless pixels 
     223                to the data objects. 
     224 
     225        ==============  ========   ==================== 
     226        intensity       detector   shape 
     227        ==============  ========   ==================== 
     228        :math:`I_a(Q)`  2-D        100 x 512 pixels 
     229        :math:`I_b(Q)`  1-D        2000 pixels 
     230        :math:`I_c(Q)`  2-D        256 x 256 pixels 
     231        ==============  ========   ==================== 
     232 
     233        Data from a SAXS/MAXS/WAXS instrument might be represented thus. 
     234 
     235.. code-block:: text 
     236        :linenos: 
     237                 
     238        SASroot 
     239                SASentry 
     240                        SASdata 
     241                                @Q_indices=0 
     242                                @I_axes="Q" 
     243                                I: float[100*512  + 2000 + 256*256 - nDiscardedPixels] 
     244                                Qx: float[100*512 + 2000 + 256*256 - nDiscardedPixels] 
     245                                Qy: float[100*512 + 2000 + 256*256 - nDiscardedPixels] 
     246                                Qz: float[100*512 + 2000 + 256*256 - nDiscardedPixels] 
     247 
     248 
     249 
     250:math:`I(t,Q)` models with time-dependence 
     251========================================================== 
     252 
     2531-D :math:`I(t,Q)` 
     254------------------ 
     255 
     256Examples:   
     257:download:`HDF5 <../../examples/hdf5/simple1dtimeseries.h5>` 
     258:download:`XML <../../examples/xml/simple1dtimeseries.xml>`  
     259 
     260.. code-block:: text 
     261        :linenos: 
     262         
     263        SASroot 
     264                SASentry 
     265                        SASdata 
     266                                @Q_indices=1 
     267                                @I_axes="Time,Q" 
     268                                I: float[nTime,100] 
     269                                Q: float[100] 
     270                                Time: float[nTime]       
     271 
     272.. _1D SAS data in a time series I(t,Q): 
     273 
     2741-D :math:`I(t,Q(t))` 
     275---------------------------------------- 
     276 
     277This example is slightly more complex, showing data where :math:`Q` is also time-dependent. 
     278 
     279.. code-block:: text 
     280        :linenos: 
     281                 
     282        SASroot 
     283                SASentry 
     284                        SASdata 
     285                                @Q_indices=0,1 
     286                                @I_axes="Time,Q" 
     287                                I: float[nTime,100] 
     288                                Q: float[nTime,100] 
     289                                Time: float[nTime] 
     290 
     291 
     2922-D :math:`I(t,Q)` 
     293------------------- 
     294 
     295Examples:  
     296:download:`HDF5 <../../examples/hdf5/generic2dtimeseries.h5>` 
     297:download:`XML <../../examples/xml/generic2dtimeseries.xml>` 
    214298 
    215299.. code-block:: text 
     
    227311                                Time: float[nTime] 
    228312 
    229 Examples:  :download:`XML <../../examples/xml/generic2dtimeseries.xml>`         :download:`HDF5 <../../examples/hdf5/generic2dtimeseries.h5>` 
    230  
    231 generic 2D SAS data in a time series: :math:`I(Q(t),t)` 
    232 --------------------------------------------------------------------------------------------------- 
     313.. _2-D I(t,Q(t)): 
     314 
     3152-D :math:`I(t,Q(t))` 
     316--------------------- 
    233317 
    234318This example is slightly more complex, showing data where :math:`Q` is also time-dependent. 
     
    248332                                Time: float[nTime] 
    249333 
    250 2D SAS data as images in a time series with a time-independent mask: :math:`I(Q(t),t)` 
    251 ------------------------------------------------------------------------------------------------------- 
    252  
    253 This example explores a bit of complexity added to the previous example. 
     334.. _2-D.time-dependent.masked.image: 
     335 
     3362-D :math:`I(t,Q(t))` masked image 
     337----------------------------------------- 
     338 
     339This example explores a bit more complexity, adding a mask that is time-dependent. 
    254340 
    255341.. code-block:: text 
     
    269355                                Mask: int[100,512] 
    270356 
    271 generic 2D SAS data in a time, T, & P series: :math:`I(t,T,P,Q(t,T,P))` 
    272 --------------------------------------------------------------------------------------------------- 
    273  
    274 Complex case where all :math:`Q` values are different for each of time, temperature, and pressure. 
     357 
     358 
     359models with several varied parameters 
     360===================================== 
     361 
     3622-D :math:`I(t,T,P,Q(t,T,P))` 
     363----------------------------- 
     364 
     365Complex case of :math:`I(t,T,P,Q(t,T,P))` 
     366where all :math:`Q` values are different for each combination of time, temperature, and pressure. 
     367 
     368Examples:   
     369:download:`HDF5 <../../examples/hdf5/generic2dtimetpseries.h5>` 
     370:download:`XML <../../examples/xml/generic2dtimetpseries.xml>`   
    275371 
    276372.. code-block:: text 
     
    290386                                P: float[nPressure] 
    291387 
    292 Examples:  :download:`XML <../../examples/xml/generic2dtimetpseries.xml>`       :download:`HDF5 <../../examples/hdf5/generic2dtimetpseries.h5>` 
    293  
    294 generic 2D SAS data (images) in a time, T, & P series: :math:`I(T,t,P,Q(t))` 
    295 --------------------------------------------------------------------------------------------------- 
    296  
    297 Slightly less complex than previous, where :math:`Q` only depends on time. 
     388.. _2-D.images.with.varied.T.t.P: 
     389 
     3902-D  :math:`I(T,t,P,Q(t))` images 
     391--------------------------------- 
     392 
     393Slightly less complex than previous, now :math:`I(T,t,P,Q(t))` 
     394where :math:`Q` only depends on time. 
    298395 
    299396.. code-block:: text 
     
    313410                                Pressure: float[nPressure] 
    314411 
    315 SAS data with several detectors: :math:`I(Q)` 
    316 --------------------------------------------------------------------------------------------------- 
    317  
    318 Here, the data are appended to common data objects. 
    319 This hypothetical case has reduced data derived from  
    320 three detectors, Ia(Q), Ib(Q), and Ic(Q): 
    321 * Ia(Q) is derived from a 2D detector (100 x 512 pixels) 
    322 * Ib(Q) is derived from a 1D detector (2000 pixels) 
    323 * Ic(Q) is derived from a 2D detector (256 x 256 pixels) 
    324  
    325 Data from a SAXS/MAXS/WAXS instrument might be represented thus. 
    326  
    327 .. code-block:: text 
    328         :linenos: 
    329                  
    330         SASroot 
    331                 SASentry 
    332                         SASdata 
    333                                 @Q_indices=0 
    334                                 @I_axes="Q" 
    335                                 I: float[100*512  + 2000 + 256*256] 
    336                                 Qx: float[100*512 + 2000 + 256*256] 
    337                                 Qy: float[100*512 + 2000 + 256*256] 
    338                                 Qz: float[100*512 + 2000 + 256*256] 
    339  
    340 ---------- 
     412 
    341413 
    342414.. TODO: Could make this a note 
    343415 
    344 Invalid Case 
    345 ====================== 
    346  
    347 Over-simplified 2D (image) SAS data: :math:`I(Q)` 
    348 --------------------------------------------------------------------------------------------------- 
    349  
    350 Invalid because the method of addressing the Q values  
    351 is different from all the above. 
     416Unhandled Cases 
     417=============== 
     418 
     4192-D image with :math:`Q_x` & :math:`Q_y` vectors 
     420------------------------------------------------------------------------- 
     421 
     422This model is outside the scope of this format.  The method of addressing  
     423the :math:`Q` values is different than for the other models. 
     424 
     425.. Is this really true? 
     426.. This usage seems quite common and should be able to be handled. 
    352427 
    353428.. code-block:: text 
     
    363438                                Qy: float[512] 
    364439 
    365  
    366 Terms 
    367 =============== 
    368  
    369 SASroot: 
    370         same use as original 1D format 
    371 SASentry: 
    372         some changes from the original 1D format 
    373  
    374         needs a ''version'' attribute that describes the version of the  
    375         canSAS definition of SASentry.  Use: ``version="1.0"`` 
    376  
    377 SASdata: 
    378         different use from original 1D format, refers to a single 
    379         reduced data set that can be represented thus (such as 
    380         from one detector) 
    381  
    382         :attribute I_axes: Comma-separated list that describes the names  
    383                                                         of the data objects that correspond to the  
    384                                                         indices of the ``I`` data object.  Such as:: 
    385                                                          
    386                                                                 @I_axes="Temperature,Time,Pressure,Q,Q" 
    387         :attribute Q_indices: Array that describes which indices  
    388                                                         (of the :math:`I` data object) are used to  
    389                                                         reference the ``Q`` data object. The items in this array  
    390                                                         use zero-based indexing.  Such as:: 
    391                                                          
    392                                                                 @Q_indices=1,3,4 
    393                                                          
    394                                                         which indicates that Q requires three indices 
    395                                                         from the :math:`I` data object: one for time and 
    396                                                         two for Q position.  
    397         :attribute Mask_indices: Array that describes which indices 
    398                                                         (of the :math:`I` data object) are used to  
    399                                                         reference the ``Mask`` data object.  The items in this 
    400                                                         array use zero-based indexing.  Such as:: 
    401                                                          
    402                                                                 @Mask_indices=3,4 
    403                                                          
    404                                                         which indicates that Q requires two indices 
    405                                                         from the :math:`I` data object for Q position.  
    406          
    407         To indicate the dependency relationships of other varied parameters,  
    408         use attributes similar to ``@Mask_indices`` (such as ``@Temperature_indices`` 
    409         or ``@Pressure_indices``). 
    410  
    411 .. 
    412         SASdata has some possible attributes, as shown in this example: 
    413          
    414         <pre> 
    415         @Q_indices=1,3,4 
    416         @I_axes="Temperature,Time,Pressure,Q,Q" 
    417         @Mask_indices=3,4 
    418         </pre> 
    419          
    420         To indicate the dependency relationships of other varied parameters, use attributes similar to ''@Mask_indices'' (such as ''@Temperature_indices'' or ''@Pressure_indices''). 
    421          
    422         === @Q_indices === 
    423         Array attribute that describes which indices (of the I data object) are used to reference Q. 
    424         The items in this array use zero-based indexing. 
    425          
    426         === @I_axes === 
    427         Comma-separated list that describes the names of the data objects that correspond to the indices of the I object. 
    428          
    429         === @Mask_indices === 
    430         Array attribute that describes which indices (of the I data object) are used to reference Mask. 
    431         The items in this array use zero-based indexing. 
    432  
    433 Algorithm for Software to Read Data files Written with this Structure 
    434 ====================================================================== 
    435  
    436 to be written 
    437  
    438 .. 
    439         Contents: 
    440          
    441         .. toctree:: 
    442            :maxdepth: 2 
    443  
    444 .. 
    445         .. code-block:: text 
    446             :linenos: 
    447  
    448         .. literalinclude:: ../markup_example/hkl_ioc.mac.original 
    449             :tab-width: 4 
    450             :linenos: 
    451             :language: guess 
    452  
    453         .. figure:: example1.png 
    454             :alt: view of original hkl_ioc.mac HTML documentation 
    455          
    456             Documentation of the original **hkl_ioc.mac** file. 
    457  
    458  
     440Instead, use either the model titled:  
     441`2-D image <simple 2-D (image) I(Q)>`_ 
     442or `2-D generic data <generic 2-D I(Q)>`_ (preferred). 
  • canSAS2012/docs/source/framework.rst

    r226 r227  
    1414Description 
    1515============== 
     16 
     17 
     18.. figure:: 2012-minimum.png 
     19    :alt: Absolute minimum requirement for analysis of SAS data  
     20 
     21    Absolute minimum requirement for analysis of SAS data . 
     22 
     23 
     24.. figure:: 2012-recommended-minimum.png 
     25    :alt: Minimum content recommended for reduced SAS data 
     26 
     27    Minimum content recommended for reduced SAS data. 
     28 
     29 
     30Terms 
     31=============== 
     32 
     33.. index:: ! SASroot 
     34        groups; SASroot 
     35 
     36**SASroot**: 
     37        derived from original 1D format, attributes have changed 
     38         
     39        .. caution:: needs full write-up 
     40 
     41        .. index:: ! SASentry 
     42                groups; SASentry 
     43         
     44        **SASentry**: 
     45                derived from original 1D format, content and attributes have changed 
     46                 
     47                .. caution:: needs full write-up 
     48                 
     49                *SASentry* groups have several attributes: 
     50         
     51                :@name: Text that describes this group. 
     52                                        Must conform to the `naming standard <naming standard>`  
     53                                        and must be unique within a *SASentry* group.  Such as:: 
     54                                         
     55                                                @name="sasentry01" 
     56                :@version: Describes the version of the canSAS standard used to write this data. 
     57                                        This must be a text (not numerical) representation.  Such as:: 
     58                                         
     59                                                @version="1.0" 
     60 
     61                .. index:: ! SASdata 
     62                        groups; SASdata 
     63                 
     64                **SASdata**: 
     65                        different use from original 1D format, refers to a single 
     66                        reduced data set that can be represented thus (such as 
     67                        from one detector) 
     68                         
     69                        *SASdata* groups have several attributes: 
     70                 
     71                        :@name: Text that describes this group. 
     72                                                Must be unique within a SASentry group.  Such as:: 
     73                                                 
     74                                                        @name="sasdata01" 
     75                 
     76                        :@I_axes: Comma-separated list that describes the names  
     77                                                of the data objects that correspond to the  
     78                                                indices of the ``I`` data object.  Such as:: 
     79                                                 
     80                                                        @I_axes="Temperature,Time,Pressure,Q,Q" 
     81                        :@Q_indices: Array that describes which indices  
     82                                                (of the :math:`I` data object) are used to  
     83                                                reference the ``Q`` data object. The items in this array  
     84                                                use zero-based indexing.  Such as:: 
     85                                                 
     86                                                        @Q_indices=1,3,4 
     87                                                 
     88                                                which indicates that Q requires three indices 
     89                                                from the :math:`I` data object: one for time and 
     90                                                two for Q position.  
     91                        :@Mask_indices: Array that describes which indices 
     92                                                (of the :math:`I` data object) are used to  
     93                                                reference the ``Mask`` data object.  The items in this 
     94                                                array use zero-based indexing.  Such as:: 
     95                                                 
     96                                                        @Mask_indices=3,4 
     97                                                 
     98                                                which indicates that Q requires two indices 
     99                                                from the :math:`I` data object for Q position. 
     100 
     101                        To indicate the dependency relationships of other varied parameters,  
     102                        use attributes similar to ``@Mask_indices`` (such as ``@Temperature_indices`` 
     103                        or ``@Pressure_indices``). 
     104 
     105 
     106.. index:: ! data objects 
     107.. _data objects: 
     108 
     109Data Objects 
     110------------ 
     111 
     112Storage container [#data_object]_ with numerical data for analysis or any kind of metadata.   
     113All data objects have attributes, some required, some optional. 
     114The name chosen for each data object must adhere to the `naming standard`_ described below. 
     115 
     116:@size: (required for numerical arrays) Number of items in this data object.   
     117                        If the array is multi-dimensional, then the length of each index 
     118                        is reported individually, separated by commas.  Such as:: 
     119                         
     120                                size="100,512" 
     121                         
     122                        describes a 2-D array of 100 rows and 512 columns. 
     123                        Some implementations (such as HDF5 which uses *shape*) may provide  
     124                        native versions of the size.  Use the native capability, when present. 
     125 
     126.. index:: !units 
     127        Unidata UDunits 
     128        UDunits 
     129 
     130:@units: (required for all numerical objects)  
     131                        Engineering units of this data object.   
     132                        Use the `Unidata UDunits`_ [#UDunits]_  
     133                        specification as this is compatible with 
     134                        various community standards. 
     135 
     136.. index:: !uncertainty 
     137 
     138:@uncertainty: (optional for numerical arrays)  
     139                        Name of the data object (in this *SASdata* group) that 
     140                        provides the uncertainty to be used for data analysis. 
     141 
     142.. _naming standard: 
     143 
     144Naming Standard 
     145--------------- 
     146 
     147The **names** for data objects should follow a standard  
     148convention that starts with a letter (upper or lower case) and  
     149then letters, numbers, and "_". The length of the name is limited  
     150to no more than 63 characters (imposed by the rule HDF5 for names). 
     151 
     152This standard convention may be described by the regular expression:: 
     153 
     154        [A-Za-z][\\w_]*  
     155 
     156 
     157.. index:: ! uncertainty; supplemental 
     158.. _supplementary uncertainty: 
     159 
     160Supplementary Uncertainty Data 
     161------------------------------ 
     162 
     163A special case discussed at canSAS2012. 
     164 
     165Requires a named subdirectory below *SASdata* to contain the supplementary data. 
     166The name of the subdirectory is given in an attribute of the data object. 
     167 
     168 
     169 
     170 
     171 
    16172 
    17173Contents: 
     
    21177    
    22178   metadata 
     179 
     180 
     181--------------------------- 
     182 
     183.. rubric:: Footnotes 
     184 
     185 
     186 
     187.. [#data_object] Such as an array or scalar or text. HDF5 calls this a *dataset*,    
     188        Not a folder or a group or an object that contain other objects. 
     189.. _Unidata UDunits: http://www.unidata.ucar.edu/software/udunits/udunits-2-units.html 
     190.. [#UDunits] 
     191    The :index:`UDunits` specification also includes instructions for derived units. 
     192 
     193 
     194 
     195 
     196 
     197 
     198 
     199 
     200 
     201 
     202 
     203 
     204.. 
     205        Contents: 
     206         
     207        .. toctree:: 
     208           :maxdepth: 2 
     209 
     210.. Examples of reST structures that might be useful while writing this document 
     211 
     212        .. code-block:: text 
     213            :linenos: 
     214 
     215        .. literalinclude:: ../markup_example/hkl_ioc.mac.original 
     216            :tab-width: 4 
     217            :linenos: 
     218            :language: guess 
     219 
     220        .. figure:: example1.png 
     221            :alt: view of original hkl_ioc.mac HTML documentation 
     222         
     223            Documentation of the original **hkl_ioc.mac** file. 
     224 
     225 
  • canSAS2012/docs/source/implementation.rst

    r226 r227  
    2323 
    2424.. need to describe the algorithms and software to read this format 
     25 
     26 
     27 
     28Algorithm for Software to Read Data files Written with this Structure 
     29====================================================================== 
     30 
     31#. open the file and read the *SASroot* (or root-level) group. 
     32#. open each *SASentry* group: 
     33        #. verify the version attribute: must be "1.0" (a string) 
     34        #. note the *name* attribute, if present 
     35        #. note the title, if present 
     36        #. note the *SASsample* group contents, if present 
     37        #. open each *SASdata* group 
     38                #. note the *name* attribute, if present 
     39                #. read the *I_axes* attribute, it tells the names (in storage order) of the other data objects on which *I* depends. 
     40                #. read the *Q_indices* attribute, it tells which of the *I_axes* (zero-based numbering) have *Q* dependence 
     41                #. if present, read the *Mask_indices* attribute (similar to the ``Q_indices``), to get the dependencies of the ``Mask``. 
     42                #. read ``I`` data object as described below (see `Read a data object`_) 
     43                #. same for ``Q``, ``Qx``,  ``Qy``,  ``Qz`` data objects (if present) 
     44                #. same for the names in the *I_axes* attribute (except for *Q* since it was already handled) 
     45 
     46 
     47.. _Read a data object: 
     48.. rubric:: Read a data object 
     49 
     50#. read the *size* attribute, if present 
     51#. allocate memory for the object 
     52#. read the data object and its units 
     53#. if present, read the *uncertainty* attribute and read the named data object it describes 
     54 
     55 
     56 
     57Algorithm to Identify :math:`Q` values given a set of indices on the ``I`` data 
     58=============================================================================== 
     59 
     60Given an intensity data object (called ``I``), the algorithm to identify the associated 
     61``Q`` values with any given intensity datum is described here: 
     62 
     63#. Identify the given set of indices with the names of data objects 
     64        #. note the set of indices for the intensity datum 
     65        #. note the names of the various intensity axes from the ``I_axes`` attribute 
     66#. note the list of indices for *Q* as given by the ``Q_indices`` attribute 
     67#. ... this gets tedious without a couple examples... 
     68#. analyze how we do it below and finish writing this part 
     69 
     70.. caution:: This write-up is unfinished at this point.  Follow below for a few examples. 
     71 
     72simple time-series example 
     73-------------------------- 
     74 
     75.. sidebar:: Simplified example 
     76 
     77        To simplify our example, only the relevant metadata has 
     78        been left in this example. 
     79 
     80Consider the SAS data example including a time-series (same model as :ref:`2-D I(t,Q(t))`): 
     81 
     82        .. code-block:: text 
     83                :linenos: 
     84                 
     85                SASroot 
     86                  SASentry 
     87                    SASdata 
     88                      @name="sasdata01" 
     89                      @I_axes="Time,Q" 
     90                      @Q_indices=0,1 
     91                      Qx : float[4,35] 
     92                      Qy : float[4,35] 
     93                      Qz : float[4,35] 
     94                      I : float[4,35] 
     95                      Time : float[4] 
     96 
     97        #. The *I_axes* attribute describes a *Time* data object, in addition to some *Q* data.  The *Time* index is in the first position. 
     98        #. It also says that there is only one index to use (the second index on intensity) when looking up a :math:`Q` value. 
     99        #. Since there is no *Q* data object, there must be three data objects *Qx*, *Qy*, *Qz* that provide the scattering vector. 
     100        #. The *Q_indices* attribute indicates that the lookup of *Q* depends on both the *Time* (0) and *Q* (1) indices and that *Q* is time-dependent. 
     101        #. One index (position 0) is used to lookup the *Time* value. 
     102        #. index *i* is for *Time* and index *j* is for *Q*. 
     103         
     104        Given the indices ``i,j``, return all the data for this datum:: 
     105         
     106                Qx[i,j], Qy[i,j], Qz[i,j], Time[i], I[i,j] 
     107 
     108 
     109simple time-series example 
     110-------------------------- 
     111 
     112Consider the example of the 2-D time-dependent masked :ref:`image <2-D.time-dependent.masked.image>`. 
     113 
     114        Given the indices ``i,j,k``, return all values for this datum:: 
     115         
     116                Qx[i,j,k], Qy[i,j,k], Qz[i,j,k], Time[i], Mask[j,k], I[i,j,k] 
     117 
     118 
     119another example 
     120-------------------------- 
     121 
     122See the model for 2-D  :math:`I(T,t,P,Q(t))` :ref:`images <2-D.images.with.varied.T.t.P>`. 
     123 
     124        Given the indices ``i,j,k,l,m``, return all values for this datum:: 
     125         
     126                Qx[j,l,m], Qy[j,l,m], Qz[j,l,m], Temperature[i], Time[j], Pressure[k], I[i,j,k,l,m] 
     127 
     128 
     129 
     130 
  • canSAS2012/docs/source/index.rst

    r226 r227  
    3636 
    3737        The canSAS (Collective Action for Nomadic Small-Angle Scatterers) forum  
    38         met in Uppsala, Sweden in July 2012 to discuss standardization of the  
     38        met in Uppsala, Sweden in July 2012 [#]_ to discuss standardization of the  
    3939        storage of reduced small-angle scattering of any dimension to be considered  
    40         for analysis. 
     40        for analysis. [#]_ 
    4141         
    4242        This document describes the current specification as an  
     
    5555.. [#]  http://www.cansas.org 
    5656.. [#]  http://svn.smallangles.net/trac/canSAS/browser/1dwg/tags/v1.0/doc/cansas-1d-1_0-manual.pdf 
     57.. [#]  http://www.smallangles.net/wgwiki/index.php/canSAS-2012 
     58.. [#]  http://www.smallangles.net/wgwiki/index.php/2012_Data_Discussion 
Note: See TracChangeset for help on using the changeset viewer.