# MAPLIB (CCP4: Library)

## NAME

maplib - Subroutine Library for CCP4 map file handling

Original documentation by Phil Evans and John Campbell.

## CONTENTS

1. INTRODUCTION
2. DETAILED DESCRIPTION OF THE MAP FORMAT
3. MAP HANDLING SUBROUTINES
4. THE SUBROUTINES 'MRDHDR' and 'MRDHDS'
   ('ccp4_map_read_open_header' and 'ccp4_map_read_open_header_check')
5. THE SUBROUTINE 'MPOSN'
   ('ccp4_map_read_position_section')
6. THE SUBROUTINE 'MRDLIN'
   ('ccp4_map_read_line_as_mode')
7. THE SUBROUTINE 'MGULP'
   ('ccp4_map_read_whole_section_as_mode')
8. THE SUBROUTINE 'MGULPR'
   ('ccp4_map_read_whole_section_as_real')
9. THE SUBROUTINE 'MRCLOS'
   ('ccp4_map_read_close')
10. THE SUBROUTINES 'MWRHDR' and 'MWRHDL'
    ('ccp4_map_write_open_header_by_id' and 'ccp4_map_write_open_header_by_name')
11. THE SUBROUTINE 'MSPEW'
    ('ccp4_map_write_all_section')
12. THE SUBROUTINE 'MWRSEC'
    ('ccp4_map_write_part_section')
13. THE SUBROUTINE 'MPOSNW'
    ('ccp4_map_write_position_section')
14. THE SUBROUTINES 'MWCLOSE', 'MCLOSE' and `MCLOSC'
    ('ccp4_map_write_close_auto', 'ccp4_map_write_close_user_sum' and 'ccp4_map_write_close_user_mean')
15. THE SUBROUTINES 'MSYPUT' and 'MSYWRT'
    ('ccp4_map_write_spgname' and 'ccp4_map_write_symm_matrix')
16. THE SUBROUTINE 'MSYMOP'
    ('ccp4_map_read_symm_matrix')
17. THE SUBROUTINE 'MSYCPY'
    ('ccp4_map_copy_symmetry')
18. THE SUBROUTINE 'MSKPUT'
    ('ccp4_map_write_skew_info')
19. THE FUNCTION 'MSKGET'
    (No alternative name)
20. THE SUBROUTINES `MTTCPY' and `MTTREP'
    ('ccp4_map_copy_title' and 'ccp4_map_write_replace_title')
21. THE SUBROUTINES 'MRFNAM' and 'MWFNAM'
    ('ccp4_map_get_last_read_filename' and 'ccp4_map_get_last_write_filename')
22. THE SUBROUTINES 'CCP4MAPHEAD', 'CCP4MAPIN' and 'CCP4MAPOUT' ('ccp4_map_read_header_only', 'ccp4_map_read_whole_map' and 'ccp4_map_write_whole_map')
23. TYPICAL CALLING SEQUENCES
24. IMPLEMENTATION NOTES

## 1) INTRODUCTION

The standard map file format used by the CCP4 programs is the map/image file format devised at the MRC LMB Cambridge, originally by David Agard. The advantages of the format include the following:

a)
  The information in the header describes the relationship of the map to the crystal cell, and other information useful in crystallographic calculations (eg crystal symmetry)
b)
  The file may be written and read in different ways e.g. written section by section and read line by line.
c)
  The format is suitable for both crystallographic work and for image processing so that Fourier and plotting programs can be used for both purposes.

## 2) DETAILED DESCRIPTION OF THE MAP FORMAT

The overall layout of the file is as follows:

a)
  File header (256 longwords)
b)
  Symmetry information
c)
  Map, stored as a 3-dimensional array

The files are read & written using the diskio package, which allows the file to be treated as a direct-access byte stream, essentially as in C fread & fwrite calls.

