Discussion List Archives

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Cifsas dictionary

  • Subject: Cifsas dictionary
  • From: Marco <Malfois@embl-hamburg.de>
  • Date: Mon, 24 Aug 1998 09:55:19 +0200
  • Organization: EMBL
Dear All,

below you will find a draft of a one-dimensional SAS
data format prepared following the discussions at the
Denver X-ray conference (Aug'97), Workshop at NIST (Jan'98),
canSAS'98 (Grenoble, Feb'98) and ACA'98 (Arlington, July'98)
meetings.

The idea was to have a simple interchangeable format which
can be written/read by the data aquisition and analysis
software. A consensus seemed to be reached on an ASCII
format for one-dimensional data which includes:

- a self-described header containing all relevant information about the
  sample and instrumental conditions;
- raw or reduced data in a table form.

The above structure was implemented by defining a dictionary
serving as a common basis to make the files self describing.
This dictionary was realized as an extension of CIF (Crystallographic
Information File), which is a standard means of information interchange
in crystallography. Similar "extension" approach has been developed,
e.g. for the powder crystallography data. Adhering to CIF allows to
use numerous public domain programs developed for this format
(you may read all about it at the UICr WWW page).

Please note that the draft below concerns only 1D data.
For 2D files, a portable binary format would probably
be required, which is out of scope of the current project.

Your comments/suggestions/extensions/criticism are welcome.
Please put them on the SAS listserver or send directly to
Malfois@EMBL-Hamburg.DE or Svergun@EMBL-Hamburg.DE.
If a consensus will be reached, the project will be extended
to develop relevant tools for this format.
Any standard is meaningful only if it is going to be used!

The information below includes:

1. A short description of the names used
2. An example of a sasCIF file
3. A "sasCIF extension" to a CIF dictionary.




                        sasCIF dictionary  (draft)
                        Description of the names used
                        M.Malfois, D.Svergun, July 1998


   PUBLIC INFORMATION

   ### All included in the core CIF dictionary

   BLOCK INFORMATION

   # Some relevant CIF dictionary entries are also listed

   _audit_Block_code_        Identifies uniquely the current data block
   _audit_Creation_date_
   _audit_Update_Record_     History

   _sas_block_data_id        Uniquely identifies the current SAS data block

   SOURCE INFORMATION

   _diffrn_radiation_source           X-ray tube, neutron reactor...
   _diffrn_radiation_probe            Source of radiation (X-rays/Neutrons)
   _diffrn_radiation_wavelength       radiation wavelength in A.
   _diffrn_radiation_monochromator    Its type

   # Assumed: x=equatorial direction, y=azimuthal direction

   _sas_beam_collimation_slit_x        Collimation slits in cm
   _sas_beam_collimation_slit_y

   _sas_beam_size_x                    Beam size on the sample in cm
   _sas_beam_size_y
   _sas_beam_divergence_x              Beam divergency in radians
   _sas_beam_divergence_y

   _sas_beam_collimation_distance          In cm
   _sas_beam_sample_detector               In cm

   _sas_beam_delta_lambda                   (Delta lambda) /lambda

   DETECTOR INFORMATION

   _diffrn_detector        general class of detector
   _diffrn_detector_type   Model or name of the detector used

   _sas_det_beamstop_x       Beamstop size on X, cm
   _sas_det_beamstop_y       Beamstop size on Y, cm

   _sas_det_pixnum_x         Number of detector pixels in X direction
   _sas_det_pixnum_y         Number of detector pixels in Y direction

   _sas_det_pixsiz_x         Pixel size, X direction, cm
   _sas_det_pixsiz_y         Pixel size, Y direction, cm

   _sas_det_center_x         Beam center, X coordinate in cm from left
   _sas_det_center_y         Beam center, Y coordinate in cm from bottom

   _sas_det_rad_step         Radial step to group pixels for
                                 circular average (cm)
   _sas_det_mer_fact         # of channels merged together (1D-detector)

   _sas_det_rotation         Tilt of the detector (degrees)

   _sas_det_sector_width        In degrees (for sectorial average)
   _sas_det_sector_orientation  In degrees with respect to X direction

   SAMPLE INFORMATION

   _chemical_compound_source_

   _diffrn_ambient_temperature            temperature in K
   _diffrn_ambient_environment            air, vacuum...

   _sas_sample_name                   Sample description
   _sas_sample_concentration          In g/l
   _sas_sample_thickness              In cm
   _sas_sample_transmission

   _sas_sample_time                 For kinematic measurements
   _sas_sample_strain
   _sas_sample_pressure             any other parameters ???

   _sas_sample_orientation          Sample normal/beam
   _sas_sample_monitor              sample calibration channel value

   _sas_sample_buffer_composition
   _sas_sample_buffer_pH
   _sas_sample_matrix_monitor       matrix calibration channel value
   _sas_sample_exposure             measurement exposure time

   TREATMENT INFORMATION

   _sas_trt_detres_made               data normalized against response Y/N
   _sas_trt_detres_block              Detector response data block

   _sas_trt_matrix_made                Matrix/buffer scattering subtracted Y/N
   _sas_trt_matrix_block               Matrix/buffer scattering block
   _sas_trt_matrix_transmission        Transmission of the matrix/buffer

   _sas_trt_background_made            Background subtracted     Y/N
   _sas_trt_background_block           Background scattering block
   _sas_trt_background_transmission    Transmission of empty cell

   _sas_trt_raw_data_file              acquisition data file(s)
   _sas_trt_raw_data_date              date/time of raw data file

   _sas_trt_date                       date/time of primary data treatment

   DATA INFORMATION

   _sas_data_type                  Possible types:  $Sample, $Matrix,
                                        $Detector, $Background
   _sas_data_title

   _sas_data_momentum_transfer     momentum transfer (Q,q,s,S,h,k,m....)
   _sas_data_momentum_factor       Scaling factor of the above quantity to
                                      4*pi sin(th)/lam [A-1]
   _sas_data_intensity             scattering intensity
   _sas_data_stat_error            standard deviation
   _sas_data_syst_error            e.g. from radial average etc
   _sas_data_scaling_factor        Scaling factor for the intensity and errors

   _sas_data_group_factor          # of pixels contributing to this point
   _sas_data_resolution            Width of Gaussian resolution function



