ecopath_matlab: A Matlab implementation of Ecopath
Updated 13 Jul 2022
A Matlab implementation of Ecopath
Author: Kelly Kearney
This package provides a Matlab-based implementation of the Ecopath algorithm (part of the popular fisheries ecosystem modeling tool Ecopath with Ecosim), as well as a few functions for further analysis and visualization of an Ecopath-style food web.
This software is intended for people already familiar with the Ecopath concept who wish to perform that particular calculation, as well as related analysis of food web properties, outside of the GUI environment provided by the original EwE software. It assumes a basic working knowledge of Matlab.
If you use this code in your research, please cite as follows:
K. A. Kearney, “ecopath_matlab: A Matlab-based implementation of the Ecopath food web algorithm,” Journal of Open Source Software, vol. 2, no. 9, 2017.
This software requires Matlab R2015b or later (everything except the graph method should be functional in R2014b or later). It also requires the Statistics and Machine Learning Toolbox.
No OS limitations beyond those required for Matlab itself.
At present, this package is not compatible with Octave (v4.0.3).
Git users can clone directly:
git clone email@example.com:kakearney/ecopath_matlab-pkg
Alternatively, you may download a zipped version of the source code via the Clone or Download > Download zip button above, or from the ecopath_matlab entry on the MatlabCentral File Exchange. The File Exchange entry is updated daily from this repository.
The following folders need to be added to you Matlab Path (via
ecopath_matlab-pkg/ConsoleProgressBar ecopath_matlab-pkg/aggregate ecopath_matlab-pkg/cellstr2 ecopath_matlab-pkg/cprintf ecopath_matlab-pkg/ecopath_matlab ecopath_matlab-pkg/legendflex ecopath_matlab-pkg/readtext ecopath_matlab-pkg/regexpfound ecopath_matlab-pkg/setgetpos_V1.2 ecopath_matlab-pkg/wraptext
This package centers around a custom Matlab class,
ecopathmodel. The properties of an
ecopathmodel object hold the typical input parameters associated with a single ecosystem food web; the methods provide functions to calculate Ecopath mass balance.
ecopathmodel: Create an ecopathmodel object
dc: Table of diet composition data
df: Table of detritus fates
discard: Table of fisheries discards
discardFate: Table of discard fates
fleet: Names corresponding to each fishing gear/fleet in the model
groupdata: Table of group-related parameters
landing: Table of fisheries landings
name: Names corresponding to each group in the model
ngear: Number of fishing gears/fleets in model
ngroup: Number of groups (living and detrital) in model
nlive: Number of living groups (non-detrital) in model
pedigree: Table of pedigree values applied to parameters
stanza: Names corresponding to each multi-stanza set
stanzadata: Table of multi-stanza-set-related parameters
addpedigree: Add entries to the pedigree table
calcstanza: Calculate B and Q/B values for multi-stanza Ecopath groups
checkstanza: Fill in (or validate) B, QB, and BA values for stanzas
combinegroups: Combine groups and/or fleets in an ecopathmodel object
createensemble: Build an ensemble of Ecopath model parameters
displaybasic: Prints ecopath results to screen
ecopath: Rewrite of Ecopath algorithms
getpedigreevals: Extract values corresponding to pedigree entries
graph: Convert ecopathmodel object to a diagraph object
networkindices: Calculate ecological network indices
sort: Sort groups and fleets in an ecopathmodel object
sortbytrophic: Sort ecopathmodel object groups by trophic level
stanzaindices: Extract indices of stanza groups, in order of age
subpedigreevalues: Replace values in ecopathmodel based on pedigree
unitconvert: Convert units of parameter values
A few additional functions are provided alonside the
ecopathmodel class, including functions for import and export of data, as well as a few helper functions that are called by the
ecopathmodel class methods but can also be called independently by users:
ecopathmodel2rpath: Print ecopathmodel data to comma-delimited files
editstanzacalcs: Replicate multi-stanza calculations from Ecopath
mdb2ecopathmodel: Create ecopathmodel object from EwE6 data file
networkindices: Calculate network indices for a food web
rpath2ecopathmodel: Create ecopathmodel object from Rpath data files
trophiclevel: Estimates trophic level of food web members
Documentation for each function and method in this package is provided via standard Matlab function headers, accessed in Matlab via the
help command. The reference page for the
ecopathmodel class (including links to descriptions of all properties and methods) can be accessed by typing the following in the Matlab Command Window:
For an overview of the class, along with several examples of usage, please see the overview document:
ecopathmodel_overview.m. A published version of this file can be found in html/ecopathmodel_overview.html.
If you use this code in a scientific publication, please cite using the Journal of Open Source Software documentation paper (see JOSS badge link above).
Community contributions to this package are welcome!
To report bugs, please submit an issue here, and include:
- your operating system
- your version of Matlab and all relevant toolboxes (type
verat the Matlab command line to get this info)
- code/data to reproduce the error or buggy behavior, and the full text of any error messages received
Please also feel free to submit enhancement requests, or to send pull requests for bug fixes or new features.
I do monitor the MatlabCentral FileExchange entry for any issues raised in the comments, but would prefer to track issues here on GitHub.
A note on versions
I maintain tagged versions of this software for citation purposes only. Actual improvements to the code are made continuously as issues arise, and are not labeled with version numbers. My numbering system is, roughly:
- 0.x: ecopathlite.m in its infancy, tailored to my Ph.D. thesis work.
- 1.x: The mostly-stable ecopathlite.m code suite (available on GitHub as ecopathlite-pkg). I plan to keep that code around for back-compatibility and previous citation purposes, but am no longer making any updates to it.
- 2.x: Rewrite of ecopathlite.m and its companion functions with an object-oriented approach; reorganized, fully-documented, and now intended for full use by others.
I began syncing the GitHub repository and the MatlabCentral File Exchange (FEX) entry in May 2015; the FEX labels that entry as "1.3". Version numbers on the FEX prior to that point were automatically assigned by MatlabCentral, and do not match up to the tagged versions in the GitHub repo. Please only use the GitHub tagged release numbers, and not the FEX numbers, if you need to reference a particular release. As noted above, the preferred method of citation for this code is to cite its companion documentation paper (see JOSS badge above).
Kearney, Kelly A. “ecopath_matlab: A Matlab-Based Implementation of the Ecopath Food Web Algorithm.” The Journal of Open Source Software, vol. 2, no. 9, The Open Journal, Jan. 2017, p. 64, doi:10.21105/joss.00064.
MATLAB Release Compatibility
Platform CompatibilityWindows macOS Linux
- Mathematics and Optimization > Global Optimization Toolbox > Particle Swarm >
- Sciences > Food Sciences >
- Sciences > Agriculture >
Inspired by: GRIDXY, plots.m, plotses.m, readtext, SETPOS 1.2 - GETPOS 1.2, cprintf - display formatted colored text in Command Window, ConsoleProgressBar, wraptext
Community Treasure Hunt
Find the treasures in MATLAB Central and discover how the community can help you!Start Hunting!
Discover Live Editor
Create scripts with code, output, and formatted text in a single executable document.
Versions that use the GitHub default branch cannot be downloaded
Linked GitHub readme and DOI for JOSS paper
Corrected typo in description
Updated description to reference github readme.
- Calculations are now robust to all potential input models, including those with multi-stanza groups.
Corrected FEX image
- Major overhaul to the createensemble routines: more flexibility, new sampling options, and improved efficiency