Skip to content
BranchesTags

Repository files navigation

ForamEcoQS

ForamEcoQS is a cross-platform desktop application for ecological quality assessment based on benthic foraminifera. It targets .NET 10, uses Eto.Forms for the graphical interface - so the same code runs natively on Windows (WPF), Linux (GTK) and macOS (Cocoa) - and can also run in command-line mode. The software calculates multiple biotic and diversity indices from species-by-sample abundance matrices and assigns Ecological Quality Status (EQS) classes where implemented.

Supported architectures: x64 and arm64 on Linux and macOS, x64 and arm64 on Windows.

Authors and Affiliations

Department of Pure and Applied Sciences (DiSPeA), University of Urbino Carlo Bo (UniUrb)

Department of Geosciences, University of Fribourg (UNIFR)

Year: 2026

Citation

If you use ForamEcoQS in scientific work, please cite:

Mangiagalli, M., Frontalini, F., Cristallo, C., Francescangeli, F., 2026. ForamEcoQS: An analytical software suite for foraminiferal ecological quality status assessment. SoftwareX 35, 102921. https://doi.org/10.1016/j.softx.2026.102921

Overview

ForamEcoQS supports a practical analysis workflow:

  • Import abundance matrices from Excel or CSV files;
  • Create or edit sample tables directly in the application;
  • Clean and normalize sample data;
  • Calculate selected indices for each sample;
  • Review EQS classifications for supported indices;
  • Export tables, plots, and EQS agreement summaries.

Main Features

Data Input and Editing

  • Create an empty dataset.
  • Open existing datasets from Excel or CSV.
  • Detect and correct transposed sheets automatically (see Input File Layout).
  • Save the current dataset to Excel.
  • Create spreadsheet templates from reference lists.
  • Add, remove, and rename sample columns.
  • Undo recent data edits.
  • Clean and normalize sample values.
  • Transpose the loaded sheet at any time from Edit Data > Transpose Data (species ↔ samples).

Input File Layout

ForamEcoQS expects species down the first column and one sample per following column:

Species Station 1 Station 2 Station 3
Ammonia beccarii 10 20 5
Elphidium excavatum 5 3 12
Mud (%) 40 55 70

Spreadsheets are just as often written the other way round, with samples in rows and species across the header. Both the GUI and the CLI check the layout when a file is opened and flip it when needed, so either arrangement can be loaded as it is. The check looks at, in order:

  1. The label in the top-left corner (Species, Taxon, ... against Sample, Station, Site, ...).
  2. Which axis carries the optional mud (%) entry, since that sits on the sample axis.
  3. How many labels on each axis read like taxon names (Ammonia beccarii, Elphidium cf. excavatum, Quinqueloculina sp.) rather than sample codes (S3, St. 12, Station_A).

A clear-cut case is transposed straight away and reported; a borderline one asks first in the GUI and is left alone with a warning in the CLI. Nothing is ever transposed silently, and Edit Data > Transpose Data (species ↔ samples) flips the sheet by hand whenever the detection gets it wrong.

