Filters & Filter Management

Filters work on nodes and/or edges. All filters inherits from the base class GraphFilter. GraphFilter has overloaded ()-operators for nodes and edges. The derived filters overloads at least one of these to filter on specific properties of each node and edge.

Filters are required to set the nodes and edges properties to indicate whether they operate (are valid) on nodes, edges or both.

Additionally filters also have properties to indicate whether they are enabled (should be executed by the associated action) and inverted. If inverted is set the filter should return the opposite result to what it normally does.

Actions vs Filters

Actions are what determines the effect of applying a filter to nodes and edges. All actions inherits from the base class GraphAction. Any action can take effect on nodes, edges, or both. An action has an internal filter that is used to determine whether the action should execute or not. Every action has overloaded ()-operators for nodes and edges that first calls the underlying filter and then performs its action accordingly.

A "true" return value of operator() mean that the node GraphAction using the filter should execute and false, that it should not execute. For HideAction for example, a "true" return value means that the node should be hidden and false means it should be shown.

Filter Lists

A class called GraphFilterList holds actions (which in turn holds a filter). A GraphFilterList has overloaded ()-operators for nodes and edges that applies each action in the list on the given node/edge.

We make a distinction on pre- and post-filters. Pre-filters are the filters used to determine whether a node/edge should be in the grapher, this happens in the add_node() and add_edge() functions in Grapher.

Post-filters are used to apply properties to nodes/edges after they have been added to the grapher, this happens when a filter is activated. Pre- and post-filters are both represented by a GraphFilterList.

Import / Export

ilters can be imported/exported to an XML format. This is done by utilizing the FilterParser class. To generate a FilterParser object you need a Linkler, a GraphProperties object and (optionally a LinklerDiff). While reading, using the read_filters method, you will receive a GraphFilterList in return value.

Filters while generating (Grapher)

The Grapher is created by a builder. The builder uses the add_node() and add_edge() methods of Grapher and these use a GraphFilterList to test whether the given node/edge should be added or not.

Filters while iterating

To see an example using Filters while iterating review the code example in the (Grapher documentation)[grapher.md].

In UI: Conditional Formatting vs Filters

In the UI we have the option of specifying filters vs conditional formatting. More on this is available in the GUI documentation. One important note about their difference is that "filters" only generates HideActions and the default behaviour is expected, that is if the filter returns true then the node should be kept in the graph (not hidden). In the case of "conditional formatting" however, the SetPropertyAction for opacity and color should both be executed when the filter matches, but for HideAction, it would be expected that it is if the filter does match that nodes should be hidden, ie. the opposite as for "conditional formatting". Therefore MainController sets inverted to true when this is the case.