Object-oriented bipartite

Creating S3-objects in bipartite

Starting with version 3.00, the bipartite-package enables object-oriented programming (OOP) using the S3 system. To understand what that means we will demonstrate the new functionalities with the aid of the dataset Safariland.

library(bipartite)
data(Safariland)
options(max.print = 10)
class(Safariland)
## [1] "bipartite_web" "matrix"        "array"

As the output above indicates Safariland is now of type bipartite_web in addition to the types matrix and array.

str(Safariland)
##  'bipartite_web' int [1:9, 1:27] 673 0 0 0 0 0 0 0 0 0 ...
##  - attr(*, "dimnames")=List of 2
##   ..$ : chr [1:9] "Aristotelia chilensis" "Alstroemeria aurea" "Schinus patagonicus" "Berberis darwinii" ...
##   ..$ : chr [1:27] "Policana albopilosa" "Bombus dahlbomii" "Ruizantheda mutabilis" "Trichophthalma amoena" ...
##  - attr(*, "lower_attributes")='data.frame': 9 obs. of  0 variables
##  - attr(*, "higher_attributes")='data.frame':    27 obs. of  0 variables
##  - attr(*, "meta_attributes")= list()

So the dataset in its core is still an integer matrix of size \(9\times 27\) with named rows and columns. From the help file, we know that the columns represent pollinators and the rows represent plant species.

Sometimes, that’s all the information available about a network. More often, however, additional information is available about individual nodes or the network as a whole.

For example, the Safariland data has additional information about the plants and pollinators available. We stored this data in two separate CSV files and load those into the workspace as data.frame objects.

plant_attributes <- read.csv("plant_attributes.csv", row.names = 1)
plant_attributes <- plant_attributes[rownames(Safariland), ]
plant_attributes
##                                 Family       Life.form Origin
## Aristotelia chilensis    Eleocarpaceae Understory tree Native
## Alstroemeria aurea    Alstroemeriaceae            Herb Native
## Schinus patagonicus      Anacardiaceae Understory tree Native
##  [ reached 'max' / getOption("max.print") -- omitted 6 rows ]
pollinator_attributes <- read.csv("pollinator_attributes.csv", row.names = 1)
pollinator_attributes <- pollinator_attributes[colnames(Safariland), ]
pollinator_attributes
##                              Family       Order
## Policana albopilosa      Colletidae Hymenoptera
## Bombus dahlbomii             Apidae Hymenoptera
## Ruizantheda mutabilis    Halictidae Hymenoptera
## Trichophthalma amoena Nemestrinidae     Diptera
## Syrphus octomaculatus     Syrphidae     Diptera
##  [ reached 'max' / getOption("max.print") -- omitted 22 rows ]

Now we can create a new bipartite_web object combining the interaction matrix with the details on the plants and pollinators as well as some meta information.

Safariland.web <- bipartite_web(Safariland,
                                lower_attributes = plant_attributes,
                                higher_attributes = pollinator_attributes,
                                meta_attributes = list("type" = "pollination"))
print(Safariland.web)
## <bipartite_web object>
## Dimensions: 9 x 27 
## -------------------------------------------------- 
## Higher species attributes:
##                              Family       Order
## Policana albopilosa      Colletidae Hymenoptera
## Bombus dahlbomii             Apidae Hymenoptera
## Ruizantheda mutabilis    Halictidae Hymenoptera
## Trichophthalma amoena Nemestrinidae     Diptera
## Syrphus octomaculatus     Syrphidae     Diptera
##  [ reached 'max' / getOption("max.print") -- omitted 22 rows ]
## Lower species attributes:
##                                 Family       Life.form Origin
## Aristotelia chilensis    Eleocarpaceae Understory tree Native
## Alstroemeria aurea    Alstroemeriaceae            Herb Native
## Schinus patagonicus      Anacardiaceae Understory tree Native
##  [ reached 'max' / getOption("max.print") -- omitted 6 rows ]
## Meta attributes:
## $type
## [1] "pollination"
## 
## -------------------------------------------------- 
## Matrix:
##                          Policana albopilosa Bombus dahlbomii
## Aristotelia chilensis                    673                0
##                          Ruizantheda mutabilis Trichophthalma amoena
## Aristotelia chilensis                      110                     0
##                          Syrphus octomaculatus Manuelia gayi
## Aristotelia chilensis                        0             0
##                          Allograpta.Toxomerus Trichophthalma jaffueli Phthiria
## Aristotelia chilensis                       0                       0        0
##                          Platycheirus1
## Aristotelia chilensis                4
##  [ reached 'max' / getOption("max.print") -- omitted 8 rows and 17 columns ]