#####################################################
# Example file illustrating description             #
# of a small-angle scattering experiment            #
# with data names from the core CIF                 #
# and sasCIF extension dictionaries                 #
#                                                   #
#  Warning: was NOT checked against the CIF rules,  #
#           just gives impression on how a sasCIF   #
#           file would look like ...                #
#####################################################

data_TEST_publ

_audit_block_code               1998-07-09_Exa_for_sasCIF

_audit_creation_date  1998-07-08
_audit_creation_method  "from PD example file"

loop_ _publ_contact_author_name
      _publ_contact_author_email
      _publ_contact_author_phone
      _publ_contact_author_fax

                " M.Malfois"            ,
                Malfois@EMBL-Hamburg.De ,
                +49(40)89902148         ,
                +49(40)89902149         ,

                " D.Svergun"            ,
                Svergun@EMBL-Hamburg.De ,
                +49(40)89902125         ,
                +49(40)89902149         ,

_publ_contact_author_adress

;               EMBL c/o DESY
                Notkestrasse 85
                D-22603 Hamburg
                Germany
;

_publ_section_title                 "Chicken egg white lysozyme"

_diffrn_radiation_source           "Storage ring DORIS, beamline X33"
_diffrn_radiation_probe            "Synchrotron radiation X-rays"
_diffrn_radiation_wavelength       1.5
_diffrn_radiation_monochromator    "Bent crystal"

_sas_beam_size_x                    0.2
_sas_beam_size_y                    0.5

_sas_beam_sample_detector           150

_diffrn_detector        "Gas-filled proportional"
_diffrn_detector_type   Quadrant

_sas_det_beamstop_x       0.5
_sas_det_beamstop_y       0.5
_sas_det_pixsiz_x         0.01
_sas_det_pixsiz_y         0.01

