Cleaned notation, wrote documentation

.Rproj.user/5B9FC3CC/pcs/source-pane.pper

@@ -1,3 +1,3 @@
 {
-    "activeTab" : 6
+    "activeTab" : 0
 }

.Rproj.user/5B9FC3CC/pcs/windowlayoutstate.pper

@@ -1,14 +1,14 @@
 {
     "left" : {
-        "panelheight" : 1085,
-        "splitterpos" : 629,
+        "panelheight" : 1113,
+        "splitterpos" : 841,
         "topwindowstate" : "NORMAL",
-        "windowheight" : 1123
+        "windowheight" : 1151
     },
     "right" : {
-        "panelheight" : 1085,
-        "splitterpos" : 464,
+        "panelheight" : 1113,
+        "splitterpos" : 475,
         "topwindowstate" : "NORMAL",
-        "windowheight" : 1123
+        "windowheight" : 1151
     }
 }

.Rproj.user/5B9FC3CC/pcs/workbench-pane.pper

@@ -1,4 +1,4 @@
 {
     "TabSet1" : 2,
-    "TabSet2" : 0
+    "TabSet2" : 1
 }

.Rproj.user/5B9FC3CC/persistent-state

@@ -1,6 +1,6 @@
 build-last-errors="[]"
 build-last-errors-base-dir="~/RPackages/eyeball/"
-build-last-outputs="[{\"output\":\"==> R CMD INSTALL --no-multiarch --with-keep.source eyeball\\n\\n\",\"type\":0},{\"output\":\"* installing to library ‘/home/sallesina/R/x86_64-pc-linux-gnu-library/3.1’\\n\",\"type\":1},{\"output\":\"* installing *source* package ‘eyeball’ ...\\n\",\"type\":1},{\"output\":\"** R\\n\",\"type\":1},{\"output\":\"** preparing package for lazy loading\\n\",\"type\":1},{\"output\":\"\",\"type\":1},{\"output\":\"** help\\n\",\"type\":1},{\"output\":\"\",\"type\":1},{\"output\":\"*** installing help indices\\n\",\"type\":1},{\"output\":\"\",\"type\":1},{\"output\":\"** building package indices\\n\",\"type\":1},{\"output\":\"\",\"type\":1},{\"output\":\"** testing if installed package can be loaded\\n\",\"type\":1},{\"output\":\"\",\"type\":1},{\"output\":\"* DONE (eyeball)\\n\",\"type\":1},{\"output\":\"\",\"type\":1}]"
+build-last-outputs="[{\"output\":\"==> R CMD INSTALL --no-multiarch --with-keep.source eyeball\\n\\n\",\"type\":0},{\"output\":\"* installing to library ‘/home/sallesina/R/x86_64-pc-linux-gnu-library/3.1’\\n\",\"type\":1},{\"output\":\"* installing *source* package ‘eyeball’ ...\\n\",\"type\":1},{\"output\":\"\",\"type\":1},{\"output\":\"** R\\n\",\"type\":1},{\"output\":\"** preparing package for lazy loading\\n\",\"type\":1},{\"output\":\"\",\"type\":1},{\"output\":\"** help\\n\",\"type\":1},{\"output\":\"*** installing help indices\\n\",\"type\":1},{\"output\":\"\",\"type\":1},{\"output\":\"** building package indices\\n\",\"type\":1},{\"output\":\"\",\"type\":1},{\"output\":\"** testing if installed package can be loaded\\n\",\"type\":1},{\"output\":\"\",\"type\":1},{\"output\":\"* DONE (eyeball)\\n\",\"type\":1},{\"output\":\"\",\"type\":1}]"
 compile_pdf_state="{\"errors\":[],\"output\":\"\",\"running\":false,\"tab_visible\":false,\"target_file\":\"\"}"
 console_procs="[]"
 files.monitored-path=""

.gitignore

@@ -1,5 +1,4 @@
 *~
-Code/FigureComparison/Matrices
-Code/SortedComparison/AdjacencyMatrices
-
 .Rproj.user
+.Rhistory
+

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: eyeball
 Version: 0.1
-Date: 2015-06-15
+Date: 2015-06-19
 Title: Approximations for the real part of the leading eigenvalue of large
     community matrices.
 Description: This package provides a set of functions to: a) Build food webs b)

NAMESPACE

@@ -6,6 +6,7 @@ export(eye.ellipse.df)
 export(eye.foodweb.cascade)
 export(eye.foodweb.file)
 export(eye.foodweb.niche)
+export(eye.foodweb.random)
 export(eye.pairs.from.empirical)
 export(eye.pairs.from.fourcorner)
 export(eye.pairs.from.normal)

R/eye.approximations.R