Safariland.web could now be stored and shared as a single R object containing all relevant information on the dataset.

save(Safariland.web, file = "Safariland.web.RData")

3D (multi-layer) network objects

Version 3.0 also introduces simple multilayer bipartite networks. The S3-class for those is called bipartite_webarray and in its core represents a 3D-array, in which the third dimension represents the various networks.

To demonstrate we will combine Safariland with the vazarr data set, as they stem from the same field work.

dim(Safariland)
## [1]  9 27
dim(vazarr)
## [1] 10 29

Looking at the dimensions of the two data sets, we see that in Safariland 9 plant species and 27 pollinator species were recorded, and in vazarr 10 plant species and 29 pollinator species were recorded.

To combine the two we call bipartite_webarray passing both as a an argument.

warray <- bipartite_webarray(Safariland, vazarr)
dim(warray)
## [1] 10 41  2

The new warray object now has three dimensions. The first two still represent the plants and pollinators and the third represents the two networks. As we can see the first two dimensions have been blown up to include the union of all plant and pollinator species.

print(warray)
## <bipartite_webarray object>
## Dimensions: 10 x 41 x 2 
## Web names: Safariland vazarr 
## -------------------------------------------------- 
## Global higher attributes:
## data frame with 0 columns and 41 rows
## Global lower attributes:
## data frame with 0 columns and 10 rows
## Global meta attributes:
## list()
## -------------------------------------------------- 
## Safariland 
## Higher attributes:
## data frame with 0 columns and 41 rows
## Lower attributes:
## data frame with 0 columns and 10 rows
## Meta attributes:
## list()
## Matrix:
##                          Acroceridae Allograpta.Toxomerus Anthaxia
## Alstroemeria aurea                 0                    1        0
##                          Bombus dahlbomii Bombus ruderatus Braconidae2
## Alstroemeria aurea                    154                0           0
##                          Braconidae3 Camponotus Chalepogenus caeruleus
## Alstroemeria aurea                 0          0                      0
##                          Chilicola1
## Alstroemeria aurea                0
##  [ reached 'max' / getOption("max.print") -- omitted 9 rows and 31 columns ]
## -------------------------------------------------- 
## vazarr 
## Higher attributes:
## data frame with 0 columns and 41 rows
## Lower attributes:
## data frame with 0 columns and 10 rows
## Meta attributes:
## list()
## Matrix:
##                          Acroceridae Allograpta.Toxomerus Anthaxia
## Alstroemeria aurea                 1                    4        2
##                          Bombus dahlbomii Bombus ruderatus Braconidae2
## Alstroemeria aurea                      4               30           0
##                          Braconidae3 Camponotus Chalepogenus caeruleus
## Alstroemeria aurea                 0          0                      0
##                          Chilicola1
## Alstroemeria aurea                1
##  [ reached 'max' / getOption("max.print") -- omitted 9 rows and 31 columns ]

From the print output we can tell that the attributes are now separated into global attributes describing the whole bipartite_webarray and local attributes for each containing web.

To further illustrate the difference we will load the plant and pollinator attributes CSV files again, as they contain information on all species observed in the field study. They are going to be the global higher and lower attributes for our new bipartite_webarray.

pollinator_attributes <- read.csv("pollinator_attributes.csv", row.names = 1)
plant_attributes <- read.csv("plant_attributes.csv", row.names = 1)

In addition we create two data.frames containing a single column with an id for the higher species of vazarr and the lower species of Safariland respectively. Those will be our local attributes.

vazarr_higher_attributes <- data.frame(id = 1:ncol(vazarr),
                                       row.names = colnames(vazarr))
safariland_lower_attributes <- data.frame(id = 1:nrow(Safariland),
                                          row.names = rownames(Safariland))
warray <- bipartite_webarray(Safariland, vazarr,
                             global_higher_attributes = pollinator_attributes,
                             global_lower_attributes = plant_attributes,
                             global_meta_attributes = list(type = "pollinaton"),
                             local_higher_attributes = list("vazarr" = vazarr_higher_attributes),
                             local_lower_attributes = list("Safariland" = safariland_lower_attributes))
