Add Pielou's eveness, fix typo in documentation

docs/src/ecology.md

@@ -1,6 +1,6 @@
 # Diversity.Ecology
 
-n the **Diversity.Ecology** submodule, we replicate old ecological
+In the **Diversity.Ecology** submodule, we replicate old ecological
 diversity measures and generalised versions of them that relate to our
 general measures of alpha, beta and gamma diversity at subcommunity
 and ecosystem measures. The generalisations of the richness, Shannon
@@ -18,7 +18,7 @@ julia> using Diversity.Ecology, LinearAlgebra
 
 julia> community = [10, 20, 20];
 
-julia> community /= sum(community);
+julia> community /= sum(community); #Convert counts to proportions
 
 julia> diversity = simpson(community)
 1×7 DataFrame
@@ -55,6 +55,41 @@ julia> generalisedjaccard(ecosystem, [0, 1, 2], Matrix(1.0I, 3, 3))
 │ 1   │ Arbitrary Z │ Jaccard │ 0     │ types      │           │ metacommunity   │                │ 0.333333  │
 │ 2   │ Arbitrary Z │ Jaccard │ 1     │ types      │           │ metacommunity   │                │ 0.414214  │
 │ 3   │ Arbitrary Z │ Jaccard │ 2     │ types      │           │ metacommunity   │                │ 0.5       │
+
+julia> community = [0.7, 0.2, 0.1]
+
+julia> pielou(community)
+1×7 DataFrame
+ Row │ div_type  measure  type_level  type_name  partition_level  partition_name  diversity 
+     │ String    String   String      String     String           String          Float64   
+─────┼──────────────────────────────────────────────────────────────────────────────────────
+   1 │ Unique    Pielou   types                  subcommunity     1                0.729847
+
+julia> communitymat = [10 20 30 20 0; #5 sites/subcommunities (columns) and 6 species (rows)
+                       10 0 50 80 10;
+                       60 10 90 0 0; 
+                       10 10 10 10 10;
+                       70 70 70 70 70;
+                       10 0 0 90 0]
+
+julia> generalisedpielou(subcommunityDiversity, communitymat)
+5×7 DataFrame
+ Row │ div_type     measure  type_level  type_name  partition_level  partition_name  diversity 
+     │ String       String   String      String     String           String          Float64   
+─────┼─────────────────────────────────────────────────────────────────────────────────────────
+   1 │ Arbitrary Z  Pielou   types                  subcommunity     1                0.781115
+   2 │ Arbitrary Z  Pielou   types                  subcommunity     2                0.745557
+   3 │ Arbitrary Z  Pielou   types                  subcommunity     3                0.888073
+   4 │ Arbitrary Z  Pielou   types                  subcommunity     4                0.864562
+   5 │ Arbitrary Z  Pielou   types                  subcommunity     5                0.622366
+
+julia> generalisedpielou(metacommunityDiversity, communitymat)
+1×7 DataFrame
+ Row │ div_type     measure  type_level  type_name  partition_level  partition_name  diversity 
+     │ String       String   String      String     String           String          Float64   
+─────┼─────────────────────────────────────────────────────────────────────────────────────────
+   1 │ Arbitrary Z  Pielou   types                  metacommunity                     0.510146
+
 ```
 
 ```@contents

src/Diversity.jl

@@ -157,7 +157,7 @@ export generalisedrichness, richness
 export generalisedshannon, shannon
 export generalisedsimpson, simpson
 export generalisedjaccard, jaccard
-
+export generalisedpielou, pielou
 end # sub-module Ecology
 
 """

src/Ecology.jl

@@ -184,11 +184,11 @@ end
 Calculates Simpson's index (1 / diversity at q = 2) of a series of
 columns representing independent subcommunity counts.
 
-# Arguments:
+#### Arguments:
 
 - `proportions`: population proportions
 
-# Returns:
+#### Returns:
 
 - concentrations of subcommunities
 """
@@ -212,7 +212,7 @@ for the species. This gives a measure of the distinctness of the
 subcommunities, though we believe that beta and normalised beta have
 better properties.
 
-# Arguments:
+#### Arguments:
 
 - `proportions`: population proportions
 
@@ -221,7 +221,7 @@ better properties.
 - `Z`: similarity matrix or
 - `sim`: instance of AbstractTypes
 
