Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/marcoradocchia/schoenerd
Schoener's D index calculator for niche overlap.
https://github.com/marcoradocchia/schoenerd
d-index index niche niche-d niche-overlap overlap rust schoener schoener-d schoener-d-index schoener-index
Last synced: 2 months ago
JSON representation
Schoener's D index calculator for niche overlap.
- Host: GitHub
- URL: https://github.com/marcoradocchia/schoenerd
- Owner: marcoradocchia
- License: gpl-3.0
- Created: 2023-06-04T22:23:05.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2023-06-11T08:31:25.000Z (over 1 year ago)
- Last Synced: 2024-05-01T17:39:16.905Z (8 months ago)
- Topics: d-index, index, niche, niche-d, niche-overlap, overlap, rust, schoener, schoener-d, schoener-d-index, schoener-index
- Language: Rust
- Homepage:
- Size: 58.6 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Citation: CITATION.cff
Awesome Lists containing this project
README
schoenerd
Schoener's D index calculator for niche overlap.
```math
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.
# Installation
## Build from source[^2]
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`](https://github.com/casey/just) command runner.
```sh
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= sudo just install`, where `` is a placeholder for the
desired path.
> **NOTE**: The `install` recipe in the `justfile` is Linux-specific and not
> available on other platforms. In order to install `schoenerd` on a
> non-Linux platform, manual installation of the build artifacts
> (binary, completions, manpage, etc.) is required.
## GitHub releases
Pre-compiled binary[^4] of the
[latest release](https://github.com/marcoradocchia/schoenerd/releases/latest),
as well as shell completion scripts[^5] and manpage are available in
GitHub releases.
## Cargo
Installing with Rust's `cargo` package manager is available on any
platform (Linux, Windows, macOS, etc.).
> **NOTE**: `cargo` installs the `schoenerd` 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.
### Master Branch
Build and install with `cargo` on any platform from git master branch:
```sh
cargo install --git https://github.com/marcoradocchia/schoenerd --branch master
```
### [crates.io](https://crates.io/crates/schoenerd)
Build and install with `cargo` on any platform from latest release:
```sh
cargo install schoenerd
```
## Arch User Repository
For Arch Linux users, packages are available in the **A**rch **U**ser
**R**epository:
- [`schoenerd`](https://aur.archlinux.org/packages/schoenerd):
builds from source, from latest release;
- [`schoenerd-bin`](https://aur.archlinux.org/packages/schoenerd-bin):
pre-compiled binary[^4] of the latest release;
- [`schoenerd-git`](https://aur.archlinux.org/packages/schoenerd-git): builds
from source, from git master branch.
> **WARNING**: `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`](https://github.com/Jguer/yay):
```sh
yay -S schoenerd-bin # or `schoenerd`, or `schoenerd-git`
```
or [`paru`](https://github.com/Morganamilo/paru):
```sh
paru -S schoenerd-bin # or `schoenerd`, or `schoenerd-git`
```
# Usage
`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 format
Input data must be formatted as a **C**omma **S**eparated **V**alue 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
```
## Output format
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.
### Pretty table
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 |
## Help
Output of `schoenerd -h` listed below:
```
schoenerd v0.1.0 - Marco Radocchia , Gaia Di Francescantonio
Schoener's D index calculator for niche overlap.
Usage:
schoenerd [OPTIONS]
Options:
-i, --input
Input CSV file path
-f, --input-field-delimiter
Input CSV field delimiter
-t, --input-record-terminator
Input CSV record terminator
-c, --input-quote-character
Input CSV quote character
-o, --output
Output CSV file path
-F, --output-field-delimiter
Output CSV field delimiter
-T, --output-record-terminator
Output CSV record terminator
-C, --output-quote-character
Output CSV quote character
-n, --disable-output-headers
Disable output headers
-s, --sort
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
```
# License
This project is licensed under [GPLv3](LICENSE).
[^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`](https://www.rust-lang.org/tools/install).
[^4]: Currently `x86_64-linux-gnu` only.
[^5]: Currently `zsh`, `bash` & `fish`.