_sas_det_center_x         2.0
_sas_det_center_y         2.2

_sas_det_sector_width        45
_sas_det_sector_orientation  22.5

_diffrn_ambient_temperature            277
_diffrn_ambient_environment            air

_sas_sample_name
; Chicken egg white lysozyme in solution
;
_sas_sample_concentration            15
_sas_sample_buffer_composition     "150mM NaCl, 40 mM Na acetate"
_sas_sample_buffer_pH                4.25

_sas_sample_thickness            0.2
_sas_sample_transmission         0.6
_sas_sample_exposure_time        600

_sas_trt_detres_made               Yes
_sas_trt_matrix_made               Yes
_sas_trt_background_made           Yes

_sas_trt_date                      07-Jul-1997

_sas_block_data_id          "07-09-98 02:46am|Exa_for_sasCIF|Diff"
_sas_data_type              Sample
_sas_data_title              "Lysozyme difference data"
_sas_data_momentum_factor    0.62831
_sas_data_scaling_factor     1e-6

loop_ _sas_data_momentum_transfer
      _sas_data_intensity
      _sas_data_stat_error

    5.210180E-02  ,     86.182260  ,      6.284270
    5.384985E-02  ,     84.223050  ,      5.760499
    5.559791E-02  ,     82.234630  ,      5.395226
    5.734596E-02  ,     78.108730  ,      5.148366
    5.909401E-02  ,     77.326730  ,      4.874490

# .....  truncated for brievity

    5.258238E-01  ,      5.752596  ,  6.161484E-01
    5.275719E-01  ,      4.321647  ,  6.167618E-01
    5.293199E-01  ,      5.015543  ,  6.191652E-01
    5.310680E-01  ,      5.677856  ,  6.121474E-01
    5.328161E-01  ,      5.151685  ,  6.183262E-01

# The file may contain other data sets (matrix scattering,
# another sampls(s), detector response etc) identified by their
# own _sas_block_data_id

#--eof--eof--eof--eof--eof--eof--eof--eof--eof--eof--eof--eof--eof
##############################################################################
#                                                                            #
#                        SAS  CIF  Dictionary                                #
#                        ---------------------                               #
#                                                                            #
#  CIF data definitions specifically for SAS applications.                   #
#  These are in addition to those defined in the Core CIF Dictionary 1996.   #
#                                                                            #
#  The DDL commands used in this dictionary are defined in "ddl_core.dic".   #
#                                                                            #
##############################################################################

data_on_this_dictionary

    _dictionary_name            cif_sas.dic
    _dictionary_version         0.1
    _dictionary_update          1998-08-17
    _dictionary_history
;
  1998-08-17  Initial definitions
;

#......................... Block/Dataset names

data_sas_block_data_[sas]
    _name                     '_sas_block_data_[sas]'
    _category                   category_overview
    _type                       null

#.............................................................

data_sas_block_data_id
    _name                     '_sas_block_data_id'
    _category                   sas_block
    _type                       char
    _definition
;              It is used to assign an unique id code
               to a data block.
;

#......................... Beam Information

data_sas_beam_[sas]
    _name                     '_sas_beam_[sas]'
    _category                   category_overview
    _type                       null

#.............................................................

data_sas_beam_collimation_slit_
    loop_ _name                '_sas_beam_collimation_slit_x'
                               '_sas_beam_collimation_slit_y'
    _category                    sas_beam
    _type                        numb
    _enumeration_range           0.0:
    _units                       cm
    _units_detail               'centimeters'
    _list                        both
    _definition
;              defines the collimation slits in the equatorial
               and axial direction.
;

data_sas_beam_size_
    loop_ _name                '_sas_beam_size_x'
                               '_sas_beam_size_y'
    _category                    sas_beam
    _type                        numb
    _enumeration_range           0.0:
    _units                       cm
    _units_detail               'centimeters'
    _list                        both
    _definition
;              defines the beam size on the sample
;

