Libdext Matlab Wrapper (matdpp)

This document describes the Matlab Wrapper (matdpp) for the Data Extraction Library (libdext). matdpp allows libdext scripts to be used to create data structures that are accessable from within Matlab. This edition documents version 1.0.

1. Notices
2. Introduction
3. Installation
4. Using the readdext() Function
5. The Library Files
6. Examples
7. Troubleshooting
Concept Index

 -- The Detailed Node Listing ---

Introduction

2.1 Companion Software
2.2 Obtaining
2.3 Other Documentation

Installation

3.1 Dependencies
3.2 Platforms
3.3 Required Build Tools
3.4 Building
3.5 Environment

1. Notices

The Libdext Matlab Wrapper (matdpp)

Copyright (C) 1997 - 2003 Mike Arnold, Altjira Software

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Matlab is a trademark of The Mathworks Inc.

This software and documentation is provided "as is" without express or implied warranty. All questions should be addressed to mikea@altjira.com.

2. Introduction

matdpp allows libdext scripts to be used to create data structures that are accessable from within Matlab. It it is comprised of two components. The main component is a single C-MEX function called readdext(). As a C-MEX function, readdext() is available within the Matlab environment.

readdext() takes exactly one input array, being a string containing the libdext script, and returns exactly one output array, containing the requested data structures. No data structures, other than those returned in the output array, are preserved across multiple calls to readdext().

The second component are a set of optional matlab library files built around readdext() to facilitate its use.

2.1 Companion Software
2.2 Obtaining
2.3 Other Documentation

2.1 Companion Software

For a list of software that works with libdext (and matdpp) refer to the libdext website.

2.2 Obtaining

matdpp may be downloaded from http://www.altjira.com/distrib/matdpp. See also 3.1 Dependencies, and 2.1 Companion Software, for other software that may need to be downloaded and installed.

The latest version of this documentation may be found at http://www.altjira.com/support/matdpp/matdpp.html.

2.3 Other Documentation

Further information regarding the interoperability of NMI components and supporting frameworks, their development and use, and all associated support and post-processing packages, is available in the NMI Simulation Resources documentation.

This documentation is also installed to ${prefix}/doc/matdpp, where `${prefix}' is the installation directory specified during the build configuration.

3. Installation

3.1 Dependencies
3.2 Platforms
3.3 Required Build Tools
3.4 Building
3.5 Environment

3.1 Dependencies

matdpp requires both the Network Model Interface library libnmi and the xutil library libxutil, as well as the Data Extraction library libdext. It also requires matlab including the Matlab mex compiler.

3.2 Platforms

matdpp has been successfully tested on the following systems:

• i686-linux-gnu (Mandrake 8.2) with Matlab 6.5 R13
• freebsd release 4.6 with Matlab 6.5 R13

3.3 Required Build Tools

The following software is suggested. Other versions may work but have not been tested.

• gcc 3.2
• texi2html 1.64

Package maintenance requires:

• autoconf 2.54
• automake 1.7

3.4 Building

Refer to the README and INSTALL files in the distribution.

3.5 Environment

readdext() is installed to `$prefix/libexec/matdpp' and the matlab library files are installed to `$prefix/share/matdpp', where `$prefix' is the installation prefix given to the configure script during building. These directories should be included in the Matlab path, for example by modifying the user's Matlab startup file, which is usually `/home/user/matlab/startup.m'. For example, for the default prefix `/usr/local', the following lines would be added:

addpath('/usr/local/libexec/matdpp') addpath('/usr/local/share/matdpp')

4. Using the readdext() Function

readdext() takes a single input array, being a string containing the libdext script. Note that this means the script itself, not the name of the file containing the script. For details of the script syntax refer to the libdext libdext documentation.

A single 1 by 1 output array is returned containing the following structure:

• data

  a 2 dimensional matrix of reals containing the extracted data set, where each column represents an extracted dimension and the number of rows represents the number of extracted data samples.

• index

  a 2 dimensional matrix of reals having either zero or one columns and the same number of rows as the data matrix. If it is present, the single column represents an index dimension or the x-axis for the data matrix, with one value for each extracted data sample.

• titles

  a 2 dimensional matrix of strings with a single column and the same number of rows as the number or extracted dimensions. Each string gives a description of each extracted dimension.

• description

  a single string describing the extracted data set.

5. The Library Files

The library files fall in to the following categories:

• dext_script_*()

  the creation of dext scripts that can be passed to readdext().

• dext_window_*()

  applying windowing algorithms to break up dext data structures into new dext data structures.

• dext_perrow_*()

  apply algorithms on a per row basis to a set of dext data structures.

• dext_percol_*()

  apply algorithms on a per column basis to a set of dext data structures.

• dext_convert_*()

  a collection of useful algorithms to map between sets of dext data structures.

• dext_plot_*()

  plotting dext data structures using different styles of plots.

• dext_plotspec_*() and dext_linespec_*()

  creating and using plot specification structures to standardise the formatting and layout of plots and to control their saving and printing.

6. Examples

For examples on writing libdext scripts refer to the libdext documentation.

The following is an example from the TENNS cerebellum package that utilises the matlab library files built on top of readdext(). It extracts a data set to the measured activities of the inferior olive cells in a cerebellar simulation. This data set is then broken up in to 10 windows, and the mean, standard deviation, minimum and maximum values are calculated for each inferior olive cell in each window. The resulting values are then plotted over time.

dext_load_linespec; ps = dext_default_plotspec; hold off; script = dext_script('^Io<','N-build-Net-Probe.asc'); data = dext_extract(script); windows = dext_window_divided(data,10); ps.filename = 'io.eps'; ps.legend = 'raw'; dext_plot_percol_minmaxmsd(data,windows,gLineSpecColour,gLineSpecColourDash,gLineSpecColourDot,ps);

7. Troubleshooting

1. problems with MEX files

   If the function does not compile or does not load refer to the Matlab documentation for debugging C-MEX files. The Matlab mex compiler may be incorrectly configured for the user's environment. First verify that the mex compiler is working for both C files and C++ files. Note that C++ files are not officially supported by Matlab, though example and test files do exist within most distributions. Refer to the Matlab documents regarding the use of C++ files with the mex compiler.

Concept Index

Table of Contents

1. Notices
2. Introduction

2.1 Companion Software
2.2 Obtaining
2.3 Other Documentation

3. Installation

3.1 Dependencies
3.2 Platforms
3.3 Required Build Tools
3.4 Building
3.5 Environment

4. Using the readdext() Function
5. The Library Files
6. Examples
7. Troubleshooting
Concept Index

Short Table of Contents

1. Notices
2. Introduction
3. Installation
4. Using the readdext() Function
5. The Library Files
6. Examples
7. Troubleshooting
Concept Index

About this document

• 1. Section One
• 1.1 Subsection One-One
• ...
• 1.2 Subsection One-Two
• 1.2.1 Subsubsection One-Two-One
• 1.2.2 Subsubsection One-Two-Two
• 1.2.3 Subsubsection One-Two-Three     <== Current Position
• 1.2.4 Subsubsection One-Two-Four
• 1.3 Subsection One-Three
• ...
• 1.4 Subsection One-Four