updateCyGroups: Update Cytoscape Groups

In frankkramer-lab/RCX: R package implementing the Cytoscape Exchange (CX) format

Update Cytoscape Groups

Description

This functions add Cytoscape groups in the form of a CyGroups object to an RCX or an other CyGroups object.

Usage

updateCyGroups(x, cyGroups, stopOnDuplicates = FALSE, keepOldIds = TRUE, ...)

## S3 method for class 'CyGroupsAspect'
updateCyGroups(x, cyGroups, stopOnDuplicates = FALSE, keepOldIds = TRUE, ...)

## S3 method for class 'RCX'
updateCyGroups(
  x,
  cyGroups,
  stopOnDuplicates = FALSE,
  keepOldIds = TRUE,
  checkReferences = TRUE,
  ...
)

Arguments

x	RCX or CyGroups object; (to which the new Cytoscape groups will be added)
cyGroups	CyGroups object; (the new aspect, that will be added)
stopOnDuplicates	logical; whether to stop, if duplicates in id column are found, or re-assign ids instead.
keepOldIds	logical; if ids are re-assigned, the original ids are kept in the column oldId
...	additional parameters
checkReferences	logical; whether to check if references to other aspects are present in the RCX object

Details

Cytoscape groups allow to group a set of nodes and corresponding internal and external edges together, and represent a group as a single node in the visualization. CyGroups objects can be added to an RCX or an other CyGroups object. The nodes, internalEdges and externalEdges parameters reference the node or edge IDs that belong to a group. When adding an CyGroups object to an RCX object, those IDs must be present in the Nodes or Edges aspect respectively, otherwise an error is raised.

When two groups should be added to each other some conflicts may rise, since the aspects might use the same IDs. If the aspects do not share any IDs, the two aspects are simply combined. Otherwise, the IDs of the new groups are re-assinged continuing with the next available ID (i.e. maxId(cyGroupsAspect) + 1 and maxId(rcx$cyGroups) + 1, respectively).

To keep track of the changes, it is possible to keep the old IDs of the newly added nodes in the automatically added column oldId. This can be omitted by setting keepOldIds to FALSE. Otherwise, if a re-assignment of the IDs is not desired, this can be prevented by setting stopOnDuplicates to TRUE. This forces the function to stop and raise an error, if duplicated IDs are present.

Value

CyGroups or RCX object with added Cytoscape groups

See Also

CyGroups;

Examples

## For CyGroupsAspects: 
## prepare some aspects:
cyGroups1 = createCyGroups(
  name = c("Group One", "Group Two"),
  nodes = list(c(1,2,3), 0),
  internalEdges = list(c(0,1),NA),
  externalEdges = list(NA,c(2,3)),
  collapsed = c(TRUE,NA)                     
)

cyGroups2 = createCyGroups(
  name = "Group Three",
  nodes = list(c(4,5)),
  externalEdges = list(c(4,5))                     
)

## group ids will be kept
cyGroups3 = updateCyGroups(cyGroups1, cyGroups2)

## old group ids will be omitted
cyGroups3 = updateCyGroups(cyGroups1, cyGroups2,
                           keepOldIds=FALSE)

## Raise an error if duplicate keys are present
try(updateCyGroups(cyGroups1, cyGroups2,
                   stopOnDuplicates=TRUE))
## =>ERROR: 
## Elements of "id" (in updateCyGroups) must not contain duplicates!

## For RCX
## prepare RCX object:
nodes = createNodes(name = c("a","b","c","d","e","f"))
edges = createEdges(source=c(1,2,0,0,0,2), 
                    target=c(2,3,1,2,5,4))
rcx = createRCX(nodes, edges)

## add the group
rcx = updateCyGroups(rcx, cyGroups1)

## add an additional group
rcx = updateCyGroups(rcx, cyGroups2)

## create a group with a not existing node...
cyGroups3 = createCyGroups(
  name = "Group Three",
  nodes = list(9)                    
)

## ...and try to add them
try(updateCyGroups(rcx, cyGroups3))
## =>ERROR: 
## Provided IDs of "additionalGroups$nodes" (in updateCyGroups) 
## don't exist in "rcx$nodes$id"

## create a group with a not existing edge...
cyGroups4 = createCyGroups(
  name = "Group Four",
  nodes = list(c(1,2)),
  internalEdges = list(c(9))
)

## ...and try to add them
try(updateCyGroups(rcx, cyGroups4))
## =>ERROR: 
## Provided IDs of "additionalGroups$internalEdges" (in updateCyGroups) 
## don't exist in "rcx$edges$id"

frankkramer-lab/RCX documentation built on Feb. 4, 2023, 5:12 p.m.