data_sas_beam_divergence_
    loop_ _name                '_sas_beam_divergence_x'
                               '_sas_beam_divergence_y'
    _category                    sas_beam
    _type                        numb
    _enumeration_range           0.0:
    _units                       rad
    _units_detail               'radians'
    _list                        both
    _definition
;              defines the beam divergency
;

data_sas_beam_collimation_distance
    _name                      '_sas_beam_collimation_distance'
    _category                    sas_beam
    _type                        numb
    _enumeration_range           0.0:
    _units                       cm
    _units_detail                'centimeters'
    _definition
;              defines the collimation distance
;

data_sas_beam_sample_detector
    _name                      '_sas_beam_sample_detector'
    _category                    sas_beam
    _type                        numb
    _enumeration_range           0.0:
    _units                       cm
    _units_detail               'centimeters'
    _definition
;              defines the distance sample/detector
;

data_sas_beam_delta_lambda
    _name                      '_sas_beam_delta_lambda'
    _category                    sas_beam
    _type                        numb
    _enumeration_range           0.0:
    _definition
;              defines the quantity (Delta lambda ) / lambda
               Lambda being the wavelength
;


#......................... Detector Information

data_sas_det_[sas]
    _name                     '_sas_det_[sas]'
    _category                   category_overview
    _type                       null

#.............................................................

data_sas_det_beamstop_
    loop_ _name                '_sas_det_beamstop_x'
                               '_sas_det_beamstop_y'
    _category                    sas_det
    _type                        numb
    _enumeration_range           0.0:
    _units                       cm
    _units_detail               'centimeters'
    _list                        both
    _definition
;              defines the beamstop size.
;

data_sas_det_pixnum_
    loop_ _name                '_sas_det_pixnum_x'
                               '_sas_det_pixnum_y'
    _category                    sas_det
    _type                        numb
    _enumeration_range           0.0:
    _list                        both
    _definition
;              defines the number of detector pixel
               in x and y direction.
;

data_sas_det_pixsize_
    loop_ _name                '_sas_det_pixsize_x'
                               '_sas_det_pixsize_y'
    _category                    sas_det
    _type                        numb
    _enumeration_range           0.0:
    _units                       cm
    _units_detail               'centimeters'
    _list                        both
    _definition
;              defines the pixel size in x and y direction.
;

data_sas_det_center_
    loop_ _name                '_sas_det_center_x'
                               '_sas_det_center_y'
    _category                    sas_det
    _type                        numb
    _enumeration_range           0.0:
    _units                       cm
    _units_detail               'centimeters'
    _list                        both
    _definition
;              defines the beam center on the detector in
               x and y directions.
               The X coordinate is defined from left and
               the Y coordinate is defined from bottom.
;

data_sas_det_rad_step
    _name                      '_sas_det_rad_step'
    _category                    sas_det
    _type                        numb
    _enumeration_range           0.0:
    _units                       cm
    _units_detail              'centimeters'
    _definition
;              defines the radial step to group pixels for
               circular average.
;

data_sas_det_mer_fact
    _name                      '_sas_det_mer_fact'
    _category                    sas_det
    _type                        numb
    _enumeration_range           0.0:
    _definition
;              defines the number of channels merged
               together for the 1D-detector
;

data_sas_det_rotation
    _name                      '_sas_det_rotation'
    _category                    sas_det
    _type                        numb
    _enumeration_range           -180.0:360.0
    _units                       deg
    _units_detail               'degrees'
    _definition
;              defines the tilt of the detector
;

data_sas_det_sector_
    loop_ _name                '_sas_det_sector_width'
                               '_sas_det_sector_orientation'
    _category                    sas_det
    _type                        numb
    _enumeration_range           -180.0:360.0
    _units                       deg
    _units_detail               'degrees'
    _list                        both
    _definition
;              defines the sector width for sectorial average
               and the sector orientation with respect
               x direction.
;

#......................... Sample Information

data_sas_sample_[sas]
    _name                     '_sas_sample_[sas]'
    _category                   category_overview
    _type                       null

#.............................................................