warray
## <bipartite_webarray object>
## Dimensions: 10 x 41 x 2 
## Web names: Safariland vazarr 
## -------------------------------------------------- 
## Global higher attributes:
##                           Family       Order
## Acroceridae          Acroceridae     Diptera
## Allograpta.Toxomerus   Syrphidae     Diptera
## Anthaxia             Buprestidae  Coleoptera
## Bombus dahlbomii          Apidae Hymenoptera
## Bombus ruderatus          Apidae Hymenoptera
##  [ reached 'max' / getOption("max.print") -- omitted 36 rows ]
## Global lower attributes:
##                                 Family       Life.form Origin
## Alstroemeria aurea    Alstroemeriaceae            Herb Native
## Aristotelia chilensis    Eleocarpaceae Understory tree Native
## Berberis darwinii        Berberidaceae           Shrub Native
##  [ reached 'max' / getOption("max.print") -- omitted 7 rows ]
## Global meta attributes:
## $type
## [1] "pollinaton"
## 
## -------------------------------------------------- 
## Safariland 
## Higher attributes:
## data frame with 0 columns and 41 rows
## Lower attributes:
##                          id
## Alstroemeria aurea        2
## Aristotelia chilensis     1
## Berberis darwinii         4
## Calceolaria crenatiflora  9
## Cynanchum diemii          6
## Mutisia decurrens         8
## Ribes magellanicum        7
## Rosa eglanteria           5
## Schinus patagonicus       3
## Vicia nigricans          NA
## Meta attributes:
## list()
## Matrix:
##                          Acroceridae Allograpta.Toxomerus Anthaxia
## Alstroemeria aurea                 0                    1        0
##                          Bombus dahlbomii Bombus ruderatus Braconidae2
## Alstroemeria aurea                    154                0           0
##                          Braconidae3 Camponotus Chalepogenus caeruleus
## Alstroemeria aurea                 0          0                      0
##                          Chilicola1
## Alstroemeria aurea                0
##  [ reached 'max' / getOption("max.print") -- omitted 9 rows and 31 columns ]
## -------------------------------------------------- 
## vazarr 
## Higher attributes:
##                        id
## Acroceridae            27
## Allograpta.Toxomerus    7
## Anthaxia                9
## Bombus dahlbomii        2
## Bombus ruderatus        4
## Braconidae2            NA
## Braconidae3            NA
## Camponotus             14
## Chalepogenus caeruleus 16
## Chilicola1             28
##  [ reached 'max' / getOption("max.print") -- omitted 31 rows ]
## Lower attributes:
## data frame with 0 columns and 10 rows
## Meta attributes:
## list()
## Matrix:
##                          Acroceridae Allograpta.Toxomerus Anthaxia
## Alstroemeria aurea                 1                    4        2
##                          Bombus dahlbomii Bombus ruderatus Braconidae2
## Alstroemeria aurea                      4               30           0
##                          Braconidae3 Camponotus Chalepogenus caeruleus
## Alstroemeria aurea                 0          0                      0
##                          Chilicola1
## Alstroemeria aurea                1
##  [ reached 'max' / getOption("max.print") -- omitted 9 rows and 31 columns ]

Accessing the attributes

The attributes can be acccessed using the three access functions higher_attributes, lower_attributes, and meta_attributes. The first two return the underlying data.frame the latter the underlying list.

higher_attributes(Safariland.web)
##                              Family       Order
## Policana albopilosa      Colletidae Hymenoptera
## Bombus dahlbomii             Apidae Hymenoptera
## Ruizantheda mutabilis    Halictidae Hymenoptera
## Trichophthalma amoena Nemestrinidae     Diptera
## Syrphus octomaculatus     Syrphidae     Diptera
##  [ reached 'max' / getOption("max.print") -- omitted 22 rows ]
lower_attributes(Safariland.web)
##                                 Family       Life.form Origin
## Aristotelia chilensis    Eleocarpaceae Understory tree Native
## Alstroemeria aurea    Alstroemeriaceae            Herb Native
## Schinus patagonicus      Anacardiaceae Understory tree Native
##  [ reached 'max' / getOption("max.print") -- omitted 6 rows ]
meta_attributes(Safariland.web)
## $type
## [1] "pollination"