The header is organised as 56 words followed by space for ten 80 character text labels as follows:

     1      NC              # of Columns    (fastest changing in map)
     2      NR              # of Rows
     3      NS              # of Sections   (slowest changing in map)
     4      MODE            Data type
                              0 = envelope stored as signed bytes (from
                                  -128 lowest to 127 highest)
                              1 = Image     stored as Integer*2
                              2 = Image     stored as Reals
                              3 = Transform stored as Complex Integer*2
                              4 = Transform stored as Complex Reals
                              5 == 0

                              Note: Mode 2 is the normal mode used in
                                    the CCP4 programs. Other modes than 2 and 0
                                    may NOT WORK

     5      NCSTART         Number of first COLUMN  in map
     6      NRSTART         Number of first ROW     in map
     7      NSSTART         Number of first SECTION in map
     8      NX              Number of intervals along X
     9      NY              Number of intervals along Y
    10      NZ              Number of intervals along Z
    11      X length        Cell Dimensions (Angstroms)
    12      Y length                     "
    13      Z length                     "
    14      Alpha           Cell Angles     (Degrees)
    15      Beta                         "
    16      Gamma                        "
    17      MAPC            Which axis corresponds to Cols.  (1,2,3 for X,Y,Z)
    18      MAPR            Which axis corresponds to Rows   (1,2,3 for X,Y,Z)
    19      MAPS            Which axis corresponds to Sects. (1,2,3 for X,Y,Z)
    20      AMIN            Minimum density value
    21      AMAX            Maximum density value
    22      AMEAN           Mean    density value    (Average)
    23      ISPG            Space group number
    24      NSYMBT          Number of bytes used for storing symmetry operators
    25      LSKFLG          Flag for skew transformation, =0 none, =1 if foll
    26-34   SKWMAT          Skew matrix S (in order S11, S12, S13, S21 etc) if
                            LSKFLG .ne. 0.
    35-37   SKWTRN          Skew translation t if LSKFLG .ne. 0.
                            Skew transformation is from standard orthogonal
                            coordinate frame (as used for atoms) to orthogonal
                            map frame, as

                                    Xo(map) = S * (Xo(atoms) - t)

    38      future use       (some of these are used by the MSUBSX routines
     .          "              in MAPBRICK, MAPCONT and FRODO)
     .          "   (all set to zero by default)
     .          "
    52          "

    53	MAP	        Character string 'MAP ' to identify file type
    54	MACHST		Machine stamp indicating the machine type
    			which wrote file
    55      ARMS            Rms deviation of map from mean density
    56      NLABL           Number of labels being used
    57-256  LABEL(20,10)    10  80 character text labels (ie. A4 format)

Symmetry records follow - if any - stored as text as in International Tables, operators separated by * and grouped into 'lines' of 80 characters (ie. symmetry operators do not cross the ends of the 80-character 'lines' and the 'lines' do not terminate in a *).

Map data array follows.

## 3) MAP HANDLING SUBROUTINES

High level subroutines are provided to handle 3-D maps. There are routines to handle the header, to read and write sections (ie a part of the 3D array corresponding to 1 value of the slow-moving index), and to handle the symmetry data.

Summary of routines:

Nb: longer descriptive names are now also available; calls to subroutines using the new names have the same arguments as those usng the original names.

Input:

Original name | Function | Alternative name
--- | --- | ---
MRDHDR | open file for reading, read header and print | ccp4_map_read_open_header
MPOSN | position file to a given map section | ccp4_map_read_position_section
MGULP | read a section of map | ccp4_map_read_whole_section_as_mode
MGULPR | read a section of map and convert to real*4 if necessary | ccp4_map_read_whole_section_as_real
MRCLOS | close input file | ccp4_map_read_close
CCP4MAPHEAD | read spacegroup, cell and map limits from header | ccp4_map_read_header_only
CCP4MAPIN | read in the whole map and store in x,y,z order | ccp4_map_read_whole_map
[MRDLIN] | [read a line of map] | [ccp4_map_read_line_as_mode]

Output:

Original name | Function | Alternative name
--- | --- | ---
MWRHDR / MWRHDL | open output file and set up header | ccp4_map_write_open_header_by_id / ccp4_map_write_open_header_by _name
MSPEW | write section | ccp4_map_write_all_section
MWCLOSE / [MCLOSE] / [MCLOSC] | write out header and close file | ccp4_map_write_close_auto / [ccp4_map_write_close_user_sum] / [ccp4_map_write_close_user_mean]
CCP4MAPOUT | write out the whole map in x,y,z order | ccp4_map_write_whole_map
[MWRSEC] | [write part of array as section] | [ccp4_map_write_part_section]

Symmetry:

Original name | Function | Alternative name
--- | --- | ---
MSYPUT | copy symmetry data from library file to map file | ccp4_map_write_spgname
MSYWRT | write symmetry data to mapfile | ccp4_map_write_symm_matrix
MSYMOP | read symmetry data from map file and convert to matrices and vectors. | ccp4_map_read_symm_matrix
MSYCPY | copy symmetry data from input map file to output map file | ccp4_map_copy_symmetry
MSYGET | get symmetry operations from library file (nothing to do with map files, exists in symlib.f) | No alternative name

Skew transformation:

Original name | Function | Alternative name
--- | --- | ---
MSKPUT | put skew transformation into header common block | ccp4_map_write_skew_info
MSKGET | get skew transformation from header common block (Function call) | No alternative name

Titles:

Original name | Function | Alternative name
--- | --- | ---
MTTCPY | Copy all titles from previously opened input and output files | ccp4_map_copy_title
MTTREP | Replace title in output file | ccp4_map_write_replace_title

In all these routines IUNIT is a logical stream number in the range 1 to 12. These stream numbers are not directly related to the Fortran stream numbers.

## 4) THE SUBROUTINES 'MRDHDR' and 'MRDHDS'

Alternative names: `ccp4_map_read_open_header` and `ccp4_map_read_open_header_check`

The subroutines 'MRDHDR' (_read_open_header) or 'MRDHDS' (_read_open_header_check) are used to open an input map file and read the header information. MRDHDS differs from MRDHDR only in the provision of 2 extra arguments IFAIL & IPRINT which allow for soft failure of file opening, and control of printing

    Call:  CALL MRDHDR(IUNIT,MAPNAM,TITLE,NSEC,IUVW,MXYZ,NW1,NU1,NU2,
          *NV1,NV2,CELL,LSPGRP,LMODE,RHMIN,RHMAX,RHMEAN,RHRMS)

           CALL MRDHDS(IUNIT,MAPNAM,TITLE,NSEC,IUVW,MXYZ,NW1,NU1,NU2,
          *NV1,NV2,CELL,LSPGRP,LMODE,RHMIN,RHMAX,RHMEAN,RHRMS,IFAIL,IPRINT)

Arguments:

     IUNIT (I)   Map stream number

    MAPNAM (I)   Logical file name (type CHARACTER) e.g. 'MAPIN'

     TITLE (O)   Map title (CHARACTER*80)

      NSEC (O)   Number of sections in the map

      IUVW (O)   3 word array with fast, medium, slow axes (1=X, 2=Y, 3=Z)

      MXYZ (O)   3 word array with sampling intervals along whole cell on X, Y,
                 Z

       NW1 (O)   No. of first section

       NU1 (O)   Start of section on fast axis (grid units)

       NU2 (O)   End of section on fast axis

       NV1 (O)   Start of section on medium axis

       NV2 (O)   End of section on medium axis

      CELL (O)   6 word array for cell dimensions in Angstroms and degrees

    LSPGRP (O)   Space group number

     LMODE (O)   Map data mode =0, byte
                               =1, INTEGER*2
                               =2, REAL
                               =3, COMPLEX INTEGER*2
                               =4, COMPLEX REAL
                               =5, Treated as mode 0
                 Only mode 2 and 0 should occur with CCP4 programs

     RHMIN (O)   Minimum density

     RHMAX (O)   Maximum density

    RHMEAN (O)   Mean density

    RHRMS  (O)   Rms deviation from the mean

The following arguments are for MRDHDS (ccp4_map_read_open_header_check) only

     IFAIL (I/O)  On input:     =0, stop on error
                                 =1, return on error
                  On output:    unchanged if no error
                                 =-1, error
      IPRINT (I)                 = 0; silent
                              .ne. 0; print file name, header info etc

## 5) THE SUBROUTINE 'MPOSN'

Alternative name: `ccp4_map_read_position_section`

This subroutine is used to set the position in the map file so that the next section to be read is section JSEC.

    Call:  CALL MPOSN(IUNIT,JSEC)

Arguments:

     IUNIT (I)   Map stream number

      JSEC (I)   Position the input map before section JSEC

## 6) THE SUBROUTINE 'MRDLIN'

Alternative name: `ccp4_map_read_line_as_mode`

Read the next line from an input map file. The data are returned in the same form as that stored in the map.

    Call:  CALL MRDLIN(IUNIT,X,IER)

Arguments:

     IUNIT (I)   Map stream number

         X (O)   Array to contain the line of data read from the map

       IER (O)   Error flag =0, OK   non-zero, error or end of file

## 7) THE SUBROUTINE 'MGULP'

Alternative name: `ccp4_map_read_whole_section_as_mode`

This subroutine reads the next whole map section. The data are returned in the same form as that stored in the map (ie no conversion for different modes is done).

    Call:  CALL MGULP(IUNIT,X,IER)

Arguments:

     IUNIT (I)   Map stream number

         X (O)   Array to contain the section of data read from the map

       IER (O)   Error flag =0, OK   non-zero, error or end of file

## 8) THE SUBROUTINE 'MGULPR'

Alternative name: `ccp4_map_read_whole_section_as_real`

This subroutine reads the next whole map section. For map modes other than 2 the output data are converted to type=REAL. For complex maps (mode = 3 or 4) the complex amplitude is returned.

    Call:  CALL MGULPR(IUNIT,X,IER)

Arguments:

     IUNIT (I)   Map stream number

         X (O)   Array to contain  the  section  of  data  read  from  the  map
                 (Returned as REAL values)

       IER (O)   Error flag =0, OK   non-zero, error or end of file

## 9) THE SUBROUTINE 'MRCLOS'

Alternative name: `ccp4_map_read_close`

MRCLOS closes a map file open for reading to re-use the stream.

    Call: CALL MRCLOS(IUNIT)

Arguments:

     IUNIT (I)   The map stream number

## 10) THE SUBROUTINES 'MWRHDR' AND'MWRHDL'

Alternative names: `ccp4_map_write_open_header_by_id` and `ccp4_map_write_open_header_by_name`

These subroutines are used to open an output map file and set up the header information. The actual header is only written to the file when the file is closed via the routine MCLOSE (ccp4_map_write_close_user_sum). The only difference between the two subroutines is that MWRHDR (ccp4_map_write_open_header_by_id) does not have a parameter for the logical file name for which a name of 'MAPOUT' is assumed.

    Call:  CALL MWRHDR(IUNIT,TITLE,NSEC,IUVW,MXYZ,NW1,NU1,NU2,
          *NV1,NV2,CELL,LSPGRP,LMODE)

    Call:  CALL MWRHDL(IUNIT,MAPNAM,TITLE,NSEC,IUVW,MXYZ,NW1,NU1,NU2,
          *NV1,NV2,CELL,LSPGRP,LMODE)

Arguments:

     IUNIT (I)   Map stream number

    MAPNAM (I)   Logical  file  name  (type  CHARACTER)  e.g.  'MAPOUT'   (This
                 parameter only present for MWRHDL)

     TITLE (I)   Map title (CHARACTER*80)

      NSEC (I)   Number of sections in the map

      IUVW (I)   3 word array with fast, medium, slow axes (1=X, 2=Y, 3=Z)

      MXYZ (I)   3 word array with sampling intervals along whole cell on X, Y,
                 Z

       NW1 (I)   No. of first section

       NU1 (I)   Start of section on fast axis (grid units)

       NU2 (I)   End of section on fast axis

       NV1 (I)   Start of section on medium axis

       NV2 (I)   End of section on medium axis

      CELL (I)   6 word array for cell dimensions in Angstroms and degrees

    LSPGRP (I)   Space group number

     LMODE (I)   Map data mode =0, byte for envelopes
                               =1, INTEGER*2
                               =2, REAL  (usual mode)
                               =3, COMPLEX INTEGER*2
                               =4, COMPLEX REAL
                               =5, Treated as mode 0
                  Only mode 2 and 0 should occur with CCP4 programs

## 11) THE SUBROUTINE 'MSPEW'

Alternative name: `ccp4_map_write_all_section`

This subroutine writes the next whole map section. The routine is used when the section occupies the complete array. The data are written without translation for different modes.

    Call:  CALL MSPEW(IUNIT,X)

Arguments:

     IUNIT (I)   Map stream number

         X (I)   Array holding the map section

## 12) THE SUBROUTINE 'MWRSEC'

Alternative name: `ccp4_map_write_part_section`

This subroutine is used to write a map section as part of an array to the map file.

    Call:  CALL MWRSEC(IUNIT,X,MU,MV,IU1,IU2,IV1,IV2)

Arguments:

     IUNIT (I)   The map stream number

         X (I)   The array holding the map section

        MU (I)   The number of points along the whole fast axis

        MV (I)   The number of points along the whole medium axis

       IU1 (I)   The start array index along the fast axis

       IU2 (I)   The finish array index along the fast axis

       IV1 (I)   The start array index along the medium axis

       IV2 (I)   the finish array index along the medium axis

The elements written for a section may be described in FORTRAN notation as ((X(I,J),I=IU1,IU2),J=IV1,IV2).

## 13) THE SUBROUTINE 'MPOSNW'

Alternative name: `ccp4_map_write_position_section`

This subroutine is used to set the position in the map file so that the next section to be written is section JSEC.

    Call:  CALL MPOSNW(IUNIT,JSEC)

Arguments:

     IUNIT (I)   Map stream number

      JSEC (I)   Position the output map before section JSEC

## 14) THE SUBROUTINE 'MWCLOSE', 'MCLOSC' and `MCLOSE'

Alternative names: `ccp4_map_write_close_auto`, `ccp4_map_write_close_user_sum` and `ccp4_map_write_close_user_mean`

MWCLOSE, MCLOSC & MCLOSE write the header records to the output map file and close the file. They differ in their handling of the density limits, mean and rms deviation. You are strongly recommended to use MWCLOSE (ccp4_map_write_close_user_sum).

Use:-

MWCLOSE (ccp4_map_write_close_auto)
  if the sums for mean & rms are accumulated inside the maplib package (in MSPEW/ccp4_map_write_all_section). This works for mode=2 only. USE THIS FOR NORMAL PURPOSES.
MCLOSC (ccp4_map_write_close_user_sum)
  when a map file is just being copied, since the RHMEAN & RHRMS arguments can be taken directly from the call to MRDHDR/ccp4_map_read_open_header. This call is also useful when the mean & rms need to be weighted (as in rotation functions), so they need to be calculated in the main program.
MCLOSE (ccp4_map_write_close_user_mean)
  if the sums for mean & rms RHSUM & RHSUM2 are accumulated outside the maplib package.

    Calls:  CALL MWCLOSE(IUNIT)
     	CALL MCLOSC(IUNIT,RHMIN,RHMAX,RHMEAN,RHRMS)
    	CALL MCLOSE(IUNIT,RHMIN,RHMAX,RHSUM,RHSUM2)

Arguments:

     IUNIT (I)   The map stream number

     RHMIN (I)   The minimum density in the map

     RHMAX (I)   The maximum density in the map

    RHSUM  (I)   The sum of all the densities in the map (This will be  divided
                 internally by the number of points in the map to give the mean
                 density which is then stored)

    RHSUM2 (I)   The sum of squares of the density values in the map (This will
                 used internally to calculate the rms deviation from the mean
                 value which is then stored.)

    RHMEAN (I)   The mean density in the map. This is the same as is returned
                 from reading the header

    RHRMS  (I)   The rms deviation from the mean density, as stored in the header

## 15) THE SUBROUTINES 'MSYPUT' and 'MSYWRT'

Alternative names: `ccp4_map_write_spgname` and `ccp4_map_write_symm_matrix`

The subroutine MSYPUT reads the symmetry operators file (logical name SYMOP) and finds the entry for the requested space group. The symmetry operators are copied from the symmetry operators file to the map file on stream IUNIT leaving space for the header records.

    Call:  CALL MSYPUT(IST,LSPGRP,IUNIT)

Arguments:

       IST (I)   The FORTRAN unit number for  reading  the  symmetry  operators
                 file (choose a unit number which does not conflict with
    	     the rest of your program).

    LSPGRP (I)   The space group number

     IUNIT (I)   The map stream number of the output map file

The subroutine MSYWRT writes symmetry operators to map stream IUNIT Note that the symmetry operators are written to the file one per line and may have a different format to those in the SYMOP file

    Call: CALL  MSYWRT(IUNIT,NSYM,ROT)

Arguments:

           IUNIT    (I)     Map stream number
           NSYM     (I)     Number of symmetry operators
     ROT(4,4,NSYM)  (I)     rotation/translation matrices

## 16) THE SUBROUTINE 'MSYMOP'

Alternative name: `ccp4_map_read_symm_matrix`

This subroutine reads the symmetry operators from an input map file (after calling MRDHDR /ccp4_map_read_open_header). The operators are converted and returned as matrices.

    Call:  CALL MSYMOP(IUNIT,NSYM,ROT)

Arguments:

     IUNIT (I)   The map stream number

      NSYM (O)   The number of symmetry operators

       ROT (O)   The array in which the symmetry operators are returned as  4*4
                 matrices. It should be dimensioned as ROT(4,4,NS) where NS  >=
                 NSYM (usually NS = 96)

## 17) THE SUBROUTINE 'MSYCPY'

Alternative name: `ccp4_map_copy_symmetry`

This subroutine copies the symmetry operators from an input map file to an output map file after calls to MRDHDR (_read_open_header) and MWRHDR (_write_open_header_by_id) (or MWRHDL / _write_open_header_by_name). Note that if you have more than one input file, this routine should be called after MRDHDR for the file from which you want to copy the symmetry operations, and before calling MRDHDR for any other file.

    Call:  CALL MSYCPY(IN,IOUT)

Arguments:

        IN (I)   The input map stream number

      IOUT (I)   The output map stream number

## 18) THE SUBROUTINE 'MSKPUT'

Alternative name: `ccp4_map_write_skew_info`

This subroutine writes a skew transformation to an output map header block (after a call to MWRHDR (_write_open_header_by_id) or MWRHDL (_write_open_header_by_name) ).

NB *** Use of MSKPUT & MSKGET has not been generally implemented in the CCP4 suite ***

    Call:  CALL MSKPUT(SKWMAT,SKWTRN)

Arguments:

    SKWMAT (I)   3*3 Skew rotation matrix

    SKWTRN (I)   3 word Skew translation matrix

## 19) THE FUNCTION 'MSKGET'

Alternative name: None.

This function reads a skew transformation from an input map header block (after a call to MRDHDR (_read_open_header) ).

NB *** Use of MSKPUT & MSKGET has not been generally implemented in the CCP4 suite ***

    Call:  I = MSKGET(SKWMAT,SKWTRN)

Arguments:

    SKWMAT (O)   3*3 Skew rotation matrix

    SKWTRN (O)   3 word Skew translation matrix

Returns MSKGET =1, skew transformation present, =0, absent

## 20) THE SUBROUTINES `MTTCPY' and `MTTREP'

Alternative names: `ccp4_map_copy_title` and `ccp4_map_write_replace_title`

MTTCPY (ccp4_map_copy_tile) copies all titles from a previously opened input to the previously opened output file, adding the new TITLE to the end or overwriting the last one if there are already 10 (the maximum which can be stored).

    Call:  CALL MTTCPY(TITLE)

Arguments:

    TITLE (I)  CHARACTER variable holding the new title (<=80 characters)

MTTREP (ccp4_map_write_replace_title) replaces the NT-th title in the output file (after calls to MWRHDR / ccp4_map_read_open_header and MTTCPY / ccp4_map_copy_title), adding a new TITLE to the end or overwriting the last one if there are already 10.

    Call:  CALL MTTREP(TITLE,NT)

Arguments:

    TITLE (I)  CHARACTER varaible holding the new title

       NT (I)  INTEGER number of title to be replaced

## 21) THE SUBROUTINES 'MRFNAM' and 'MWFNAM'

Alternative names: `ccp4_map_get_last_read_filename` and `ccp4_map_get_last_write_filename`

These routines may be called to return the full filename for a file open for reading (MRFNAM / ccp4_map_get_last_read_filename) or writing (MWFNAM / ccp4_map_get_last_write_filename).

    Call: CALL MRFNAM(FNAME)
          CALL MWFNAM(FNAME)

Arguments:

      FNAME (O) file name of last file opened by MRDHDR/MRDHDS or by
    		MWRHDR/MWRHDL

## 22) THE SUBROUTINES 'CCP4MAPHEAD', 'CCP4MAPIN' AND 'CCP4MAPOUT'

Alternative names: `ccp4_map_read_header_only`, `ccp4_map_read_whole_map`, and `ccp4_map_write_whole_map`.

These are Kevin Cowtan's "wrapper" routines which provide an interface to other maplib subroutines in order to easily read and write entire maps. CCP4MAPHEAD obtains the map limits from the map file, and CCP4MAPIN and CCP4MAPOUT then use this information to resepctively read in and write out an entire map in one go.

CCP4MAPHEAD reads header information from a map file. It is used to get the map limits before calling CCP4MAPIN.

      Call: CALL ccpmap4head(iunit,name,nspgrp,cell,nu,nv,nw,nu1,nv1,nw1,nu2,
           +                 nv2,nw2)

Arguments:

      iunit   (I)  Map stream number (integer)
      name    (I)  Logical file name (type character*8) e.g.'MAPIN'
      nspgrp  (O)  Space group number (integer)
      cell    (O)  6 word array for cell dimensions in Angstroms and
                   degrees (real)
      nu      (O)  Sampling interval along whole cell on X (integer)
      nv      (O)  Sampling interval along whole cell on Y (integer)
      nw      (O)  Sampling interval along whole cell on Z (integer)
      nu1     (O)  Start of map on X axis, in grid units (integer)
      nv1     (O)  Start of map on Y axis, in grid units (integer)
      nw1     (O)  Start of map on Z axis, in grid units (integer)
      nu2     (O)  End of map on X axis (integer)
      nv2     (O)  End of map on Y axis (integer)
      nw2     (O)  End of map on Z axis (integer)

Note that this differs from ccp4_map_read_open_header_check [MRDHDS] (which it calls) in that the file is not left open but is closed (by a call to ccp4_map_read_close [MRCLOS]) before the subroutine terminates. Note also that the map limits are returned in x,y,z order rather than in fast, medium, slow order.

CCP4MAPIN reads a whole map into an array and stores it in x,y,z order. The map limits are required as input to dimension the array holding the map, and can be obtained with a call to the subroutine CCP4MAPHEAD.

      Call: CALL ccp4mapin (iunit,name,title,map,nu1,nv1,nw1,nu2,nv2,nw2)

Arguments:

      iunit   (I)  Map stream number (integer)
      name    (O)  logical file name (type character) e.g. 'MAPIN'
      title   (O)  Map title (type character)
      map     (O)  Real array of dimension (nu1:nu2,nv1:nv2,nw1:nw2)
                   which stores the map which is read in
      nu1     (I)  Start of map on X axis, in grid units (integer)
      nv1     (I)  Start of map on Y axis, in grid units (integer)
      nw1     (I)  Start of map on Z axis, in grid units (integer)
      nu2     (I)  End of map on X axis (integer)
      nv2     (I)  End of map on Y axis (integer)
      nw2     (I)  End of map on Z axis (integer)

CCP4MAPIN utilises calls to the following maplib routines:

- ccp4_map_read_open_header_check [MRDHDS],
- ccp4_map_read_whole_section_as_real [MGULPR], and
- ccp4_map_read_close [MRCLOS].

CCP4MAPOUT writes out a whole map in x,y,z order.

      Call: CALL ccp4mapout(iunit,name,title,map,nspgrp,cell,nu,nv,nw,nu1,
           +                nv1,nw1,nu2,nv2,nw2)

Arguments:

      iunit   (I)  Map stream number (integer)
      name    (I)  Logical file name (type character) e.g.'MAPIN'
      title   (I)  Map title (type character)
      map     (I)  Real array of dimension (nu1:nu2,nv1:nv2,nw1:nw2)
                   which stores the map being written out
      nspgrp  (I)  Space group number (integer)
      cell    (I)  6 word array for cell dimensions in Angstroms and degrees (real)
      nu      (I)  Sampling interval along whole cell on X (integer)
      nv      (I)  Sampling interval along whole cell on Y (integer)
      nw      (I)  Sampling interval along whole cell on Z (integer)
      nu1     (I)  Start of map on X axis, in grid units (integer)
      nv1     (I)  Start of map on Y axis, in grid units (integer)
      nw1     (I)  Start of map on Z axis, in grid units (integer)
      nu2     (I)  End of map on X axis (integer)
      nv2     (I)  End of map on Y axis (integer)
      nw2     (I)  End of map on Z axis (integer)

CCP4MAPOUT utilises calls to the following maplib subroutines:

- ccp4_map_write_open_header_by_name [MWRHDL],
- ccp4_map_write_symm_matrix [MSYWRT],
- ccp4_map_write_all_section [MSPEW],
- ccp4_map_write_close_auto [MWCLOSE].

There is also a call to the symlib routine MSYMLB.

## 23) TYPICAL CALLING SEQUENCES

Typical calling sequences are as follows:

Write new file

MWRHDR/MWRHDL | ccp4_map_write_open_header_by_id / ccp4_map_write_open_header_by_name
MSYPUT | ccp4_map_write_spgname
MSPEW repeated for each section | ccp4_map_write_all_section
MWCLOSE[/MCLOSE/MCLOSC] | ccp4_map_write_close_auto [/ccp4_map_write_close_user_sum / ccp4_map_write_close_user_mean]

Read file

MRDHDR | ccp4_map_read_open_header
MSYMOP | ccp4_map_read_symm_matrix
MPOSN to 1st section | ccp4_map_read_position_section
MGULP (or MGULPR) repeated for each section | ccp4_map_read_whole_section_as_mode (or ccp4_map_read_whole_section_as_real)

Read file, write modified file

MRDHDR | ccp4_map_read_open_header
MWRHDR/MWRHDL | ccp4_map_write_open_header_by_id / ccp4_map_write_open_header_by_name
MSYMOP | ccp4_map_read_symm_matrix
MSYCPY | ccp4_map_copy_symmetry
MGULP ) repeated for each section MSPEW ) | ccp4_map_read_whole_section_as_mode ) ccp4_map_write_all_section )
MWCLOSE[/MCLOSE/MCLOSC] | ccp4_map_write_close_auto [/ccp4_map_write_close_user_sum / ccp4_map_write_close_user_mean

Read and write whole map

CCP4MAPHEAD to get map limits | ccp4_map_read_header_only
CCP4MAPIN | ccp4_map_read_whole_map
CCP4MAPOUT once map has been manipulated | ccp4_map_write_whole_map

## 24) IMPLEMENTATION NOTES

The map functions (modes other than 2 or 4) requiring non standard code are handled via the routines CCPBYT, CCPTOI, CCPBYI, CCPGTB etc. in CCPLIB and through the DISKIO routines. In particular, use packed integer arrays for handling masks/envelopes. The convention for masks is that non-zero represents `true', i.e. protein region, and 0 false, i.e. solvent region; normally only 0 and 1 should be used for masks.