Index Calculation

  • Compute selected indices from the Advanced Indices workflow.
  • Choose threshold systems and reference options from Index Calculation Settings.
  • Apply optional EQR calculations for FSI and exp(H'bc).
  • Use selected Foram-AMBI lists for eco-group based indices.

Visualization and Export

  • Open plot options for calculated results.
  • Open a composite dashboard.
  • Load existing index tables for plotting without recalculation.
  • Export result tables to Excel.
  • Export plots to PNG.

Reference Lists Management

  • Foram-AMBI List Manager.
  • FSI List Manager.
  • Geographic Areas Database.
  • User Custom Lists Manager.
  • Ecological-group override support for taxa assignments.
  • Export and import ecological-group overrides as a JSON file, so they can be shared with collaborators or committed to version control alongside a dataset.

WoRMS Species Verification

Species that are not found in the selected local reference databank can optionally be checked against the WoRMS (World Register of Marine Species) online REST API. This is an opt-in feature that requires an internet connection.

For each unmatched name, WoRMS lookup can:

  • Confirm it is a recognized, valid marine taxon even though it is absent from the local databank (in the GUI, such rows are highlighted orange instead of red, and are no longer removed by Clean and Normalize).
  • Detect likely typos via fuzzy/phonetic name matching.
  • Surface the currently accepted scientific name when the entered name is an outdated synonym (e.g. a species that has since been reclassified into a different genus).

In the GUI, enable it via the "Verify unmatched species against WoRMS" checkbox in Index Calculation Settings (disabled by default). In CLI mode, pass the -worms flag (see below). Without WoRMS verification, the CLI still always reports which species were excluded from eco-group-based indices because they were not found in the reference databank.

EQS Comparison Tools

  • EQS summary table.
  • Pairwise Cohen's kappa matrix.
  • Confusion matrices between indices.
  • Kappa heatmap.
  • Exportable EQS agreement summary.

CLI Mode

  • Run the same calculator in command-line mode by passing arguments at startup.
  • Read the first worksheet from an Excel input file.
  • Print results to console or export them to Excel.

Calculated Indices

Core Ecological / Biotic Indices

  • Foram-AMBI
  • Foram-M-AMBI
  • FSI
  • TSI-Med
  • NQIf
  • FIEI
  • BENTIX
  • BQI
  • FoRAM Index

Diversity / Structure Metrics

  • exp(H'bc)
  • H'log2
  • H'ln
  • Simpson (1-D)
  • Pielou's J
  • ES100

Supporting Metrics

  • Species Richness (S)
  • Total Abundance (N)
  • Ecological group percentages (EG1-EG5)
  • FoRAM functional group percentages

Key Thresholds and Criteria Used by the Software

Foram-AMBI EQS Threshold Systems

The threshold system is selectable in Index Calculation Settings.

System High Good Moderate Poor Bad
Borja 2003 <= 1.2 <= 3.3 <= 4.3 <= 5.5 > 5.5
Parent 2021 < 1.4 < 2.4 < 3.4 < 4.4 >= 4.4
Bouchet 2025 (Brazilian transitional waters) < 1.4 < 1.8 < 3.0 <= 4.0 > 4.0

TSI-Med Criteria

Implemented formula:

TSI-Med = ((%TS - %TSref) / (100 - %TSref)) x 100

%TSref is derived from mud percentage (%mud) using the selected reference curve:

  • Barras 2014: %TSref = 5.0 + 0.3 x %mud
  • Parent 2021 (>125 µm): %TSref = 4.5 + 0.28 x %mud
  • Jorissen 2018 homogenized: %TSref = 3.6718 + 0.3247 x %mud

Supported EQS conventions:

Convention High Good Moderate Poor Bad
Parent 2021 <= 4 <= 16 <= 36 <= 64 > 64
Barras & Jorissen 2011 > 64 <= 64 <= 36 <= 16 <= 4

The second convention inverts the ecological meaning of low TSI values.

FSI EQS

Class Rule
High >= 9
Good >= 5.5
Moderate >= 2
Poor >= 1
Bad < 1

0 is treated as Azoic.

NQIf EQS

Class Rule
High >= 0.54
Good >= 0.45
Moderate >= 0.31
Poor >= 0.13
Bad < 0.13

exp(H'bc) Threshold Sets

Threshold Set High Good Moderate Poor Bad
O'Brien 2021 Norway >125 µm >= 10 >= 7 >= 5 > 2 <= 2
O'Brien 2021 Norway >63 µm >= 22 >= 13 >= 7 > 3 <= 3
O'Brien 2021 Italy >63 µm >= 5 >= 4 >= 3 > 2 <= 2

EQR Logic

Optional EQR mode is available for FSI and exp(H'bc).

  • EQR = Observed / Reference
  • The value is clamped to the 0.0-1.0 range.

EQS boundaries from EQR:

Class Rule
High >= 0.8
Good >= 0.6
Moderate >= 0.4
Poor >= 0.2
Bad < 0.2

Default reference values exposed by the settings dialog:

  • FSI reference value: 10.0
  • exp(H'bc) reference value: 20.0

Other Implemented EQS Classifications

Index High Good Moderate Poor Bad
BENTIX >= 4.5 >= 3.5 >= 2.5 >= 2.0 < 2.0
BQI >= 12 >= 8 >= 5 >= 2 < 2
Foram-M-AMBI >= 0.81 >= 0.61 >= 0.41 >= 0.21 < 0.21

For BENTIX and BQI, 0 is treated as Azoic.

FoRAM Index Interpretation

Implemented formula:

FI = (10 x Ps) + Po + (2 x Ph)

Where:

  • Ps = symbiont-bearing proportion
  • Po = stress-tolerant proportion
  • Ph = heterotrophic proportion

Interpretation:

  • > 4: suitable for coral growth
  • 2-4: marginal conditions
  • < 2: unsuitable for coral growth

Repository Layout

Project Target Purpose
src/ForamEcoQS.Core net10.0 Index calculations, databank loaders, WoRMS client and the CLI. No UI dependencies.
src/ForamEcoQS.App net10.0 The Eto.Forms user interface, shared by every platform.
src/ForamEcoQS.Gtk net10.0 Linux executable (GTK 3 backend).
src/ForamEcoQS.Wpf net10.0-windows Windows executable (WPF backend).
src/ForamEcoQS.Mac net10.0 macOS executable (Cocoa backend).

Requirements

  • .NET 10 SDK for build and run from source. Confirm the installation with dotnet --list-sdks; a 10.0.x entry is required.
  • Packaged releases include the .NET runtime; no separate .NET installation is required.
  • On Linux, GTK 3 must be present: libgtk-3-0 plus librsvg2-common and adwaita-icon-theme for correct icon rendering.
  • Bundled reference .csv and .xls files available at runtime (they are copied next to the executable automatically).

NuGet packages used by the projects:

  • Eto.Forms and the Eto.Platform.Gtk / Eto.Platform.Wpf / Eto.Platform.Mac64 backends
  • OxyPlot.Core and OxyPlot.Eto
  • ClosedXML
  • ExcelDataReader
  • ExcelDataReader.DataSet

Build note: only src/ForamEcoQS.Wpf is Windows-targeted, and it already sets EnableWindowsTargeting, so the whole solution builds from Linux and macOS as well.

Installation Tutorials

These instructions build and run the application from this repository.

Linux (Ubuntu / Debian)

  1. Install the .NET 10 SDK and the GTK runtime:

    sudo apt-get update
sudo apt-get install -y libgtk-3-0 librsvg2-common adwaita-icon-theme

  2. Clone, build and run:

    git clone https://github.com/uniurbit/ForamEcoQS.git
cd ForamEcoQS
dotnet run --project src/ForamEcoQS.Gtk -c Release

macOS (Intel and Apple Silicon)

  1. Install the .NET 10 SDK.

  2. Clone, build and run:

    git clone https://github.com/uniurbit/ForamEcoQS.git
cd ForamEcoQS
dotnet run --project src/ForamEcoQS.Mac -c Release

    ./build/publish.sh osx-arm64 (or osx-x64) additionally produces a double-clickable ForamEcoQS.app bundle under artifacts/.

Windows 11

  1. Install the .NET 10 SDK, then close and reopen the terminal so its PATH is refreshed.

  2. Clone the repository and enter its directory:

    git clone https://github.com/uniurbit/ForamEcoQS.git
cd ForamEcoQS

  3. Confirm that an SDK in the 10.0.x series is available:

    dotnet --list-sdks

  4. Restore, build, and start the GUI:

    dotnet restore ForamEcoQS.sln
dotnet build ForamEcoQS.sln -c Release
dotnet run --project src\ForamEcoQS.Wpf -c Release

Windows 10

  1. Install all pending Windows updates, then install the .NET 10 SDK.

  2. Open a new PowerShell window and verify the SDK:

    dotnet --info

    The output must list a 10.0.x SDK.

  3. Follow steps 2–4 in the Windows 11 tutorial above. The commands and expected behavior are identical on Windows 10.

Packaged Windows releases include the .NET Desktop Runtime. Building from this source repository requires the SDK.

Build

The whole solution builds on any operating system:

dotnet restore ForamEcoQS.sln
dotnet build ForamEcoQS.sln -c Release

Run

Run the GUI

Pick the head that matches your operating system:

dotnet run --project src/ForamEcoQS.Gtk    # Linux
dotnet run --project src/ForamEcoQS.Mac    # macOS
dotnet run --project src/ForamEcoQS.Wpf    # Windows

If no command-line arguments are passed, the application starts in GUI mode, shows the splash screen, and then opens the main window.

Create a Standalone Build

build/publish.sh publishes any supported target with its .NET runtime into artifacts/<rid>/:

./build/publish.sh                 # every target
./build/publish.sh linux-arm64     # or a specific runtime identifier

Supported runtime identifiers: linux-x64, linux-arm64, osx-x64, osx-arm64, win-x64, win-arm64. For macOS targets the script creates a self-contained ForamEcoQS.app bundle, including the .NET runtime, reference databanks and application icon:

./build/publish.sh osx-arm64 osx-x64

The bundles are written to artifacts/osx-arm64/ForamEcoQS.app (Apple Silicon) and artifacts/osx-x64/ForamEcoQS.app (Intel). On macOS, the script also creates a ZIP archive for each bundle, preserving executable permissions. Cross-publishing from Windows or Linux creates a .tar.gz archive instead. Extract the archive and copy ForamEcoQS.app into Applications; no separate .NET installation is required for these macOS packages. These packages are not Developer ID signed or notarized.

The GitHub Actions build workflow runs only manually, through Actions > build > Run workflow. It does not run on pushes or pull requests. A manual run builds and tests Windows x64, Linux x64/ARM64 and macOS Intel/Apple Silicon on matching runners. It uploads Windows/macOS ZIP archives and Linux tar archives, with checks for bundle structure, architecture, CLI calculations and Linux GUI startup. Local packaging does not use GitHub Actions.

For Windows and Linux, distribute the complete artifacts/<rid> directory, not only the executable: the bundled .csv and .xls reference databanks in that directory are required for indices that use reference lists.

The published executable accepts the same CLI arguments as dotnet run. For example:

./artifacts/linux-x64/ForamEcoQS -i ~/data/input.xlsx -index=all -list jorissen -o ~/data/results.xlsx -mud=50

Run the CLI

The command line runs on every platform and never initialises a UI toolkit:

dotnet run --project src/ForamEcoQS.Gtk -- -i INPUT_FILE [options]

Supported options:

  • -i INPUT_FILE
  • -index=INDEX_LIST
  • -list LIST_NAME
  • -o OUTPUT_FILE
  • -mud=VALUE
  • -worms (verify species not found in the reference databank against the WoRMS online database; requires internet access)
  • -transpose (force transposing the input, for files with species in columns and samples in rows)
  • -no-transpose (never transpose the input, even when it looks the wrong way round)
  • -help
  • --help
  • /?

Supported reference list names for -list:

  • jorissen
  • alve
  • bouchetmed
  • bouchetatl
  • bouchetsouthatl
  • OMalley2021

Accepted index names in -index=:

  • exp(H'bc)
  • H'log2
  • H'ln
  • FSI
  • TSI-Med
  • NQIf
  • FIEI
  • Foram-AMBI
  • Foram-M-AMBI
  • BENTIX
  • BQI
  • FoRAM Index
  • Species Richness (S)
  • Total Abundance (N)
  • Simpson (1-D)
  • Pielou's J
  • ES100

Example:

dotnet run --project src/ForamEcoQS.Gtk -- -i data.xlsx -index=all -list jorissen -o results.xlsx -mud=50

Example with WoRMS verification of unmatched species:

dotnet run --project src/ForamEcoQS.Gtk -- -i data.xlsx -index=all -list jorissen -o results.xlsx -worms

Worked CLI Verification Example

Use this small, deterministic example to verify that the CLI, input parsing, and Excel export work after installation.

  1. Create an Excel workbook named verification-input.xlsx. Its first worksheet must contain the following table, with the first row used as headers:

    Species Sample_A Sample_B
    Taxon alpha 10 0
    Taxon beta 20 25
    Taxon gamma 0 5

  2. From the repository root, run:

    dotnet run --project src/ForamEcoQS.Gtk -c Release -- -i ./verification-input.xlsx "-index=Species Richness (S),Total Abundance (N)" -o ./verification-results.xlsx

  3. The command must finish with Results saved. and Done.. Open the Results worksheet in verification-results.xlsx and verify these values:

    Index Sample_A Sample_B
    Species Richness (S) 2 2
    Total Abundance (N) 30 30

This example intentionally uses indices that do not require a reference databank. To calculate reference-list-dependent indices such as Foram-AMBI, add -list jorissen (or another supported list) to the command.

Input File Format

The expected input layout is a species-by-sample matrix:

  • The first column must contain species names;
  • Each following column represents one sample;
  • Positive numeric values are treated as abundances.

CLI mode supports Excel .xls and .xlsx files and reads the first worksheet. GUI mode also supports CSV import.

Troubleshooting

Symptom Cause Resolution
dotnet is not recognized The SDK is not installed or the current terminal has an outdated PATH. Install the .NET 10 SDK, close every terminal window, open a new PowerShell window, and run dotnet --info.
NETSDK1045 or an error saying net10.0-windows is unsupported An older SDK is being used. Install .NET 10 SDK and ensure dotnet --list-sdks shows 10.0.x. Remove or update any repository/user global.json that pins an older SDK.
Unable to load shared library 'libgtk-3.so.0' on Linux The GTK 3 runtime is missing. sudo apt-get install -y libgtk-3-0 librsvg2-common adwaita-icon-theme (or the equivalent for your distribution).
Error: Input file ... not found The -i path is incorrect or not quoted. Use an absolute path or quote a path containing spaces, for example -i "C:\Data\input file.xlsx".
Error: Input file is empty or invalid The file is not a readable Excel workbook, has no rows, or its first worksheet has no header row. Save the data as .xls or .xlsx, place species names in the first column, and include a header row.
Error: Could not load reference databank The list name is invalid or the application is not run from its build/project output. Use one of the documented list names (for example jorissen) and run with dotnet run --project src/ForamEcoQS.Gtk (or the head for your platform) so bundled data files are copied to the output directory.
Excel export fails because the file is in use results.xlsx is open in Excel or another application. Close the file, choose a different output name, and rerun the command.

Output and Exports

ForamEcoQS can produce:

  • Calculated result tables in the Advanced Indices window;
  • An EQS summary table;
  • Excel exports of results;
  • PNG exports for generated plots;
  • Exports for EQS agreement outputs, including the kappa matrix.

Tools and Databanks

The application includes:

  • Selectable Foram-AMBI reference lists;
  • A Foram-AMBI List Manager;
  • An FSI List Manager;
  • A Geographic Areas Database;
  • A User Custom Lists Manager;
  • Taxon-specific ecological-group overrides;
  • Template generation from lists.

Notes and Limitations

  • The GUI runs on Windows, Linux and macOS through Eto.Forms; each platform uses its own native widget set, so small visual differences between platforms are expected.
  • Some indices depend on the selected databank and species classification coverage.
  • TSI-Med depends on mud percentage and the selected reference curve.
  • FoRAM Index is mainly meaningful for tropical or subtropical reef settings; the software warns when too little of a sample's assemblage matches a FoRAM functional group for the index to be meaningful.
  • Azoic is treated separately from Bad in several EQS outputs.
  • WoRMS species verification (GUI checkbox or -worms in the CLI) is optional and requires internet access; results depend on the availability and currency of the WoRMS online database at the time of the query.

References

  • Borja A. et al. (2003). AMBI classification boundaries.
  • Parent B. et al. (2021). Foram-AMBI and TSI-related threshold updates.
  • Bouchet V.M.P. et al. (2025). Brazilian transitional waters Foram-AMBI thresholds.
  • Barras C. et al. (2014). TSI-Med reference relationship.
  • Jorissen F.J. et al. (2018). Foram-AMBI Mediterranean development.
  • O'Brien B.J. et al. (2021). exp(H'bc) thresholds and related foraminiferal EQS work.
  • Dimiza M.D. et al. (2016). Foram Stress Index.
  • Alve E. et al. (2019). Norwegian Quality Index for foraminifera.
  • Simboura N. and Zenetos A. (2002). BENTIX.
  • Rosenberg R. et al. (2004). BQI framework.
  • Muxika I. et al. (2007). M-AMBI / multivariate ecological quality approach.
  • Hallock P. et al. (2003). Original FoRAM Index.
  • Prazeres M. et al. (2020). FoRAM Index revisit.
  • Mojtahid M. et al. (2006). FIEI.
  • WoRMS Editorial Board. World Register of Marine Species. Available from https://www.marinespecies.org at VLIZ. doi:10.14284/170.

About

ForamEcoQS (Foraminiferal Ecological Quality Status) is a comprehensive software tool designed to calculate biotic indices based on benthic foraminifera for assessing the ecological quality of marine environments.

Resources

Readme
MIT license
Activity
Custom properties

Stars

1 star

Watchers

1 watching

Forks

3 forks
Report repository

Releases

Packages

Contributors

Languages