Changeset 267


Ignore:
Timestamp:
Nov 4, 2012 11:24:12 PM (7 years ago)
Author:
prjemian
Message:

re-arrange and add to SAS basics

Location:
canSAS2012
Files:
5 added
10 edited
4 moved

Legend:

Unmodified
Added
Removed
  • canSAS2012/.project

    r260 r267  
    33        <name>canSAS2012</name> 
    44        <comment>canSAS multi-dimensional data standard</comment> 
    5         <projects/> 
    6         <buildSpec/> 
    7         <natures/> 
     5        <projects> 
     6        </projects> 
     7        <buildSpec> 
     8                <buildCommand> 
     9                        <name>org.python.pydev.PyDevBuilder</name> 
     10                        <arguments> 
     11                        </arguments> 
     12                </buildCommand> 
     13        </buildSpec> 
     14        <natures> 
     15                <nature>org.python.pydev.pythonNature</nature> 
     16        </natures> 
    817</projectDescription> 
  • canSAS2012/docs/source/basics.rst

    r230 r267  
    22 
    33================================================== 
    4 Define the terms here 
     4Definitions 
    55================================================== 
    66 
    7 such as Q and the meaning of reduced data 
     7.. sidebar:: work in progress... 
     8 
     9        This document is under construction. 
     10        Many parts have yet to be written. 
     11 
     12For the general case of small-angle scattering data, all that is required is 
     13to have measurements of reduced intensity :math:`I` as a function scattering  
     14vector, :math:`Q`.  Some techniques may require additional information, such  
     15as wavelength. 
     16 
     17.. index:: ! reduced data 
     18 
     19.. _reduced data: 
     20 
     21Reduced Data 
     22========================= 
     23 
     24What is *reduced data*?  Consider this figure of the scientific workflow  
     25presented at the  
     26*2006 Advanced Photon Source Workshop on Scientific Software*  
     27(*ANL-APS-TB-51*, Argonne National Laboratory): 
     28         
     29        .. figure:: graphics/2006-10-09-scientific-workflow.jpg 
     30            :alt: scientific workflow 
     31            :height: 400 px 
     32 
     33.. note:: *Reduced data* is the data presented for analysis after all  
     34        instrument-specific artifacts and corrections have been applied. 
     35 
     36An *experiment* is constructed from a sequence of *measurements* by a scientific 
     37instrument.  Raw data from those measurements must be converted from the format  
     38received by components of the instrument (detectors, amplifiers, motors, encoders,  
     39thermocouples, etc.) into a form suitable for analysis particular  
     40to the scientific investigation.  Part of the conversion process involves the removal of 
     41artifacts and the correction of distortions of the signal by the measurement process 
     42(such as detector dead-time corrections or removal of dead pixels from an area  
     43detector image) and the combination of parameters describing the instrument configuration 
     44and even the possibility of an applied mask to remove parts of the measurement 
     45that contain no useful observations.   
     46The data that results after all these conversion steps have  
     47been applied is termed **reduced data**. 
     48 
     49In broad terms, the steps involved in the process of data reduction are  
     50particular to a specific scientific instrument as it existed at a specific  
     51time.  For many scientific instruments, such as those at large user facilities, 
     52it is not possible to generalize the process of data reduction and identify 
     53all the parameters necessary for data reduction in advance.   
     54         
     55.. note:: It is, and will always be, the responsibility of the instrument team  
     56        to provide the process of converting the data measurements into 
     57        **reduced data**. 
     58 
     59Requirements for Reduced SAS Data 
     60---------------------------------------------- 
     61 
     62The absolute minimum information required for the standard analysis  
     63of small-angle scattering measurements is intensity as a function of  
     64scattering vector, :math:`I(Q)`. 
     65 
     66:ref:`Intensity <I>` 
     67        is expressed in absolute units of cross-section  
     68        or in units directly convertible by a scaling constant 
     69 
     70:ref:`scattering vector <Q>` 
     71        is expressed as :ref:`scattering vector  
     72        magnitude <Q scalar>` (:math:`|Q|`)  
     73        or :ref:`scattering vector  <Q vector>` (:math:`\vec{Q}`) 
     74 
     75Some analyses may require additional information such as 
     76the estimation of experimental uncertainties, the 
     77wavelength and type of the radiation probe, 
     78or the instrumental resolution.  These should be provided, 
     79where possible.  Note that, for example, reduced SAS data does not 
     80*require* a number representing the distance from sample to detector as this 
     81common instrument-specific term has already been factored into the data  
     82reduction process. 
     83 
     84.. index:: ! Q 
     85 
     86.. _Q: 
     87 
     88Definition of :math:`Q` 
     89========================= 
     90 
     91:math:`Q` may be represented either as the magnitude of the scattering vector, 
     92:math:`|Q|` or by the three-dimensional scattering vector :math:`\vec{Q}`. 
     93When we write :math:`Q`, we may refer to either or both of :math:`|Q|`  
     94or :math:`\vec{Q}`,  depending on the context. 
     95 
     96.. _Q scalar: 
     97 
     98Q vector magnitude: :math:`|Q|=(4 \pi / \lambda) \sin(\theta)` 
     99------------------------------------------------------------------ 
     100 
     101        where :math:`\lambda` is the wavelength of the radiation, 
     102        and :math:`2\theta` is the angle through which the detected radiation has been scattered. 
     103        This is a one-dimensional reduction of the general case below. 
     104         
     105        .. _Q geometry: 
     106         
     107        .. figure:: graphics/Q-geometry.jpg 
     108            :alt: Q geometry 
     109            :height: 200 px 
     110             
     111            definition of :math:`|Q|` geometry for small-angle scattering 
     112 
     113 
     114 
     115.. _Q vector: 
     116 
     117Q vector: :math:`\vec{Q}=\vec{k'}-\vec{k}` 
     118---------------------------------------------- 
     119 
     120        where :math:`\vec{k}` is the wave vector of the incident radiation 
     121        and :math:`\vec{k'}` is the wave vector of the scattered radiation. 
     122        Here, :math:`\vec{k}` is a vector of magnitude :math:`2\pi/\lambda` 
     123        that points along the trajectory of the radiation. 
     124         
     125        .. _Q vector geometry: 
     126         
     127        .. figure:: graphics/q-vector.png 
     128            :alt: Q vector geometry 
     129            :height: 400 px 
     130             
     131            definition of :math:`\vec{Q}` geometry for small-angle scattering [#]_ 
     132 
     133.. [#] A hearty nod for this graphic is given to the guide: 
     134        **neutron scattering: A Primer**,  
     135        by Roger Pynn (LANSCE),  
     136        published in the Summer 1990 edition of *Los Alamos Science*. 
     137 
     138 
     139 
     140.. index:: ! I 
     141 
     142.. _I: 
     143 
     144Definition of Intensity: :math:`I` 
     145========================================== 
     146 
     147The intensity may be represented in one of these forms: 
     148 
     149**absolute units**: :math:`d\Sigma/d\Omega(Q)` 
     150        differential cross-section 
     151        per unit volume per unit solid angle (typical units: 1/cm/sr) 
     152 
     153**absolute units**: :math:`d\sigma/d\Omega(Q)` 
     154        differential cross-section 
     155        per unit atom per unit solid angle (typical units: cm^2) 
     156 
     157**arbitrary units**: :math:`I(Q)` 
     158        usually a ratio of two detectors  
     159        but units are meaningless (typical units: a.u.) 
     160 
     161This presents a few problems  
     162for analysis software to sort out when reading the data. 
     163Fortunately, it is possible to analyze the *units* to determine which type of 
     164intensity is being reported and make choices at the time the file is read. But this is 
     165an area for consideration and possible improvement. 
     166 
     167One problem arises with software that automatically converts data into some canonical 
     168units used by that software. The software should not convert units between these different 
     169types of intensity indiscriminately. 
     170 
     171.. index:: I(Q) 
     172 
     173A second problem is that when arbitrary units are used, then the set of possible 
     174analytical results is restricted.  With such units, no meaningful volume fraction  
     175or number density can be determined directly from :math:`I(Q)`. 
     176 
     177In some cases, it is possible to apply a factor to convert the arbitrary  
     178units to an absolute scale.  This should be considered as a possibility  
     179of the analysis process. 
     180 
     181 
     182 
     183.. index:: ! coordinate axes 
     184 
     185.. _coordinate axes: 
     186 
     187Coordinate Axes 
     188=========================== 
     189 
     190The canSAS standard assumes a right-hand rule coordinate system,  
     191consistent with a variety of software packages and data formats. 
     192See, for example: http://www.nexusformat.org/Coordinate_Systems 
     193 
     194:z: 
     195        :math:`z` is along the trajectory of the radiation 
     196        (positive value in the direction towards the detector) 
     197:x: 
     198        :math:`x` is orthogonal to :math:`z` in the horizontal plane 
     199        (positive values increase to the right when viewed  
     200        towards the incoming radiation) 
     201:y: 
     202        :math:`y` is orthogonal to :math:`z` and :math:`x`  
     203        in the vertical plane (positive values increase upwards) 
     204                 
     205 
     206 
     207 
     208.. index:: 
     209        ! orientation 
     210        roll 
     211        pitch 
     212        yaw 
     213 
     214.. _orientation: 
     215 
     216Orientation 
     217=========================== 
     218 
     219Orientation (angles) describes single-axis rotations (rotations about 
     220multiple axes require more information): 
     221         
     222**roll** 
     223        is a rotation about the :math:`z` axis 
     224 
     225**pitch** 
     226        is a rotation about the :math:`x` axis 
     227 
     228**yaw** 
     229        is a rotation about the :math:`y` axis 
  • canSAS2012/docs/source/conf.py

    r230 r267  
    116116# of the sidebar. 
    117117#html_logo = None 
    118 html_logo = 'cswikilogo.png' 
     118html_logo = 'graphics/cswikilogo.png' 
    119119 
    120120# The name of an image file (within the static path) to use as favicon of the 
  • canSAS2012/docs/source/contents.rst

    r230 r267  
    2222subversion repository, available for world-readable checkout:: 
    2323 
    24         svn co http://svn.smallangles.net/svn/canSAS/canSAS2012 ./canSAS2012 
     24        svn co http://www.cansas.org/svn/canSAS2012 ./canSAS2012 
    2525 
    2626Look in the ``docs/source`` directory for the source code files. 
    27  
    28  
    29 .. rubric:: Index 
    30  
    31 :ref:`genindex` 
    32  
    33  
    34 .. rubric:: Search 
    35  
    36 :ref:`search` 
  • canSAS2012/docs/source/framework.rst

    r227 r267  
    77================================================== 
    88 
     9.. sidebar:: work in progress... 
     10 
     11        This document is under construction. 
     12        Many parts have yet to be written. 
     13 
    914.. describe the framework 
    1015 
     
    1621 
    1722 
    18 .. figure:: 2012-minimum.png 
     23.. figure:: graphics/2012-minimum.png 
    1924    :alt: Absolute minimum requirement for analysis of SAS data  
    2025 
     
    2227 
    2328 
    24 .. figure:: 2012-recommended-minimum.png 
     29.. figure:: graphics/2012-recommended-minimum.png 
    2530    :alt: Minimum content recommended for reduced SAS data 
    2631 
     
    218223            :language: guess 
    219224 
    220         .. figure:: example1.png 
     225        .. figure:: graphics/example1.png 
    221226            :alt: view of original hkl_ioc.mac HTML documentation 
    222227         
  • canSAS2012/docs/source/hdf5.rst

    r225 r267  
    11.. $Id$ 
     2 
     3.. index::  
     4        ! HDF5 
     5        implementation; HDF5 
    26 
    37.. _hdf5_implementation: 
    48 
    59================================================== 
    6 HDF5 Implementation 
     10Binary: HDF5 
    711================================================== 
     12 
     13.. sidebar:: work in progress... 
     14 
     15        This document is under construction. 
     16        Many parts have yet to be written. 
     17 
     18It is expected that small-angle scattering data will be stored in  
     19binary HDF5 files (http://www.hdfgroup.org/HDF5/).   
     20To store SAS data in text files, see the chapter titled  
     21:ref:`xml_implementation`. 
     22 
     23The basic plan here is to describe the implementation of  
     24the canSAS multi-dimensional format within the NeXus HDF5 format  
     25(http://www.nexusformat.org) by creating a new NeXus  
     26:index:`NXcansas` application definition, expressed as a  
     27NXDL file (http://download.nexusformat.org/doc/html/nxdl.html).   
     28 
     29The effort to create this NXDL definition will commence once  
     30the basics of the canSAS multi-dimensional format are set forth. 
    831 
    932Contents: 
  • canSAS2012/docs/source/implementation.rst

    r227 r267  
    11.. $Id$ 
     2 
     3.. index:: ! implementation 
    24 
    35.. _implementation: 
  • canSAS2012/docs/source/index.rst

    r230 r267  
    4343        outcome of that meeting. 
    4444 
     45.. sidebar:: work in progress... 
     46 
     47        This document is under construction. 
     48        Many parts have yet to be written. 
    4549 
    4650.. toctree:: 
     
    5458 
    5559.. [#]  http://www.cansas.org 
    56 .. [#]  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 
     60.. [#]  http://www.cansas.org/trac/export/265/1dwg/tags/v1.0/doc/cansas-1d-1_0-manual.pdf 
     61.. [#]  http://www.cansas.org/wgwiki/index.php/canSAS-2012 
     62.. [#]  http://www.cansas.org/wgwiki/index.php/2012_Data_Discussion 
    5963 
    6064 
  • canSAS2012/docs/source/metadata.rst

    r226 r267  
    77================================================== 
    88 
     9.. sidebar:: work in progress... 
     10 
     11        This document is under construction. 
     12        Many parts have yet to be written. 
     13 
    914Describe the metadata.  Show that it was derived from the 1D format. 
    1015 
  • canSAS2012/docs/source/xml.rst

    r225 r267  
    11.. $Id$ 
     2 
     3.. index::  
     4        ! XML 
     5        implementation; XML 
    26 
    37.. _xml_implementation: 
    48 
    59================================================== 
    6 XML Implementation 
     10Text: XML 
    711================================================== 
     12 
     13.. sidebar:: work in progress... 
     14 
     15        This document is under construction. 
     16        Many parts have yet to be written. 
     17 
     18It is expected that small-angle scattering data will be stored in  
     19text files formatted as XML (http://www.w3schools.com/xml).   
     20To store SAS data in binary  files, see the chapter titled  
     21:ref:`hdf5_implementation`. 
     22 
     23The basic plan here is to describe the implementation of the canSAS  
     24multi-dimensional format in an XML file by creating an :index:`XML Schema`  
     25file (http://www.w3.org/XML/Schema, http://www.w3schools.com/schema)  
     26or similar schema specification  
     27(such as :index:`schematron` - http://www.schematron.com).   
     28 
     29The effort to create this XML Schema specification will commence once  
     30the basics of the canSAS multi-dimensional format are set forth. 
    831 
    932Contents: 
Note: See TracChangeset for help on using the changeset viewer.