Skip to content

Link rows

network

Create network links using explicit lists of target IDs, weights and other link attributes.

For each row this step iterates over the IDs in the link_targets column, and if an ID exists also in the source column, the corresponding rows will be connected, optionally with specified attributes.

The link_targets column may contain one target ID per row, or lists of target IDs. In either case, any additional attribute columns should be of the same type. I.e. if each row specifies multiple links via lists in link_targets, then attribute columns should also contain lists of the same length, such that each link can be assigned its corresponding attribute. If the lengths of lists containing target IDs and attributes do not match, the corresponding row will be ignored. If attributes are single-valued (not containing lists), all links from specified in that row will have the same attribute value.

Note that the types of values in source and link_targets identifying the nodes/rows to be linked should also match. Ideally, either both columns have numeric values or both have string-like (categorical) values. However, as long as one can be converted safely to the other, linking will work as expected (e.g. source IDs could be specified as numbers [0, 1, 2] and target IDs as strings ["3", "2", "1"] without the step failing).

The resulting links dataset will have at least the columns source, target and weight. If a third argument was specified (the first link attribute), this will be used for the weight of the links. If no attribute was specified (only source and targets), the weights will be constant (1.0). Any attribute given after the weight will be carried through using its original name.

Example

In the following example we connect rows/nodes identified in the column link_source, to rows/nodes specified in the column link_targets, which contains lists of such link targets. Additionally, we use the columns link_weights and links_are_reciprocal (which contain lists of the same lengths as targets), to add attributes to the created links (the weight of the link and whether it is unidirectional or bidirectional).

link_rows(ds.link_source, ds.link_targets, ds.link_weights, ds.links_are_reciprocal) -> (links)

Usage

The following are the step's expected inputs and outputs and their specific types.

link_rows(
    source: number|category,
    link_targets: number|category|list[number]|list[category],
    *link_attributes: number|category|list, 
    {
        "param": value
    }
) -> (links: dataset)

where the object {"param": value} is optional in most cases and if present may contain any of the parameters described in the corresponding section below.

Inputs


source: column:number|category

A column of (numerical or categorical) IDs identifying the nodes/rows acting as the source of a link.


link_targets: column:number|category|list[number]|list[category]

A column containing (potentially lists) of IDs corresponding to link targets.


*link_attributes: column:number|category|list

One ore more optional attributes for the links. Must be lists of the same lengths as link_targets if the latter contains lists.

Outputs


links: dataset

A new dataset containing links (source, target, weight and optional attribute columns) between connected nodes.

Parameters


weight_factor: number = 1.0

Multiply link weights by this number.