Next Previous Contents

1. Introduction

BRIX is a program (Still Another!) to convert different formats of electron density maps to O format. BRIX was written to circumvent the problems of fixed array boundaries, and allocates the memory it needs on the fly. Thus, you are only limited by the virtual memory of the computer.

BRIX writes a new un-swapped version of the DSN6 file, independent of endianism issues. Thus, you can use a bricked density file which has been calculated on an ALPHA machine on a SGI. Also, the new format contains more information in the header, most notably the SIGMA value of the map. Thus, in your map macros, you will be able to put a ';' where you normally specify the contouring level, to get a 1 sigma contouring.

The new bricked electron density format is understood by O versions later than 5.10.

However, BRIX will still calculate the old, unportable, DSN6 format, if the program is invoked under the name 'mappage' (uh, actually, it only needs to contain the word mappage, so 4d_mappage is OK). In other words, you can install a symbolic link (or normal link):

      % ln -s brix mappage

and then run the mappage version.

BRIX understands the following map formats: X-PLOR (formatted), CCP4, TNT and EZD, and will automagically determine which format the map is. It will also automatically slice the map correctly.

1.1 An example session

Here is a sample session of BRIX. The only input needed is the names of the input map and the output brick file; these can be given on the command line:

kaktus 395% brix /xtal/morten/xplor/type3/m10.xmap   m10.omap
 brix> Convert ED maps to O format
 brix> Version 1.1, Nov 1993
 brix>
 brix> Mapfile: /xtal/morten/xplor/type3/m10.xmap
 brix> O brick file: m10.omap
 brix> ...file is formatted
 brix>
 brix> Map type is X-PLOR
 brix>
 brix> Parameters as read from the map file:
 brix> Grid .................        80        80       192
 brix> Origin ...............         6       -21        24
 brix> Extent ...............        75       105        76
 brix> Fast, medium, slow....         1         2         3
 brix> Cell axes ............     69.90     69.90    161.80
 brix> Cell angles ..........     90.00     90.00     90.00
 brix>
 brix> Reslicing XYZ --> YXZ
 brix> Fast, medium, slow....         2         1         3
 brix> Min, max, sigma ......  -4.53080   7.12510   0.98377
 brix> Scale ................     1.000
 brix>
 brix> Prod .................  21.87733
 brix> Plus .................        99
 brix> Bricks along x,y,z ...        10        14        10
kaktus 396%

BRIX binaries are available from ftp://kaktus.imsb.au.dk/pub/o/brix. There are versions for HP, ESV and 4D.

1.2 The BRIX map format

The format of the bricked files made by BRIX is almost the same as the old MAPPAGE (DNS6) format, except that no byte swapping is required.

The header record

The first 512 bytes of the file is the header information, containing the following information

Origin:

the origin of the map in grid units, along X, Y, Z.

Extent:

the extent (size) of the map, along X, Y, Z, in grid units

Grid:

number of grid points along the whole unit cell, along X, Y, Z.

Cell:

Unit cell parameters

Prod, plus:

Constants that bring the electron density from byte to normal scale. They are calculated like this: prod = 255.0/(rhomax-rhomin), plus = -rhomin*prod.

Sigma:

Rms deviation of electron density map.

In the original DSN6 format, this information was stored in the first elements of an INTEGER*2 array with 256 elements. The problem with that is that such an array is stored differently in big endian (for example SGI) and small endian (for example ALPHA) machines. BRIX overcomes this problem by storing the header as a character string. The first few bytes of the character string is a signature (a "smiley") that enables O and other programs to recognize the format of the file. Then comes a keyworded sequence giving the origin, extent, unit cell parameters etc.

On a UNIX system, you can use 'more' to look at the header of the file, because it ends with a formfeed character:

kaktus 810% more test.omap
:-) origin 49 -25 -12 extent 77 51 88 grid 180 108 144 cell 208.280 122.300 151.
800 90.000 126.700 90.000 prod 22.55819 plus 118 sigma 1.07519 ^L               
--More--(0%)

The map data

The input map is divided into cubes of 8 x 8 x 8 = 512 gridpoints. The density value at each of these gridpoints is then scaled to fit into a single byte, that is, to values between 0 and 255. Each of these 512 cubes (bricks) is written to a single record of the file. In the DSN6 format, the 512 bytes where equivalenced to an INTEGER*2 array with 256 elements, which was then written out. This presents a problem as described in the section above. BRIX overcomes this by storing the 512 bytes in a character array.

1.3 Writing a BRIX file

The following describes the use of a piece of FORTRAN code that you can use in your own programs when writing a BRIX file. It can be found at http://imsb.au.dk/~mok/brix/paged_export.F.

This file contains two subroutines, paged, and pagedhdr. They are intended for outputting a paged electron density file for input into "O". The format of the paged electron density file does not depend on the byte-endedness of the computer.

To use the subroutines, you must first set up the values of these variables:

Your program must open a file, direct access 512 byte records:


      open (unit=olun, file=filenm, status='new',access='direct',
     $        recl=128, form='unformatted')

The recl number is sometimes given in longwords, sometimes in bytes, depending on the computer. Now you can write the header. Str is a character*512 variable:


     write (str, 10) origin, extent, grid, cell, prod, plus, sigma
10   format (":-) Origin", 3i5," Extent", 3i5, " Grid", 3i5,
    $        " Cell ", 6f10.3, " Prod", f12.5, " Plus",i8, 
    $        " Sigma ", f12.5)


     write (olun, rec=1, iostat=errcod) str

Next, the program must calculate the number of 8 grid pages along X, Y, Z:


     do i=1,3
        xyzbrix(i) = extent(i)/8
        if (mod(extent(i),8) .ge. 1) xyzbrix(i) = xyzbrix(i) + 1
     enddo

The paged routine can now be called. The map must be sectioned so that fast, medium, slow is Y, X, Z. Call the paged routine with one section at a time. Rho is the array that holds the (prod/plus scaled) density, rhosec is an array large enough to hold one section, slices is an array large enough to hold 8 sections of density. In the following example a user-supplied routine map_getsection gets the next slice. Of course you can do this any way you like.


     do isec = 1, extent(3)
        call map_getsection (rho, rhosec, isec, extent, errcod)
        call paged (olun, rhosec, slices, 
    $        extent(1), extent(2), xyzbrix(1), xyzbrix(2), isec, errcod)
        if (errcod .ne. 0) then
           call prompt ("Error writing brick")
           stop
        endif
     enddo

Finally, call the paged routine with a value of 0 in 'isec':


        call paged (olun, rhosec, slices, 
    $        extent(1), extent(2), xyzbrix(1), xyzbrix(2), 0, errcod)

This flushes the slices array.


Next Previous Contents