Discussion List Archives

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

Trying to use imgCIF/CBF

John Westbrook, Paul Ellis, and I have been having a conversation about
where to go with this, and I'm writing this note to try to draw anyone
else who wants to be back into the discussion.

I've been trying to decide what a truly usable header should look like.  I
have written some comments and questions, essentially in the form of
searching for the right CIF entries, which I include below.  You'll see
that I use a couple of entries that Harry Powell invented, and that my
comments end with a serious question.  I'll look forward to having some
advice. 

----------------------

One could define _both_ an entry_id and diffrn_id.  Perhaps these
should be the same.  A quite reasonable solution is to take the file
name prefix.

It seems to me that variables start out as a.b and become a_b.  I'll
use that idea below.

I start with the old draft suggestion from Hammersley.  All the items in
<> will have to be defined.  I left out some of his stuff.  I try to
suggest default values for everything.  I'm doing this only for detectors
at synchrotrons for the moment.  There are questions and comments embedded
below.  I need to define several new CIF entries, as you'll see. 

A really important issue that I don't see resolved is that the header
should make it very clear what is in THAT FILE.  In particular, I
don't see an entry that gives precisely the rotation axis settings for
that frame.  There is a scan definition, but frankly this isn't very
important and definitely can be misleading.  Extremely often 1.) one
does not start reducing data at the beginning of a sweep of data, 2.)
one does not end reducing at the end, and 3.) all the data predicted
in a sweep at the beginning aren't even taken.  I propose to use the
scan_axis section to define just the data included in the file.  If
it's more than one frame, that's fine.  For single files to be more than
one frame is possible, but there are many reasons not ever to do it.

I think someone needs to explain to me what was intended here.  I'd be
happy to make a phone call if you please tell me when.

Without looking somewhere else we also don't have the exposure time.
Please suggest something.

Also, on rereading all of that below, I realize that I still don't know
where the real specimen-to-detector distance should be recorded.

Bob

            List of useful CIF entries for imgCIF or CBF files:

-------------------------------------------------------------------------
_entry.id                                    <filename prefix>

_diffrn.id                                    entry_id
_diffrn.crystal_id                            <user's name for this
                                                 particular crystal; default
                                                 would be entry_id>
--------------
_diffrn_measurement.diffrn_id                 diffrn_id
_diffrn_measurement.method                    rotation

--------------
_diffrn_radiation_wavelength.id               <users name for wavelength,
                                                like L1, or null>
_diffrn_radiation_wavelength.wavelength       <wavelength or null>
_diffrn_radiation_wavelength.wt               1.0


_diffrn_radiation.diffrn_id                   diffrn_id

# Polarization is not defined correctly because it speaks of the angle
  between the polarization plane and the plane containing the incident
  and reflected beams.  There is a long discussion in the imgCIF
  bulletinboard about this.  Clearly this is different for each
  reflection.  We'll use the ratio and norm terms as they exist, but
  the user will have to know that they have new values, as below, when
  the detector is an area detector.

_diffrn_radiation.polarisn_ratio        <polarization ratio: (Ih-Iv)/(Ih+Iv)
                                              {Ih = intensity of the
                                              electric vector in the
                                              horizontal plane, Iv
                                              ditto in vertical
                                              plane}; Default 0.0>

_diffrn_radiation.polarisn_norm         <Angle between the polarization-plane
                                              normal and the lab Y axis -- see
                http://www.iucr.org/iucr-top/cif/imgcif/cif_img_1.0.html#AXIS;
                                              Default of 0.0 makes this correct
                                              for most synchrotrons with horiz.
                                              polarization and horiz. rot'n
                                              axes>

_diffrn_radiation.wavelength_id               wavelength_id

-----------------
_diffrn_source.diffrn_id                      diffrn_id
_diffrn_source.source                         <synchrotron>
_diffrn_source.type                           <beamline name>

## Harry Powell suggests new CIF entries:

_diffrn_source_divx                           <beam crossfire in degrees
                                              parallel to Lab X axis, the 
                                              princ. rot'n axis>
_diffrn_source_divy                           <same for Lab Y>

--------------------
_diffrn_detector.diffrn_id                    diffrn_id
_diffrn_detector.id                           <short code to define this 
                                              particular detector, like 
                                              NSLS-X12B-Q4>
_diffrn_detector.detector                     <detector type code, like CCD>
_diffrn_detector.type                         <Statement of Mfr. and type of
                                              detector, like "ADSC Q4R">

