Skip to content

Network Filtering and Querying

Jump to bottom
Joshua Melville edited this page Dec 5, 2018 · 10 revisions

Querying and filtering

Filtering and querying a network are core requirements in Network Canvas and Server. Network Canvas uses filtering to determine which nodes should be shown in node panels, and uses querying for skip logic. Server uses querying during the export process to determine which networks to include in an export, and filtering to determine which data within those networks to include (or exclude).

Querying and filtering are related, but separate operations.

  • Filtering a network applies one or more logical constraints to network entities (alters, and edges) and returns the subset of the network that satisfies these constraints. Important to note is that filtering retains the validity of the network model: the returned network will not contain orphaned or partially disconnected edges, since these are not phenomenologically valid.

  • Querying similarly applies one or more logical constraints to the network, but adds an additional "top level" constraint. Unlike the filter operation, a query returns true or false depending on if this top level constraint is satisfied. For example, if we wish to skip a stage if no edges of a given type exist in our network, we would construct a rule (see below) to target that edge type, and evaluate the outcome in terms of Boolean logic.

Rules

Filter and querying operations are comprised of one or more logical constraints, called rules. These target each of the basic entity types in our network model: ego, alters, and edges.

  • An egoRule operates only on the node representing the participant, and is only available during querying operations.
  • An alterRule operates on alters, and requires a 'type' to be specified. It will remove nodes that do not satisfy the criteria.
  • An edgeRule operates on edges, and requires a 'type' to be specified. It will remove nodes not connected to an edge that satisfies the rule criteria.

Eight operators are available for use with these rules:

  • GREATER_THAN
  • LESS_THAN
  • GREATER_THAN_OR_EQUAL
  • LESS_THAN_OR_EQUAL
  • EXACTLY
  • NOT
  • EXISTS
  • NOT_EXISTS

Note that some of these operators are for testing an attribute of the entity, whereas others apply to the entity itself. For example, GREATER_THAN, LESS_THAN, LESS_THAN_OR_EQUAL, EXACTLY, and NOT can be used to test the value of a node, edge, or ego attribute. In contrast, EXISTS, and NOT_EXISTS can be used to test for a node or edge type, regardless of other attributes.

Using the entity type in combination within an operator allows the construction of simple logical tests such as: "alters of type 'Person' with attribute 'age' greater than or equal to 18".

Joining rules

Rules are combined using one of two joining methods: AND and OR.

These methods behave much as you might expect. In the context of a filter operation:

  • OR signifies that the result of each rule should be combined together in the returned network. If a node or edge matches any individual rule criteria, it will be returned in the overall network.
  • AND signifies that nodes and edges in the returned network should satisfy all rule constraints.

Querying and "truthiness"

As mentioned, querying returns a boolean value representing if a filtered network satisfies a "top level constraint".

The value of the top level constraint is determined by the "truthiness" of the individual rules themselves. If rules are joined by AND statements, and all individual rules evaluate to true, so will the top level constraint. Conversely, if any individual rules evaluate to false, so too will the top level constraint.

If rules are joined by OR statements, any individual rule evaluating truthfully will cause the top level constraint to also evaluate as true.

When constructing a query, each rule has an additional operator that determines how its truthiness is evaluated. For illustration, refer back to the example rule mentioned above:

alters of type 'Person' with attribute 'age' greater than or equal to 18

When used within a query, we must describe how to interpret the result of this filter. To do this, we describe the evaluation of the result using dedicated query operators:

  • COUNT
  • COUNT_NOT
  • COUNT_GREATER_THAN
  • COUNT_GREATER_THAN_OR_EQUAL
  • COUNT_LESS_THAN
  • COUNT_LESS_THAN_OR_EQUAL
  • COUNT_EXACTLY

Our combined query rule then becomes:

Count of alters of type 'Person' with attribute 'age' greater than or equal to 18 is greater than 0

This rule will return true if any alters in the network match the criteria.

Advanced functionality

If more complex logic is required, such as injecting an ego attribute into a subsequent alter or edge rule, or performing a "network traversal", a custom query can be written in vanilla JavaScript.

Clone this wiki locally