Reading a Mapped File :: Data Import and Export (Programming)

Programming

Reading a Mapped File

The most commonly used property of the memmapfile class is the data property. It is through this property of the memory-map object that MATLAB provides all read and write access to the contents of the mapped file.

The actual mapping of a file to the MATLAB address space does not take place when you construct a memmapfile object. A memory map, based on the information currently stored in the mapped object, is generated the first time you reference or modify the data property for that object.

Once you have mapped a file to memory, you can read the contents of that file using the same MATLAB statements used to read variables from the MATLAB workspace. By accessing the data property of the memory map object, the contents of the mapped file appear as if they were an array in the currently active workspace. You simply index into this array to read the desired data from the file.

Example 1 -- Reading a Single Data Type

This example maps a file of 100 single-precision floating-point numbers into memory. The map begins 1024 bytes from the start of the file, and ends 400 bytes (4 bytes per single times a repeat value of 100) from that point. Construct the memmapfile object m, and show the format of its data property:

m = memmapfile('records.dat', 'format', 'single', ...
               'offset', 1024, 'repeat', 100);

d = m.data;

whos d
  Name      Size                    Bytes  Class

  d       100x1                       400  single array

Grand total is 100 elements using 400 bytes

Read a selected set of numbers from the file by indexing into the single-precision array m.data:

m.data(15:20)
ans =
  1.0e-011 *
    0.3200
    0.3299
    0.2816
    0.3129
    0.3200
    0.3356

Example 2 -- Formatting File Data as a Matrix

This example is similar to the last, except that the constructor of the memmapfile object now specifies an array shape of 4-by-6 to be applied to the data as it is read from the mapped file. MATLAB maps the file contents into a structure array rather than a numeric array, as in the previous example:

m = memmapfile('records.dat',                      ...
               'format', {'single', [4 6], 'x'},   ...
               'offset', 1024, 'repeat', 100);

d = m.data;
whos d
  Name      Size                    Bytes  Class

  d         100x1                   15664  struct array

When you read an element of the structure array, MATLAB presents the data in the form of a 4-by-6 array:

m.data(5).x
ans =
  1.0e-011 *
    0.3470    0.3370    0.0000    0.3368    0.3399    0.3200
    0.0000    0.3467    0.3314    0.3470    0.3356    0.3356
    0.3214    0.3200    0.2660    0.3200    0.3399    0.3214
    0.3527    0.3129    0.2646    0.0000    0.3129    0.3413

To index into the structure array field, use

m.data(5).x(3,2:6)
ans =
  1.0e-011 *
    0.3200    0.2660    0.3200    0.3399    0.3214

Example 3 -- Reading Multiple Data Types

This example maps a file containing more than one data type. The different data types contained in the file are mapped as fields of the returned structure array m.data.

The format parameter passed in the constructor specifies that the first 80 bytes of the file are to be treated as a 5-by-8 matrix of uint16, and the 160 bytes after that as a 4-by-5 matrix of double. This pattern repeats until the end of the file is reached. The example shows different ways of reading the data property of the object.

Start by calling the memmapfile constructor to create a memory map object, m:

m = memmapfile('records.dat', 'format', {    ...
               'uint16' [5 8] 'x';           ...
               'double' [4 5] 'y' });

If you examine the data property, MATLAB shows an 83-element structure array with two fields, one for each format specifier in the constructor:

m.data
ans = 
83x1 struct array with fields:
    x
    y

Examine one structure in the array to show the format of each field:

m.data(3)
ans = 
    x: [5x8 uint16]
    y: [4x5 double]

Now read the x and y fields of that structure from the file. MATLAB formats the first block of data as a 5-by-8 matrix of uint16, as specified in the format property, and the second block as a 4-by-5 matrix of double:

block3 = m.data(3);

block3.x
ans =
  61951  30665   7637  65324  46079  65353  64511  65535
   3010  65535  57087  65535  65535  65535  65535  51455
  65535  12218   9752  65308  65535  65357  65535  65535
  65535  29439  65535  43568  65535  65466  65499  34303
  28781  65535  65467   3066  65535  56897  65535  65413

block3.y
ans =
  1.0e+03 *
    0.0528    0.0208    0.1811    0.0208    0.1811
    0.1055    0.0643    0.1511    0.0643    0.1511
    0.1211    0.0681    0.0528    0.0681    0.0528
    0.0830    0.1168    0.0830    0.1168    0.1361

To work with multiple blocks of the mapped file, assign the full structure array m.data to a variable, s, and index into the array using standard MATLAB indexing. The example reads three regions of type double from the file:

s = m.data;

s(10:12).y
ans =
  1.0e+03 *
    0.1511    0.1511    0.0793    0.0681    0.0528
    0.0528    0.0528    0.0528    0.0718    0.1055
    0.1055    0.1055    0.1055    0.0528    0.1511
    0.0528    0.1168    0.1511    0.1093    0.0681
ans =
  1.0e+03 *
    0.1511    0.1093    0.0123    0.0528    0.1811
    0.0528    0.1436    0.1511    0.1093    0.0528
    0.1055    0.1093    0.0528    0.1436    0.1055
    0.0528    0.1018    0.1055    0.1093    0.1511
ans =
  1.0e+03 *
    0.1093    0.0681    0.1018    0.0793    0.1511
    0.1436    0.1168    0.1168    0.1055    0.0681
    0.0208    0.1811    0.0643    0.0528    0.0718
    0.0643    0.1093    0.0528    0.1055    0.0681

Example 4 -- Modifying Map Parameters

This example plots the Fourier transform output of data read from a file via a memory map. It then modifies several parameters of the existing map, reads from a different part of the data file, and plots a histogram from that data.

Create a memory-mapped object, mapping 10,000 elements of type double starting at the 1025th byte:

m = memmapfile('mybinary.bin', 'offset', 1024,         ...
               'format', 'double', 'repeat', 10000);

Get data associated with the map and plot the FFT of the first 1024 values of the map. This is when the map is actually created, because no data has been referenced until this point:

```
plot(abs(fft(m.data(1:1024))));
```

Get information about the memory map:

mapStruct = get(m)

mapStruct =
   filename: d:\matlab\mfiles\mybinary.bin
   writable: 0
     offset: 1024
     format: 'double'
     repeat: 10000
       data: [10000x1 double]

Change the map, but continue using the same file:

m.offset = 4096;
m.format = 'single';
m.repeat = 5000;

Read from a different area of the file, and plot a histogram of the data. This maps a new region and unmaps the previous region:

```
hist(m.data)
```

Constructing a memmapfile Object Writing to a Mapped File