✨ omnivory index

docs/src/interface/types.md

@@ -72,7 +72,7 @@ AbstractEcologicalNetwork
 ```
 
 The type of nodes that are allowed is determined by the *non-exported*
-`EcologicalNetworks.is_valid_species` function. To allow an additional type of
+`EcologicalNetworks.check_species_validity` function. To allow an additional type of
 node, you can write the following:
 
 ~~~ julia
@@ -83,11 +83,13 @@ struct Foo
 end
 
 import EcologicalNetworks
-EcologicalNetworks.is_valid_species(::Type{Foo}) = true
+function EcologicalNetworks.check_species_validity(::Type{Foo})
+end
 ~~~
 
 Note that **integers are never valid species identifiers**. By default, `String`
-and `Symbol` are used.
+and `Symbol` are used. The function `check_species_validity` should do *nothing*
+for an accepted type (and it will throw an error for any other type).
 
 ### By partiteness
 

src/EcologicalNetworks.jl

@@ -38,9 +38,16 @@ include(joinpath(".", "misc/data.jl"))
 export web_of_life, nz_stream_foodweb, pajek
 
 function __init__()
-   @require Mangal="b8b640a6-63d9-51e6-b784-5033db27bef2" is_valid_species(::Mangal.MangalNode) = true
-   @require Mangal="b8b640a6-63d9-51e6-b784-5033db27bef2" is_valid_species(::Mangal.MangalReferenceTaxon) = true
-   @require GBIF="ee291a33-5a6c-5552-a3c8-0f29a1181037" is_valid_species(::GBIF.GBIFTaxon) = true
+   @require Mangal="b8b640a6-63d9-51e6-b784-5033db27bef2" begin
+      function check_species_validity(::Mangal.MangalReferenceTaxon)
+      end
+      function check_species_validity(::Mangal.MangalNode)
+      end
+   end
+   @require GBIF="ee291a33-5a6c-5552-a3c8-0f29a1181037" begin
+      function check_species_validity(::GBIF.GBIFTaxon)
+      end
+   end
 end
 
 # General useful manipulations
@@ -147,6 +154,9 @@ export KGL01, KGL02, KGL03, KGL04, KGL05, KGL06, KGL07, KGL08, KGL09, KGL10,
 include(joinpath(".", "foodwebs/trophiclevels.jl"))
 export fractional_trophic_level, trophic_level
 
+include(joinpath(".", "foodwebs/omnivory.jl"))
+export omnivory
+
 include(joinpath(".", "information/entropy.jl"))
 export entropy, make_joint_distribution, mutual_information, conditional_entropy,
    variation_information, diff_entropy_uniform, information_decomposition,

src/foodwebs/omnivory.jl

@@ -0,0 +1,24 @@
+function omnivory(N::T) where {T <: UnipartiteNetwork}
+    OI = Dict([s => 0.0 for s in species(N)])
+
+    TL = fractional_trophic_level(N)
+    k = degree(N; dims=1)
+
+    for sp_i in species(N)
+
+        # Species with no interaction have an omnivory index of 0
+        k[sp_i] > 0 || continue
+
+        # For every species, we set its initial omnivory to 0
+        oi = 0.0
+        for (j, sp_j) in enumerate(species(N))
+            # Then for every species it consumes, we ha
+            tl_diff = (TL[sp_j] - (TL[sp_i]-1.0)).^2.0
+            corr = N[sp_i,sp_j]/k[sp_i]
+            oi += tl_diff * corr
+        end
+        OI[sp_i] = oi
+    end
+
+    return OI
+end

src/types/constructors.jl

@@ -5,7 +5,7 @@ function UnipartiteNetwork(A::M) where {M<:AbstractMatrix{Bool}}
 end
 
 function UnipartiteNetwork(A::M, S::Vector{NT}) where {M<:AbstractMatrix{Bool}, NT}
-  is_valid_species($1) || throw(ArgumentError("$(NT) is not a valid type of node"))
+  check_species_validity(NT)
   check_unipartiteness(A, S)
   UnipartiteNetwork{Bool,NT}(A, S)
 end
@@ -18,7 +18,7 @@ function BipartiteNetwork(A::M) where {M<:AbstractMatrix{Bool}}
 end
 
 function BipartiteNetwork(A::M, T::Vector{NT}, B::Vector{NT}) where {M<:AbstractMatrix{Bool}, NT}
-  is_valid_species($1) || throw(ArgumentError("$(NT) is not a valid type of node"))
+  check_species_validity(NT)
   check_bipartiteness(A, T, B)
   BipartiteNetwork{Bool,eltype(T)}(A, T, B)
 end
@@ -32,7 +32,7 @@ function BipartiteProbabilisticNetwork(A::Matrix{IT}) where {IT<:AbstractFloat}
 end
 
 function BipartiteProbabilisticNetwork(A::Matrix{IT}, T::Vector{NT}, B::Vector{NT}) where {IT<:AbstractFloat, NT}
-  is_valid_species($1) || throw(ArgumentError("$(NT) is not a valid type of node"))
+  check_species_validity(NT)
   check_bipartiteness(A, T, B)
   check_probability_values(A)
   BipartiteProbabilisticNetwork{IT,NT}(A, T, B)
@@ -46,7 +46,7 @@ function BipartiteQuantitativeNetwork(A::Matrix{IT}) where {IT <: Number}
 end
 
 function BipartiteQuantitativeNetwork(A::Matrix{IT}, T::Vector{NT}, B::Vector{NT}) where {IT<:Number,NT}
-  is_valid_species($1) || throw(ArgumentError("$(NT) is not a valid type of node"))
+  check_species_validity(NT)
   check_bipartiteness(A, T, B)
   BipartiteQuantitativeNetwork{IT,NT}(A, T, B)
 end
@@ -58,7 +58,7 @@ function UnipartiteQuantitativeNetwork(A::Matrix{IT}) where {IT<:Number}
 end
 
 function UnipartiteQuantitativeNetwork(A::Matrix{IT}, S::Vector{NT}) where {IT<:Number,NT}
-  is_valid_species($1) || throw(ArgumentError("$(NT) is not a valid type of node"))
+  check_species_validity(NT)
   check_unipartiteness(A, S)
   UnipartiteQuantitativeNetwork{IT,NT}(A, S)
 end
@@ -73,7 +73,7 @@ function UnipartiteProbabilisticNetwork(A::Matrix{IT}) where {IT<:AbstractFloat}
 end
 
 function UnipartiteProbabilisticNetwork(A::Matrix{IT}, S::Vector{NT}) where {IT<:AbstractFloat,NT}
-  is_valid_species($1) || throw(ArgumentError("$(NT) is not a valid type of node"))
+  check_species_validity(NT)
   check_unipartiteness(A, S)
   check_probability_values(A)
   UnipartiteProbabilisticNetwork{IT,NT}(A, S)

src/types/utilities.jl

@@ -1,8 +1,11 @@
 import Base: getindex, setindex!, permutedims, permutedims!, size, copy, !, show, +, inv, similar
 
-is_valid_species(::Type{T}) where {T <: Any} = false
+function check_species_validity(::Type{T}) where {T <: Any}
+  throw(ArgumentError("The type $(T) is not an allowed species type"))
+end
 
-is_valid_species(::Type{T}) where {T <: Union{Symbol,String}} = true
+function check_species_validity(::Type{T}) where {T <: Union{Symbol,String}}
+end
 
 """
     show(io::IO, N::AbstractEcologicalNetwork)
@@ -70,7 +73,7 @@ for the presence of an interaction.
 Use `N[i,j]` if you need to get the value of the interaction.
 """
 function has_interaction(N::AbstractEcologicalNetwork, i::NT, j::NT) where {NT}
-  @assert is_valid_species(NT)
+  check_species_validity(NT)
   @assert i ∈ species(N; dims=1)
   @assert j ∈ species(N; dims=2)
   i_pos = something(findfirst(isequal(i), species(N; dims=1)),0)