data_sas_sample_name
     _name                     '_sas_sample_name'
     _category                   sas_sample
     _type                       char
     _definition
;
          A description of the specimen such as the source of the specimen,
          identification of standards, mixtures, etc.
;

data_sas_sample_concentration
     _name                     '_sas_sample_concentration'
     _category                   sas_sample
     _type                       numb
     _enumeration_range          0.0:
     _units                      gl-1
     _units_detail              'gramme/liter'
     _definition
;
          The sample concentration.
;

data_sas_sample_thickness
     _name                     '_sas_sample_thickness'
     _category                   sas_sample
     _type                       numb
     _enumeration_range          0.0:
     _units                      cm
     _units_detail              'centimeters'
     _definition
;
          The sample thickness
;

data_sas_sample_transmission
     _name                     '_sas_sample_transmission'
     _category                   sas_sample
     _type                       numb
     _enumeration_range          0.0:
     _definition
;
          The sample transmission
;

data_sas_sample_time
     _name                     '_sas_sample_time'
     _category                   sas_sample
     _type                       numb
     _enumeration_range          0.0:
     _units                      s
     _units_detail              'seconds'
     _definition
;
          A description of the sample in case of kinematic
          measurments.
;

data_sas_sample_strain
     _name                     '_sas_sample_strain'
     _category                   sas_sample
     _type                       numb
     _enumeration_range          0.0:
     _definition
;
          The sample strain
;

data_sas_sample_pressure
     _name                     '_sas_sample_pressure'
     _category                   sas_sample
     _type                       numb
     _enumeration_range          0.0:
     _units                      Pa
     _units_detail              'Pascals'
     _definition
;
          The sample pressure
;

data_sas_sample_orientation
     _name                     '_sas_sample_orientation'
     _category                   sas_sample
     _type                       numb
     _enumeration_range          -180.0:360.0
     _units                      deg
     _units_detail              'degrees'
     _definition
;
          defines the angle between the sample normal and
          the incident beam.
;

data_sas_sample_monitor
     _name                     '_sas_sample_monitor'
     _category                   sas_sample
     _type                       numb
     _enumeration_range          0.0:
     _definition
;
          Sample calibration channel value
;

data_sas_sample_buffer_composition
    _name                      '_sas_sample_buffer_composition'
    _category                    sas_sample
    _type                        char
    _definition
;              A description of the buffer used
;

data_sas_sample_buffer_ph
     _name                     '_sas_sample_buffer_ph'
     _category                   sas_sample
     _type                       numb
     _enumeration_range          0.0:14.0
     _definition
;
          Buffer ph
;

data_sas_sample_matrix_monitor
     _name                     '_sas_sample_matrix_monitor'
     _category                   sas_sample
     _type                       numb
     _definition
;
          Matrix callibration channel value
;

data_sas_sample_exposure
     _name                     '_sas_sample_exposure'
     _category                   sas_sample
     _type                       numb
     _enumeration_range          0.0:
     _units                      s
     _units_detail              'seconds'
     _definition
;
          Exposure time of the sample
;

#......................... Treatment Information

data_sas_trt_[sas]
    _name                     '_sas_trt_[sas]'
    _category                   category_overview
    _type                       null

#.............................................................

data_sas_trt_detrep_made
     _name                     '_sas_trt_detrep_made'
     _category                   sas_trt
     _type                       char
     loop_ _enumeration          yes
                                 no
     _definition
;
          Data normalized against response
;

data_sas_trt_detrep_block
     _name                     '_sas_trt_detrep_block'
     _category                   sas_trt
     _type                       char
     _definition
;
          Detector response data block
;

data_sas_trt_matrix_made
     _name                     '_sas_trt_matrix_made'
     _category                   sas_trt
     _type                       char
     loop_ _enumeration          yes
                                 no
     _definition
;
          Matrix/buffer scattering subtracted
;

data_sas_trt_matrix_block
     _name                     '_sas_trt_matrix_block'
     _category                   sas_trt
     _type                       char
     _definition
;
          Matrix/buffer scattering block
;