@@ -1,6 +1,35 @@
+#' Calculates various approximations for the real part of the leading eigenvalue
+#' of the community matrix M.
+#'
+#' It returns the expectation for the real part of the rightmost eigenvalue of M
+#' according to May (Nature 1972), Tang et al (Ecology Letters 2014), and
+#' Allesina et al. (Nature Communications 2015) derivations.
+#'
+#'
+#' @param M The community matrix. Note that for the Allesina et al. (eyeball) approximation, M should contain (almost) no
+#'        positive coefficients in the upper triangular part and (almost) no negative coefficients in the lower-triangular
+#'        part
+#' @param calculate_eigenvalues (TRUE by default) calculate the actual eigenvalues of M and return them
+#'
+#' @return A list composed of:
+#' \describe{
+#' \item{$M}{The community matrix}
+#' \item{$M.eigenvalues}{The eigenvalues of M (if calculate_eigenvalues = TRUE)}
+#' \item{$ReL1.observed }{The actual real part of the rightmost eigenvalue of M}
+#' \item{$ReL1.May }{The prediction according to May's approximation}
+#' \item{$ReL1.TangEtAl}{The prediction according to Tang et al. approximation}
+#' \item{$ReL1.eyeball}{The prediction according to the "eyeball" approach in Allesina et al. }
+#' \item{$May.stats}{List containing the relevant statistics for computing May's approximation}
+#' \item{$TangEtAl.stats}{List containing the relevant statistics for computing the approximation of Tang et al.}
+#' \item{$eyeball.stats}{List containing the relevant statistics for computing the eyeball approximation of Allesina et al.}
+#' }
+#'
+#' @examples
+#' M <- eye.parameterize.M(eye.foodweb.cascade())
+#' eye.approximate.ReL1(M)
 #' @export
