BRIX HOWTO: Introduction

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:

- 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.

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