Below are some functions I’ve written in Matlab for processing and plotting data. Some of the functions are specific to files generated by the LISFLOOD-FP hydraulic model (you can request a copy from here). I hope you find the code below useful – feel free to edit for your needs and share with colleagues.

[download all code here]

Please check the license statement below.

General data handling

readasc.m

Reads an ASCII Raster file into memory. The ASCII Raster file format is a general text format with a simple 6-line header containing spatial information. The format is used by ArcGIS, which may read in /export the data via the ASCII to Raster and Raster to ASCII functions in ArcToolbox > Conversion Tools. This makes it easy to exchange simple raster files between ArcGIS and Matlab. ASCII Raster is also the format used by LISFLOOD-FP for raster images. Readasc will read the raster data into a variable, along with x and y vectors (optional). Nodata values are automatically converted to NaN.

Basic usage:

[data,x,y,dx] = readasc('filename.asc');
% where:
% data : matrix containing data values
% x,y  : vectors of cell coordinates
% dx   : cell size

writeasc.m

Writes an ASCII Raster file. If you intend to load this into ArcGIS, make sure you specify the file suffix as “.txt” or “.asc”.

Basic usage:

writeasc(filename,data,xl,yl,dx,nodata);
%
% where: 
% filename : string path of file to create
% data     : the array to write to file
% xl       : minimum x (SE corner)
% yl       : minimum y (SE corner)
% dx       : cell size (m)
% nodata   : value assigned as 'no data' in array

If you’ve read data in using readasc and are writing it out again, you can do this:

nodata = -9999;
data(isnan(data)) = nodata;
writeasc(filename,data,min(x),min(y),dx,nodata);

LISFLOOD-FP data handling

readmass.m

Reads a mass balance file produced during a LISFLOOD-FP run, returning a data structure of vectors. This is version 3.0 of the function, which handles files produced by LISFLOOD-FP version 4.3.5 or higher – older versions produced files in a slightly different format. The function will handle breaks in the file caused by checkpointing restarts.

Basic usage:

data = readmass('filename.mass');
% Will return a struct array, data, containing:
%    data.time      : simulation time, s
%    data.tstep     : time step at point in data.time, s
%    data.mintstep  : minimum tstep, s
%    data.numtsteps : number of iterations
%    data.area      : area of inundation, km2
%    data.vol       : volume of inundation, m3
%    data.qin       : total inflow to domain, m3s-1
%    data.hds       : water depth at d/s exit of domain, m
%    data.qout      : channel outflow discharge, m3s-1
%    data.qerror    : qerror per tstep, m3s-1
%    data.verror    : volumetric error, m3
%    data.infevap   : rainfall-inf+evap, m3

readbdy.m

Reads the dynamic boundary condition input file for LISFLOOD-FP, which usually denoted with the file suffix “.bdy”. Will return a vector of structures containing data for each boundary condition.

Basic usage:

bdydata = readbdy('filename.bdy');
% Will read a LISFLOOD-FP dynamic boundary condition file (.bdy) and return
% a Matlab structure with the following fields:
%
% name: identifier of the boundary condition
% timeformat: format that the time is given in (string) - seconds, hours
% or days
% data: flow data vector
% time: time vector of same length as flow data

readstage.m

Reads the stage output file optionally produced by LISFLOOD-FP, returning a structure with a vector for each stage.

Basic usage:

data = readstage('filename.stage');
% Will return a struct array, data, containing:
% data.time     : simulation time, s
% data.stage{1}
% data.stage{2}
% :
% data.stage{n} : vectors of stage
% data.ID       : stage number
% data.x        : x location of stages 1 to n
% data.y        : y location of stages 1 to n
% data.elev     : elevation of stages 1 to n

readprofile.m

Reads the channel profile output produced by LISFLOOD-FP when using the “profiles” keyword in the parameter file. Will return a vector of structures containing data for each channel segment.

Basic usage:

profile = readprofile('filename.profile');
% Where filename is a text string of the profile file name. This will return
% a structure of channel segments, containing the following fields:
% channel_segment
% ChanX
% ChanY
% Chainage
% Width
% Mannings
% Slope
% BankZ
% BedElev
% WaterElev
% WaterDepth
% Flow
% If LISFLOOD-FP was run in debug mode, there will be two additional fields: Q_Ident and Q_Val

loadprofiles.m

Will call readprofile.m (above) to load all channel profile data contained in a LISFLOOD-FP output folder. The files will be loaded into a structure.

Basic usage:

profiles = loadprofiles('/path/to/folder/');

You can then animate through the profiles using something like:

for i = 1:length(profiles)
   c = profiles(i).data.Chainage; we = profiles(i).data.WaterElev;
   plot(c,we),title(profiles(i).filename),pause(0.1)
end

Using GZip

Most of these functions can call GZip to uncompress/recompress data on the fly. To get this to work, GZip must be installed on the system and included on the system path. For linux/mac systems, this should already be the case, but for Windows, you will need to download the software from the GZip website then add the installation directory to the path under Control Panel > System > Advanced > Environment Variables.

License

gplv3-127x51All code on this page is covered by the terms of use of the GNU General Public Licence, version 3. By downloading files from this site you are acknowledging that you agree to abide by the terms of this licence.