data_sas_trt_matrix_transmission
     _name                     '_sas_trt_matrix_transmission'
     _category                   sas_trt
     _type                       numb
     _enumeration_range          0.0:
     _definition
;
          The matrix transmission
;

data_sas_trt_background_made
     _name                     '_sas_trt_background_made'
     _category                   sas_trt
     _type                       char
     loop_ _enumeration          yes
                                 no
     _definition
;
          Background subtracted
;

data_sas_trt_background_block
     _name                     '_sas_trt_background_block'
     _category                   sas_trt
     _type                       char
     _definition
;
          Background scattering block
;

data_sas_trt_background_transmission
     _name                     '_sas_trt_background_transmission'
     _category                   sas_trt
     _type                       numb
     _enumeration_range          0.0:
     _definition
;
          The transmission of empty cell
;

data_sas_trt_raw_data_file
     _name                     '_sas_trt_raw_data_file'
     _category                   sas_trt
     _type                       char
     _definition
;
          Acquisition data file
;

data_sas_trt_raw_data_date
     _name                     '_sas_trt_raw_data_date'
     _category                   sas_trt
     _type                       char
     _definition
;
          Date and time of raw data file acquisition.

          Dates and times should be specified in the standard
          CIF format 'yyyy-mm-ddThh:mm:ss+zz'. Use of seconds
          and a time zone is optional, but use of hours and minutes
          is strongly encouraged.
;

data_sas_trt_date
     _name                     '_sas_trt_date'
     _category                   sas_trt
     _type                       char
     _definition
;
          Date and time of traetment

          Dates and times should be specified in the standard
          CIF format 'yyyy-mm-ddThh:mm:ss+zz'. Use of seconds
          and a time zone is optional, but use of hours and minutes
          is strongly encouraged.
;

#......................... Data Information

data_sas_data_[sas]
    _name                     '_sas_data_[sas]'
    _category                   category_overview
    _type                       null

#.............................................................

data_sas_data_type
     _name                     '_sas_data_type'
     _category                   sas_data
     _type                       char
     loop_ _enumeration          sample
                                 matrix
                                 background
                                 detector
     _definition
;
          data type
;

data_sas_data_title
     _name                     '_sas_data_title'
     _category                   sas_data
     _type                       char
     _definition
;
          data title
;

data_sas_data_momentum_transfert
     _name                     '_sas_data_momentum_transfert'
     _category                   sas_data
     _type                       numb
     _list                        yes
     _definition
;
          Momentum transfert values
;

data_sas_data_momentum_factor
     _name                     '_sas_data_momentum_factor'
     _category                   sas_data
     _type                       numb
     _definition
;
          Scaling factor of the momentum transfert to
          4*PI sin (theta) / lambda  in A-1
;

data_sas_data_intensity
     _name                     '_sas_data_intensity'
     _category                   sas_data
     _type                       numb
     _list                        yes
     _definition
;
          Scattering intensity
;

data_sas_data_stat_error
     _name                     '_sas_data_stat_error'
     _category                   sas_data
     _type                       numb
     _list                        yes
     _definition
;
          Statistical errors associated to the scattering intensity
;

data_sas_data_sys_error
     _name                     '_sas_data_sys_error'
     _category                   sas_data
     _type                       numb
     _list                        yes
     _definition
;
          Systematic errors, e.g. from radial average etc...
;

data_sas_data_scaling_factor
     _name                     '_sas_data_scaling_factor'
     _category                   sas_data
     _type                       numb
     _definition
;
          Scaling factor for the intensity and errors.
;

data_sas_data_group_factor
     _name                     '_sas_data_group_factor'
     _category                   sas_data
     _type                       numb
     _list                        yes
     _definition
;
          Number of pixels contributing to this point.
;

data_sas_data_resolution
     _name                     '_sas_data_resolution'
     _category                   sas_data
     _type                       numb
     _list                        yes
     _definition
;
          Width of Gaussian resolution function.
;

#--eof--eof--eof--eof--eof--eof--eof--eof--eof--eof--eof--eof--eof