## Note: We must have Gain and Saturation or Overload values for each
   detector.  I suggest these new CIF entries:

_diffrn_detector.gain                         <digital value per x-ray photon>
_diffrn_detector.overload                     <digital value above which all
                                              readings may be nonlinear>

## Note: In the case that multi-element images are treated as one image,
this will be the center for the whole detector.

_diffrn_detector_element.id                   <element name; default 1>
_diffrn_detector_element.detector_id          detector_id
_diffrn_detector_element.center[1]            <X component of the distortion-
                                              corrected beam-center in mm from 
                                              the (0, 0) (lower left) corner 
                                              of the detector element viewed 
                                              from the sample side.>
_diffrn_detector_element.center[2]            <Y component, etc.>

-----------------------

## Note: the specimen-to-detector distance is defined in the
   frame scan-axis items as given below from the IUCr imgCIF definition
   http://www.iucr.org/iucr-top/cif/imgcif/cif_img_1.0.html#DIFFRN_SCAN:

   loop_
      _diffrn_scan_axis.scan_id
      _diffrn_scan_axis.axis_id
      _diffrn_scan_axis.angle_start
      _diffrn_scan_axis.angle_increment
      _diffrn_scan_axis.displacement_start
      _diffrn_scan_axis.displacement_range
      _diffrn_scan_axis.displacement_increment

       1 omega 200.0 20.0 0.1 . . . 
       1 kappa -40.0  0.0 0.0 . . . 
       1 phi   127.5  0.0 0.0 . . . 
       1 tranz  . . .   2.3 0.0 0.0 

In the simplest case this tranz value should define the
specimen-to-detector distance.

{I don't see why the tranz displacement is given as 2.3 in the
example.  This should be mm, and should be on the order of 100.}

## Catch-22: the specimen-to-detector distance from above is _used_ in
the axis items to define offset values.  How is this propagated?
Please read
http://www.iucr.org/iucr-top/cif/imgcif/cif_img_1.0.html#AXIS
carefully.  The distance is described in example 2:

        Example 2 -
        
        This example show the axis specification of the axes of a
        detector, source and gravity.  We have juggled the order as a
        reminder that the ordering of presentation of tokens is not
        significant.  We have taken the center of rotation of the detector
        to be 68 millimetres in the direction away from the source.
;
;
        loop_
        _axis.id
        _axis.type
        _axis.equipment
        _axis.depends_on
        _axis.vector[1] _axis.vector[2] _axis.vector[3]
        _axis.offset[1] _axis.offset[2] _axis.offset[3]
        source       .        source     .       0     0     1   . . .
        gravity      .        gravity    .       0    -1     0   . . .
        tranz     translation detector rotz      0     0     1   0 0 -68
        twotheta  rotation    detector   .       1     0     0   . . .
        roty      rotation    detector twotheta  0     1     0   0 0 -68
        rotz      rotation    detector roty      0     0     1   0 0 -68
;


-------------------

##  Harry Powell also suggests a time stamp:

_diffrn_scan.date_start                     <unix-style date format>
_diffrn_scan.date_end

--------------------

## I don't understand this.  Paul or John W. please suggest something
   in the spirit of what is above.

_diffrn_frame_data.id                         F1
_diffrn_frame_data.detector_element_id        1
_diffrn_frame_data.array_id                   'image_1'
_diffrn_frame_data.binary_id                  1


On each beamline there should be some file <setup>.cif that should
feed the chemical and exptl terms into the image header CIF.



=========================================================================
           "Reply" may fail.  Better to use the address below
	Robert M. Sweet			E-Dress: sweet@bnl.gov (that's L
	Biology Dept.			Phones:                    not 1)
	Brookhaven Nat'l Lab.	*New*	631 344 3401  (Office)
	Upton, NY  11973	Area	631 344 5642  (Beamline at NSLS)
	U.S.A.			Code	631 344 2741 or 3407  (Facsimile)
=========================================================================

Reply to: [list | sender only]
International Union of Crystallography

Scientific Union Member of the International Science Council (admitted 1947). Member of CODATA, the ISC Committee on Data. Partner with UNESCO, the United Nations Educational, Scientific and Cultural Organization in the International Year of Crystallography 2014.

International Science Council Scientific Freedom Policy

The IUCr observes the basic policy of non-discrimination and affirms the right and freedom of scientists to associate in international scientific activity without regard to such factors as ethnic origin, religion, citizenship, language, political stance, gender, sex or age, in accordance with the Statutes of the International Council for Science.

Useful links