Schoener's D index calculator for niche overlap.
GPL-3.0 License
Schoener's D index calculator for niche overlap.
D_{ij} = 1 - \frac{1}{2} \sum_{k = 1}^{S} \left\lvert P_{ik} - P_{jk} \right\rvert
schoenerd
is a CLI program designed to compute the Schoener's D Index for
niche overlap between pairs of species[^1] exploiting a common resource.
The following building instructions compile and install schoenerd
from the
git master
branch. They assume the Rust stable
toolchain (or any
version >= 1.70.0
) installed on the system[^3], as well as the
just
command runner.
git clone https://github.com/marcoradocchia/schoenerd
cd schoenerd
just build
sudo just install
By default, installation prefix is set to /usr/local
. To use a different
installation prefix, specify it via the PREFIX
environment variable as
PREFIX=<prefix> sudo just install
, where <prefix>
is a placeholder for the
desired path.
NOTE: The
install
recipe in thejustfile
is Linux-specific and not available on other platforms. In order to installschoenerd
on a non-Linux platform, manual installation of the build artifacts (binary, completions, manpage, etc.) is required.
Pre-compiled binary[^4] of the latest release, as well as shell completion scripts[^5] and manpage are available in GitHub releases.
Installing with Rust's cargo
package manager is available on any
platform (Linux, Windows, macOS, etc.).
NOTE:
cargo
installs theschoenerd
binary in$CARGO_HOME/bin
, however it ignores shell completions and manpage. If you need either of those, consider using one of the other installation options.
Build and install with cargo
on any platform from git master branch:
cargo install --git https://github.com/marcoradocchia/schoenerd --branch master
Build and install with cargo
on any platform from latest release:
cargo install schoenerd
For Arch Linux users, packages are available in the Arch User Repository:
schoenerd
:schoenerd-bin
:schoenerd-git
: buildsWARNING:
schoenerd
,schoenerd-bin
&schoenerd-git
AUR packages are mutually exclusive and conflict with each other.
You may install one of the above packages using an AUR helper, such as
yay
:
yay -S schoenerd-bin # or `schoenerd`, or `schoenerd-git`
or paru
:
paru -S schoenerd-bin # or `schoenerd`, or `schoenerd-git`
schoenerd
accepts input data either from stdin or input file
(using the -i/--input
option) and produces output either to stdout or output
file (using the -o/--output
option). This allows schoenerd
to be used as a
standalone program or inside a UNIX pipeline, which makes it suitable for
usage along with other programs or inside scripts.
Input data must be formatted as a Comma Separated Value table. Take as an example the data table below:
Bombus lapidarius | Bombus mesomelas | Bombus pascuorum | Bombus pratorum | |
---|---|---|---|---|
Carduus chrysacanthus | 0 | 0 | 0 | 1 |
Carlina acaulis | 0 | 0 | 1 | 0 |
Stachys germanica | 18 | 5 | 14 | 134 |
Trifolium pratense | 0 | 1 | 0 | 1 |
Trifolium repens | 0 | 4 | 0 | 6 |
Oxytropis campestris | 3 | 153 | 0 | 53 |
If one wanted to calculate the Schoener's D Index for each pair of pollinators, column headers of the table should contain each pollinator species, while row headers should contain each of the plant species representing the available resources. Each intersection cell must represent a non-negative integer value describing the interaction between each plant/pollinator pair (e.g. number of visits).
schoenerd
requires such a table to be serialized in a CSV format, like below:
,Bombus pratorum,Bombus lapidarius,Bombus mesomelas,Bombus pascuorum
Carduus chrysacanthus,1,0,0,0
Carlina acaulis,0,0,0,1
Stachys germanica,134,18,5,14
Trifolium pratense,1,0,1,0
Trifolium repens,6,0,4,0
Oxytropis campestris,53,3,153,0
By default schoenerd
produces CSV formatted output as shown below:
FIRST SPECIES,SECOND SPECIES,D INDEX
Bombus pratorum,Bombus lapidarius,0.8300366300366301
Bombus pratorum,Bombus mesomelas,0.3321378008494573
Bombus pratorum,Bombus pascuorum,0.6871794871794872
Bombus lapidarius,Bombus mesomelas,0.17353198948290982
Bombus lapidarius,Bombus pascuorum,0.8571428571428571
Bombus mesomelas,Bombus pascuorum,0.030674846625766916
Each record (line) of the output data contains three fields described by the CSV headers: first two fields contain the two pollinator species of which the D index is reported in the third field.
Using the -p/--pretty-table
flag the output is formatted into a table for
quick data visualization. Using the same input above, the produced result is
an ASCII version of the following table:
FIRST SPECIES | SECOND SPECIES | D INDEX |
---|---|---|
Bombus pratorum | Bombus lapidarius | 0.8300366300366301 |
Bombus pratorum | Bombus mesomelas | 0.3321378008494573 |
Bombus pratorum | Bombus pascuorum | 0.6871794871794872 |
Bombus lapidarius | Bombus mesomelas | 0.17353198948290982 |
Bombus lapidarius | Bombus pascuorum | 0.8571428571428571 |
Bombus mesomelas | Bombus pascuorum | 0.030674846625766916 |
Output of schoenerd -h
listed below:
schoenerd v0.1.0 - Marco Radocchia <[email protected]>, Gaia Di Francescantonio <[email protected]>
Schoener's D index calculator for niche overlap.
Usage:
schoenerd [OPTIONS]
Options:
-i, --input <FILE>
Input CSV file path
-f, --input-field-delimiter <CHAR>
Input CSV field delimiter
-t, --input-record-terminator <CHAR>
Input CSV record terminator
-c, --input-quote-character <CHAR>
Input CSV quote character
-o, --output <FILE>
Output CSV file path
-F, --output-field-delimiter <CHAR>
Output CSV field delimiter
-T, --output-record-terminator <CHAR>
Output CSV record terminator
-C, --output-quote-character <CHAR>
Output CSV quote character
-n, --disable-output-headers
Disable output headers
-s, --sort <DIRECTION>
Sort output by D index value [possible values: descending, ascending]
-p, --pretty-table
Display output as a pretty table on stdout
-h, --help
Print help (see more with '--help')
-V, --version
Print version
This project is licensed under GPLv3.
[^1]: Schoener, T.W. (1968) Anolis lizards of Bimini: resource parti tioning in
a complex fauna. Ecology, 49, 704–726.
[^2]: schoenerd
compiles on all platforms (Linux, Windows, macOs, ...) as
long as rust
and just
are correctly installed, however installation
recipes in the justfile
are currently Linux only.
[^3]: Install using rustup
.
[^4]: Currently x86_64-linux-gnu
only.
[^5]: Currently zsh
, bash
& fish
.