On the returned data.frame further selection of rows and columns is enabled using the $ or [ operators.

higher_attributes(Safariland.web)$Order
##  [1] "Hymenoptera" "Hymenoptera" "Hymenoptera" "Diptera"     "Diptera"    
##  [6] "Hymenoptera" "Diptera"     "Diptera"     "Diptera"     "Diptera"    
##  [ reached 'max' / getOption("max.print") -- omitted 17 entries ]
higher_attributes(Safariland.web)["Ruizantheda proxima", ]
##                         Family       Order
## Ruizantheda proxima Halictidae Hymenoptera

Local and global attributes

For bipartite_webarray there is a differentiation between the global and local attributes. The global attributes can be accessed by simply calling *_attributes:

higher_attributes(warray)
##                           Family       Order
## Acroceridae          Acroceridae     Diptera
## Allograpta.Toxomerus   Syrphidae     Diptera
## Anthaxia             Buprestidae  Coleoptera
## Bombus dahlbomii          Apidae Hymenoptera
## Bombus ruderatus          Apidae Hymenoptera
##  [ reached 'max' / getOption("max.print") -- omitted 36 rows ]

Acccessing the local attributes however requires the use of the web_id argument:

higher_attributes(warray, web_id = "vazarr")
##                        id
## Acroceridae            27
## Allograpta.Toxomerus    7
## Anthaxia                9
## Bombus dahlbomii        2
## Bombus ruderatus        4
## Braconidae2            NA
## Braconidae3            NA
## Camponotus             14
## Chalepogenus caeruleus 16
## Chilicola1             28
##  [ reached 'max' / getOption("max.print") -- omitted 31 rows ]

Replacing / changing the attributes

Replacing or changing of the attributes is achieved by using replacement functions. Which in practice means calling *_attributes, selecting the desired column/row/cell and replacing it with <- value.

meta_attributes(Safariland.web)$start_year <- 1999
meta_attributes(Safariland.web)$end_year <- 2000
meta_attributes(Safariland.web)
## $type
## [1] "pollination"
## 
## $start_year
## [1] 1999
## 
## $end_year
## [1] 2000
higher_attributes(Safariland.web)$id <- 1:ncol(Safariland.web)
higher_attributes(Safariland.web)
##                           Family       Order id
## Policana albopilosa   Colletidae Hymenoptera  1
## Bombus dahlbomii          Apidae Hymenoptera  2
## Ruizantheda mutabilis Halictidae Hymenoptera  3
##  [ reached 'max' / getOption("max.print") -- omitted 24 rows ]

Subsetting

bipartite_web objects can be subset in the same way as matrix objects. Doing this automatically subsets the higher and lower attributes data.frames accordingly.

Safariland.web[1:5, 1:3]
## <bipartite_web object>
## Dimensions: 5 x 3 
## -------------------------------------------------- 
## Higher species attributes:
##                           Family       Order id
## Policana albopilosa   Colletidae Hymenoptera  1
## Bombus dahlbomii          Apidae Hymenoptera  2
## Ruizantheda mutabilis Halictidae Hymenoptera  3
## Lower species attributes:
##                                 Family       Life.form Origin
## Aristotelia chilensis    Eleocarpaceae Understory tree Native
## Alstroemeria aurea    Alstroemeriaceae            Herb Native
## Schinus patagonicus      Anacardiaceae Understory tree Native
##  [ reached 'max' / getOption("max.print") -- omitted 2 rows ]
## Meta attributes:
## $type
## [1] "pollination"
## 
## $start_year
## [1] 1999
## 
## $end_year
## [1] 2000
## 
## -------------------------------------------------- 
## Matrix:
##                       Policana albopilosa Bombus dahlbomii
## Aristotelia chilensis                 673                0
## Alstroemeria aurea                      0              154
## Schinus patagonicus                     0                0
##                       Ruizantheda mutabilis
## Aristotelia chilensis                   110
## Alstroemeria aurea                        0
## Schinus patagonicus                       0
##  [ reached 'max' / getOption("max.print") -- omitted 2 rows ]

Keep in mind that the standard setting is drop = TRUE for subsetting. So if the result isn’t a matrix anymore it is also not a bipartite_web by default.

Safariland.web[1:5, 1]
## Aristotelia chilensis    Alstroemeria aurea   Schinus patagonicus 
##                   673                     0                     0 
##     Berberis darwinii       Rosa eglanteria 
##                     0                     0
Safariland.web[5, 3]
## [1] 6

To avoid this behaviour manually set drop = FALSE:

Safariland.web[1:5, 1, drop = FALSE]
## <bipartite_web object>
## Dimensions: 5 x 1 
## -------------------------------------------------- 
## Higher species attributes:
##                         Family       Order id
## Policana albopilosa Colletidae Hymenoptera  1
## Lower species attributes:
##                                 Family       Life.form Origin
## Aristotelia chilensis    Eleocarpaceae Understory tree Native
## Alstroemeria aurea    Alstroemeriaceae            Herb Native
## Schinus patagonicus      Anacardiaceae Understory tree Native
##  [ reached 'max' / getOption("max.print") -- omitted 2 rows ]
## Meta attributes:
## $type
## [1] "pollination"
## 
## $start_year
## [1] 1999
## 
## $end_year
## [1] 2000
## 
## -------------------------------------------------- 
## Matrix:
##                       Policana albopilosa
## Aristotelia chilensis                 673
## Alstroemeria aurea                      0
## Schinus patagonicus                     0
## Berberis darwinii                       0
## Rosa eglanteria                         0
Safariland.web[5, 3, drop = FALSE]
## <bipartite_web object>
## Dimensions: 1 x 1 
## -------------------------------------------------- 
## Higher species attributes:
##                           Family       Order id
## Ruizantheda mutabilis Halictidae Hymenoptera  3
## Lower species attributes:
##                   Family Life.form Origin
## Rosa eglanteria Rosaceae     Shrub Exotic
## Meta attributes:
## $type
## [1] "pollination"
## 
## $start_year
## [1] 1999
## 
## $end_year
## [1] 2000
## 
## -------------------------------------------------- 
## Matrix:
##                 Ruizantheda mutabilis
## Rosa eglanteria                     6

Subsetting can also be done using row and column names:

Safariland.web["Rosa eglanteria", "Ruizantheda mutabilis", drop = FALSE]
## <bipartite_web object>
## Dimensions: 1 x 1 
## -------------------------------------------------- 
## Higher species attributes:
##                           Family       Order id
## Ruizantheda mutabilis Halictidae Hymenoptera  3
## Lower species attributes:
##                   Family Life.form Origin
## Rosa eglanteria Rosaceae     Shrub Exotic
## Meta attributes:
## $type
## [1] "pollination"
## 
## $start_year
## [1] 1999
## 
## $end_year
## [1] 2000
## 
## -------------------------------------------------- 
## Matrix:
##                 Ruizantheda mutabilis
## Rosa eglanteria                     6

When subsetting bipartite_webarray objects single webs can be extracted as bipartite_web objects. Doing this combines the global and local attributes.

warray[, , "vazarr"]
## <bipartite_web object>
## Dimensions: 10 x 41 
## -------------------------------------------------- 
## Higher species attributes:
##                           Family      Order id
## Acroceridae          Acroceridae    Diptera 27
## Allograpta.Toxomerus   Syrphidae    Diptera  7
## Anthaxia             Buprestidae Coleoptera  9
##  [ reached 'max' / getOption("max.print") -- omitted 38 rows ]
## Lower species attributes:
##                                 Family       Life.form Origin
## Alstroemeria aurea    Alstroemeriaceae            Herb Native
## Aristotelia chilensis    Eleocarpaceae Understory tree Native
## Berberis darwinii        Berberidaceae           Shrub Native
##  [ reached 'max' / getOption("max.print") -- omitted 7 rows ]
## Meta attributes:
## $type
## [1] "pollinaton"
## 
## $vazarr
## list()
## 
## -------------------------------------------------- 
## Matrix:
##                          Acroceridae Allograpta.Toxomerus Anthaxia
## Alstroemeria aurea                 1                    4        2
##                          Bombus dahlbomii Bombus ruderatus Braconidae2
## Alstroemeria aurea                      4               30           0
##                          Braconidae3 Camponotus Chalepogenus caeruleus
## Alstroemeria aurea                 0          0                      0
##                          Chilicola1
## Alstroemeria aurea                1
##  [ reached 'max' / getOption("max.print") -- omitted 9 rows and 31 columns ]