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 git@github.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 pathtool
, addpath
, etc.):
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.
Constructor Summary
ecopathmodel
: Create an ecopathmodel object
Property Summary
dc
: Table of diet composition datadf
: Table of detritus fatesdiscard
: Table of fisheries discardsdiscardFate
: Table of discard fatesfleet
: Names corresponding to each fishing gear/fleet in the modelgroupdata
: Table of group-related parameterslanding
: Table of fisheries landingsname
: Names corresponding to each group in the modelngear
: Number of fishing gears/fleets in modelngroup
: Number of groups (living and detrital) in modelnlive
: Number of living groups (non-detrital) in modelpedigree
: Table of pedigree values applied to parametersstanza
: Names corresponding to each multi-stanza setstanzadata
: Table of multi-stanza-set-related parameters
Method Summary
addpedigree
: Add entries to the pedigree tablecalcstanza
: Calculate B and Q/B values for multi-stanza Ecopath groupscheckstanza
: Fill in (or validate) B, QB, and BA values for stanzascombinegroups
: Combine groups and/or fleets in an ecopathmodel objectcreateensemble
: Build an ensemble of Ecopath model parametersdisplaybasic
: Prints ecopath results to screenecopath
: Rewrite of Ecopath algorithmsgetpedigreevals
: Extract values corresponding to pedigree entriesgraph
: Convert ecopathmodel object to a diagraph objectnetworkindices
: Calculate ecological network indicessort
: Sort groups and fleets in an ecopathmodel objectsortbytrophic
: Sort ecopathmodel object groups by trophic levelstanzaindices
: Extract indices of stanza groups, in order of agesubpedigreevalues
: Replace values in ecopathmodel based on pedigreeunitconvert
: 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 fileseditstanzacalcs
: Replicate multi-stanza calculations from Ecopatheiixml2ecopathmodel
: Create ecopathmodel object from EwE6 .eiixml filemdb2ecopathmodel
: Create ecopathmodel object from EwE6 data filenetworkindices
: Calculate network indices for a food webrpath2ecopathmodel
: Create ecopathmodel object from Rpath data filestrophiclevel
: 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:
doc ecopathmodel
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
ver
at 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.
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).