cheddar (version 0.1-639)

AggregateCommunities: Aggregate communities

Description

Functions that aggregate communities in a collection.

Usage

AggregateCommunities(collection, 
                     aggregate = names(collection), 
                     weight.by='N',
                     title = NULL)
AggregateCommunitiesBy(collection, aggregate.by, ...)

Value

A new object that is either of class Community or CommunityCollection.

Arguments

collection

an object of class CommunityCollection.

aggregate

the names of the communities to aggregate.

weight.by

the name of a column by which to compute weighted mean of numeric values.

title

the title of the new Community.

aggregate.by

the name of a community property, either first-class or computed, over which to aggregate.

...

values passed to AggregateCommunities.

Author

Lawrence Hudson

Details

AggregateCommunities combines communities given in aggregate in to a single new Community.

Nodes that appear in one or more of the communities in aggregate are combined into a single node in the returned community. The way in which numeric node properties are aggregated is governed by the weight.by parameter. If weight.by is NULL or is not the name of a node property, the arithmetic mean is computed for each numeric node property. If weight.by is the name of a node property, that property is used to compute weighted means of the other numeric node properties; the arithmetic mean of weight.by is computed. This scheme means that if a community contains both N and M, aggregation using weight.by='N' results in the arithmetic mean of N and the N-weighted mean of M for each node. Node properties that are characters or logicals are aggregated by joining unique values with a `,'. Empty character strings are ignored. Species that are not present in some communities in the collection are assumed to have a value of 0 for all numeric node properties, an empty string ('') for all character node properties and a value of NA for all logical node properties.

The returned community contains the union of trophic links for each node. Community properties are aggregated by computing the arithmetic mean of numeric values and joining unique character and logical values with a `,'.

See the `Aggregating communities' section of the `Collections' vignette for a more detailed explanation and examples of how properties are aggregated.

AggregateCommunitiesBy aggregates by a property of the communities, either first-class or computed. If there is more than one unique value of the property across the contained communities, a new CommunityCollection object is returned. If there is just one unique value, a single Community is returned.

See Also

CommunityCollection, CollectionCPS

Examples

data(pHWebs)

# An aggregate of 3 communities
AggregateCommunities(pHWebs, c('Old Lodge', 'Afon Hafren', 'Broadstone'))

# The Duddon Pike Beck and Mosedal Beck communities share the same 
# latitude and have pH values of 6.1 and 5.9 respectively.
CollectionCPS(pHWebs[c('Duddon Pike Beck', 'Mosedal Beck')])

# Aggregating by the 'lat' property therefore results in a new collection 
# of nine communities.
CollectionCPS(AggregateCommunitiesBy(pHWebs, 'lat'))

# Would produce an error
if (FALSE) AggregateCommunities(pHWebs, c('not a community', 'Afon Hafren'))