-# Returns:
+#### Returns:
 
 - Jaccard-related distinctivess measures
 """
@@ -256,11 +256,11 @@ Calculates Jaccard index (Jaccard similarity coefficient) of two
 columns representing independent subcommunity counts, which is
 normmetaalpha(proportions, 0) / metagamma(proportions, 0) - 1
 
-# Arguments:
+#### Arguments:
 
 - `proportions`: population proportions
 
-# Returns:
+#### Returns:
 
 - the Jaccard index
 """
@@ -271,3 +271,85 @@ function jaccard(asm::EcoBase.AbstractAssemblage)
     hassimilarity(asm) && error("function cannot run with $(typeof(gettypes(asm))) types as contains similarity")
     return jaccard(occurrences(asm))
 end
+
+"""
+generalisedpielou::DiversityLevel, proportions::AbstractArray,
+                       Z::AbstractMatrix)
+generalisedpielou(level::DiversityLevel, proportions::AbstractArray,
+                       sim::AbstractTypes)
+
+Calculates a generalisation of Pielou's evenness for columns
+representing the counts or proportions of subcommunities. Values range from 
+zero to one, with one representing complete evenness within the 
+community. Since this is calculated as H / Hmax, and is just a proportion,
+values remain unchanged regardless of the value(s) of q supplied. 
+
+#### Arguments:
+- `level`: DiversityLevel to calculate at (e.g. subcommunityDiversity)
+
+- `proportions`: population proportions
+
+- `Z`: similarity matrix or
+- `sim`: instance of AbstractTypes
+
+#### Returns:
+- Pielou's evenness metric (at metacommunity level) or metrics (of subcommunities)
+"""
+function generalisedpielou end
+generalisedpielou(level::DiversityLevel,
+                   proportions::AbstractArray,
+                   Z::AbstractMatrix = Matrix(1.0I, size(proportions, 1), size(proportions, 1))) =
+    generalisedpielou(level, proportions, GeneralTypes(Z))
+
+function generalisedpielou(level::DiversityLevel,
+                            proportions::AbstractArray,
+                            sim::AbstractTypes)
+    if (level == subcommunityDiversity)
+        dm = ᾱ
+        ns = vec(sum(x->x>0, proportions, dims=1))
+    elseif (level == metacommunityDiversity)
+        dm = Gamma
+        ns = sum(x->x>0, proportions)
+    else
+        error("Can't calculate richness for $level")
+    end
+    gp = level(dm(Metacommunity(proportions, sim)), 1)
+    gp[!,:diversity] .= log.(gp[!,:diversity])./log.(ns)
+    gp[!,:measure] .= "Pielou"
+    select!(gp, Not(:q))
+    return gp
+end
+
+"""
+    pielou(proportions::AbstractMatrix)
+
+Calculates Pielou's evenness of a series of
+columns representing independent subcommunity counts.
+
+#### Arguments:
+
+- `proportions`: population proportions
+
+#### Returns:
+
+- evenness of subcommunities
+
+#### Example:
+```
+communitymat = [10 20 30 20 0; #5 sites/subcommunities (columns) and 6 species (rows)
+                10 0 50 80 10;
+                60 10 90 0 0; 
+                10 10 10 10 10;
+                70 70 70 70 70;
+                10 0 0 90 0]
+
+pielou(communitymat)
+```
+"""
+pielou(proportions::AbstractVecOrMat) =
+    generalisedpielou(subcommunityDiversity, proportions,
+                       UniqueTypes(size(proportions, 1)))
+function pielou(asm::EcoBase.AbstractAssemblage)
+    hassimilarity(asm) && error("function cannot run with $(typeof(gettypes(asm))) types as contains similarity")
+    return pielou(occurrences(asm))
+end

src/Metacommunity.jl

@@ -33,7 +33,6 @@ Metacommunity(abundances::AbstractArray,
   Partition. Should only be accessed through
   getordinariness!(::Metacommunity), which will populate the cache if
   it has not yet been calculated.
-
 """
 mutable struct Metacommunity{FP, ARaw, AProcessed, Sim, Part} <:
     Diversity.API.AbstractMetacommunity{FP, ARaw, AProcessed, Sim, Part}