Ignore:
Timestamp:
Dec 29, 2012 12:52:14 AM (9 years ago)
Author:
prjemian
Message:

Building out the docs for the specification of the standard. Work still in progress.

File:
1 edited

Legend:

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

    r267 r282  
    11.. $Id$ 
    22 
    3 .. _structure: 
     3.. _framework overview: 
    44 
    55================================================== 
    6 Structure of the canSAS2012 data format 
     6Overview of the canSAS2012 data format 
    77================================================== 
    88 
     
    1717============== 
    1818 
     19Describe the structure of data to be presented for small-angle scattering analysis. 
     20Make the structure sufficiently general that it may be used for analysis of any form 
     21of reduced SAS data. 
     22 
     23The hierarchical structure of the canSAS standard has been designed to be  
     24compatible with the NeXus data format. 
     25 
    1926Description 
    2027============== 
    2128 
     29Absolute minimum requirement for analysis of SAS data 
     30------------------------------------------------------- 
     31 
     32The *least* amount of information necessary for meaningful  
     33small-angle scattering analysis is the presentation of  
     34the :math:`I(Q)` SAS data.  In the canSAS standard, 
     35this data is presented within  
     36a *SASdata* group (holding the data from a single experiment),  
     37inside of *SASentry* group (holding the data from a single sample), 
     38inside of a *SASroot* group (holding one or more experiments). 
     39 
     40.. note:: It is recommended to store more metadata than this absolute minimum standard shows. 
     41   See the section :ref:`minimum recommended content` for more details. 
    2242 
    2343.. figure:: graphics/2012-minimum.png 
    24     :alt: Absolute minimum requirement for analysis of SAS data  
    25  
    26     Absolute minimum requirement for analysis of SAS data . 
    27  
     44 
     45    Absolute minimum requirement for analysis of SAS data. 
     46     
     47Alternatively, this may be shown using a more condensed :ref:`notation <notation>`, as: 
     48 
     49.. code-block:: text 
     50  :linenos: 
     51   
     52  SASroot 
     53    SASentry 
     54      SASdata 
     55        @Q_indices=0 
     56        @I_axes="Q" 
     57        I: float[] 
     58        Q: float[] 
     59 
     60.. _minimum recommended content: 
     61 
     62Minimum content recommended for reduced SAS data 
     63-------------------------------------------------- 
     64 
     65It is recommended that instruments provide at least the information described  
     66in this section to satisfy the needs of data analysis and visualization software. 
    2867 
    2968.. figure:: graphics/2012-recommended-minimum.png 
    30     :alt: Minimum content recommended for reduced SAS data 
    3169 
    3270    Minimum content recommended for reduced SAS data. 
    3371 
     72.. code-block:: text 
     73  :linenos: 
     74   
     75  SASroot 
     76    SASentry 
     77      Title: string 
     78      SASdata 
     79        @Q_indices=0 
     80        @I_axes="Q" 
     81        I: float[] 
     82        Q: float[] 
     83        probe_type: string 
     84        wavelength: float (or possibly float[]) 
     85        Idev: float[] 
     86        Qdev: float[] 
     87        SASnote 
     88          anything: string, float, float[], ... 
     89      SASsample 
     90        name: string 
     91         
     92-------------- 
     93 
     94.. caution:: re-write from this point downward on this page 
    3495 
    3596Terms 
     
    3899.. index:: ! SASroot 
    39100        groups; SASroot 
     101         
     102.. sidebar:: TODO! 
     103 
     104        break this up into tables for each group 
    40105 
    41106**SASroot**: 
     
    107172                        use attributes similar to ``@Mask_indices`` (such as ``@Temperature_indices`` 
    108173                        or ``@Pressure_indices``). 
     174                 
     175                **SASsample**: 
     176                        derived from original 1D format, content and attributes have changed 
     177                         
     178                        .. caution:: needs full write-up 
     179 
     180                .. index:: ! Title 
     181 
     182                **Title**: 
     183                        (string) Title of this *SASentry*.   
     184                        Optional attribute:  *name={short-Run-identifier}*. 
     185                        Example:: 
     186                         
     187                                Glassy Carbon C4 12keV 
    109188 
    110189 
     
    132211        Unidata UDunits 
    133212        UDunits 
     213 
     214.. _units: 
    134215 
    135216:@units: (required for all numerical objects)  
     
    152233The **names** for data objects should follow a standard  
    153234convention that starts with a letter (upper or lower case) and  
    154 then letters, numbers, and "_". The length of the name is limited  
    155 to no more than 63 characters (imposed by the rule HDF5 for names). 
    156  
    157 This standard convention may be described by the regular expression:: 
    158  
    159         [A-Za-z][\\w_]*  
     235then a sequence composed of letters, numbers, and/or "_".  
     236The length of the name is limited  
     237to no more than 63 characters (imposed by the HDF5 rule for names). 
     238 
     239        .. index:: ! naming standard; regular expression 
     240         
     241        This standard convention for object names may be  
     242        described by this regular expression:: 
     243         
     244                [A-Za-z][\\w_]*  
    160245 
    161246 
     
    190275 
    191276 
    192 .. [#data_object] Such as an array or scalar or text. HDF5 calls this a *dataset*,    
     277.. [#data_object] Such as text, a scalar, or an array. HDF5 calls this a *dataset*,    
    193278        Not a folder or a group or an object that contain other objects. 
    194279.. _Unidata UDunits: http://www.unidata.ucar.edu/software/udunits/udunits-2-units.html 
Note: See TracChangeset for help on using the changeset viewer.