-eye.approximate.ReL1 <- function(M, calculate.eigenvalues = TRUE){
-  if (calculate.eigenvalues == TRUE){
+eye.approximate.ReL1 <- function(M, calculate_eigenvalues = TRUE){
+  if (calculate_eigenvalues == TRUE){
     ev <- eigen(M, only.values = TRUE, symmetric = FALSE)$values
   }
   S <- dim(M)[1]
@@ -46,16 +75,9 @@ eye.approximate.ReL1 <- function(M, calculate.eigenvalues = TRUE){
   ReL1.observed <- NULL
   M.eigenvalues <- NULL
   ## if desired, calculate the actual ReL1.observed
-  if (calculate.eigenvalues == TRUE){
+  if (calculate_eigenvalues == TRUE){
     ReL1.observed <- max(Re(ev))
     M.eigenvalues <- ev
-    ## Debug
-    #print(plot(ev, xlim = c(min(Re(ev)), 1 + max(c(ReL1.observed, ReL1.May, ReL1.TangEtAl)))))
-    #print(abline(v = ReL1.observed, col = "black"))
-    #print(abline(v = ReL1.May, col = "red"))
-    #print(abline(v = ReL1.TangEtAl, col = "blue"))
-    #print(abline(v = ReL1.eyeball, col = "pink"))
-    ## End Debug
   }
   return(list(M = M,
               M.eigenvalues = M.eigenvalues,

R/eye.buildcommunitymatrix.R

@@ -1,32 +1,48 @@
-#' @export
+#' Builds a community matrix M based on a food web, and a parameterization for the bivariate distribution
+#'
+#' @param FW A food web object, produced by the method eye.foodweb.cascade or similar
+#' @param distribution_pairs A bivariate distribution for the pairs (possibilities are "Normal", "FourCorner", or an empirical distribution, represented by a Nx2 matrix of pairs)
+#' @param mux Mean of the negative interaction strengths
+#' @param muy Mean of the positive interaction strengths
+#' @param sigmax Standard deviation of the negative interaction strengths
+#' @param sigmay Standard deviation of the positive interaction strengths
+#' @param rhoxy Correlation between the interaction strengths
+#' @param mu_diagonal (0 by default) mean of the diagonal elements
+#' @param sigma_diagonal (0 by default) standard deviation for the diagonal elements
 #'
+#' @return The community matrix M
+#' @examples
+#' M <- eye.parameterize.M(eye.foodweb.cascade())
+#' M <- eye.parameterize.M(eye.foodweb.niche(size = 30, connectance = 0.2),
+#'      distribution_pairs = "FourCorner", mux = -1, muy = 1, sigmax = 2, sigmay = 1, rhoxy = -0.5)
+#' @export
 eye.parameterize.M <- function(FW,
-                               distribution.pairs = "Normal",
+                               distribution_pairs = "Normal",
                                mux = -1,
                                muy = 0.5,
                                sigmax = 1/4,
                                sigmay = 1/4,
                                rhoxy = -2/3,
-                               mu.diagonal = 0,
-                               sigma.diagonal = 0){
-  S <- FW$S
+                               mu_diagonal = 0,
+                               sigma_diagonal = 0){
+  S <- FW$size
   M <- matrix(0, S, S)
   ## Get off-diagonal coefficients
   NumPairs <- FW$L
-  if (is.matrix(distribution.pairs) == TRUE){
-    my.pairs <- eye.pairs.from.empirical(NumPairs = NumPairs,
-                                         Empirical.Distribution = distribution.pairs)
+  if (is.matrix(distribution_pairs) == TRUE){
+    my.pairs <- eye.pairs.from.empirical(num_pairs = NumPairs,
+                                         empirical_distribution = distribution_pairs)
   } else {
-    if (distribution.pairs == "Normal"){
-      my.pairs <- eye.pairs.from.normal(NumPairs = NumPairs,
+    if (distribution_pairs == "Normal"){
+      my.pairs <- eye.pairs.from.normal(num_pairs = NumPairs,
                                         mux = mux,
                                         muy = muy,
                                         sigmax = sigmax,
                                         sigmay = sigmay,
                                         rhoxy = rhoxy)
     }
-    if (distribution.pairs == "FourCorner"){
-      my.pairs <- eye.pairs.from.fourcorner(NumPairs = NumPairs,
+    if (distribution_pairs == "FourCorner"){
+      my.pairs <- eye.pairs.from.fourcorner(num_pairs = NumPairs,
                                           mux = mux,
                                           muy = muy,
                                           sigmax = sigmax,
@@ -37,39 +53,58 @@ eye.parameterize.M <- function(FW,
   M[FW$links] <- my.pairs[ , 1]
   M[FW$links[,2:1]] <- my.pairs[ , 2]
   ## Optional: set diagonal
-  diag(M) <- rnorm(S, mean = mu.diagonal, sd = sigma.diagonal)
+  diag(M) <- rnorm(S, mean = mu_diagonal, sd = sigma_diagonal)
   return(M)
 }
 
+#' Builds a community matrix M based on a food web model, and a parameterization for the bivariate distribution
+#'
+#' @param foodweb_model A food web model. Possible options are "Random", "Cascade", "Niche" or a file name containing an adjacency matrix
+#' @param size The number of species in the foodweb
+#' @param connectance The connectance of the food web
+#' @param distribution_pairs A bivariate distribution for the pairs (possibilities are "Normal", "FourCorner", or an empirical distribution, represented by a Nx2 matrix of pairs)
+#' @param mux Mean of the negative interaction strengths
+#' @param muy Mean of the positive interaction strengths
+#' @param sigmax Standard deviation of the negative interaction strengths
+#' @param sigmay Standard deviation of the positive interaction strengths
+#' @param rhoxy Correlation between the interaction strengths
+#' @param mu_diagonal (0 by default) mean of the diagonal elements
+#' @param sigma_diagonal (0 by default) standard deviation for the diagonal elements
+#'
+#' @return The community matrix M
+#' @examples
+#' M <- eye.buildfoodweb.and.parameterize.M(foodweb_model = "Cascade", size = 100, connectance = 0.2,
+#'      distribution_pairs = "Normal", mux = -1, muy = 1, sigmax = 1, sigmay = 1, rhoxy = -0.2,
+#'      mu_diagonal = -3, sigma_diagonal = 0)
 #' @export
-#' @import igraph
-#' @import MASS
-#' @import ggplot2
-eye.buildfoodweb.and.parameterize.M <- function(foodweb.model = "Cascade",
-                                                S = 100,
-                                                C = 0.1,
-                                                distribution.pairs = "Normal",
+eye.buildfoodweb.and.parameterize.M <- function(foodweb_model = "Cascade",
+                                                size = 100,
+                                                connectance = 0.1,
+                                                distribution_pairs = "Normal",
                                                 mux = -3,
                                                 muy = 1.5,
                                                 sigmax = 1,
                                                 sigmay = 0.75,
                                                 rhoxy = -2/3,
-                                                mu.diagonal = 0,
-                                                sigma.diagonal = 0){
+                                                mu_diagonal = 0,
+                                                sigma_diagonal = 0){
   FW <- NULL
   # if it's a file
-  if (file.exists(foodweb.model) == TRUE){
-    FW <- eye.foodweb.file(foodweb.model)
+  if (file.exists(foodweb_model) == TRUE){
+    FW <- eye.foodweb.file(foodweb_model)
+  }
+  if (foodweb_model == "Cascade"){
+    FW <- eye.foodweb.cascade(size, connectance)
   }
-  if (foodweb.model == "Cascade"){
-    FW <- eye.foodweb.cascade(S, C)
+  if (foodweb_model == "Niche"){
+    FW <- eye.foodweb.niche(size, connectance)
   }
-  if (foodweb.model == "Niche"){
-    FW <- eye.foodweb.niche(S, C)
+  if (foodweb_model == "Random"){
+    FW <- eye.foodweb.niche(size, connectance)
   }
   if (is.null(FW)){
-    stop("Invalid food web model. Please enter Cascade, Niche, or a file name for the adjacency matrix.")
+    stop("Invalid food web model. Please enter Random, Cascade, Niche, or a file name for the adjacency matrix.")
   }
-  M <- eye.parameterize.M(FW, distribution.pairs, mux, muy, sigmax, sigmay, rhoxy, mu.diagonal, sigma.diagonal)
+  M <- eye.parameterize.M(FW, distribution_pairs, mux, muy, sigmax, sigmay, rhoxy, mu_diagonal, sigma_diagonal)
   return(M)
 }