Reference

Defining Networks

The first step is to define a felt.network.Network using collections of felt.network.Node and felt.network.Way instances.

class felt.network.Node(name, x, y, **attr)

Represents a node.

Nodes have a position in 2-dimensional space given by the x and y attributes. Nodes also have a name that serves as a unique identifier, and an attr map.

An ordered sequence of nodes can be used to construct felt.network.Path, felt.network.Way, and felt.network.Link instances.

Users will typically initialize node instances directly as part of creating a felt.network.Network instance.

Parameters

  • name – a unique identifier for the node

  • x – the x position of the node

  • y – the y position of the node

  • **attr – extra key word arguments to give attributes of the node

name = None

a unique identifier for the node

x = None

node x location

y = None

node y location

attr = None

node attributes

class felt.network.Way(node_names, oneway=None)

An ordered sequence of nodes with attributes

Used to represent a way in a felt.network.Network.

Users will typically initialize way instances directly as part of creating a felt.network.Network instance.

The way may allow flow with or against the order of the nodes, or both. This is specified with the oneway argument. A positive value indicates with the node ordering. A negative value indicates against the node ordering. A zero value indicates both. The default is zero.

Parameters

  • node_names – a sequence of node names

  • oneway – Used to specify the direction of flow along the way

node_names = None

names of nodes making the path

oneway

The orientation of the way.

nodes

The sequence of nodes making the path

The links of the path

length

The length of the path, as defined by the positions of the path nodes.

class felt.network.Network(nodes, ways)

A network of ways and nodes.

A collection of ways and nodes. Ways may share nodes to form intersections.

Users will typically initialize a network instance directly, and then use it’s shortest_path() method to create Path instances.

Parameters

  • nodes – a collection of node instances

  • ways – a collection of way instances

node_names = None

the names of the nodes in the network

nodes = None

the network nodes; a dictionary with node name keys

ways = None

the ways in the network

The links in the network

graph

The graph defined by the network

shortest_path(source, sink)

Get the shortest path between two nodes in the network.

Parameters

  • source – the name of the source node

  • sink – the name of the sink node

Returns

The shortest path between the two nodes

Raises

NoPath – If there is no path between the source and sink.

path(node_names)

Create a path on a network

Parameters

node_names – the names of the nodes in the path

Raises

ValueError – if the path is not valid

Defining Paths

The second step is to define felt.network.Path instances on the network. You can define these using the felt.network.Network.path() method or the felt.network.Network.shortest_path() method.

Network.path(node_names)

Create a path on a network

Parameters

node_names – the names of the nodes in the path

Raises

ValueError – if the path is not valid

Network.shortest_path(source, sink)

Get the shortest path between two nodes in the network.

Parameters

  • source – the name of the source node

  • sink – the name of the sink node

Returns

The shortest path between the two nodes

Raises

NoPath – If there is no path between the source and sink.

Defining Movements

The third step is to define felt.movement.Movement instances.

class felt.movement.Movement(movement)

Specifies a path sub-sequence.

A movement specifies a sub-path sequence on a network. Movements are specified using a list. Within the list an Ellipsis (...) will match zero or more nodes. Any other value must match a node in the path exactly. Each path on the network is incident on the movement zero or more times. For example if the movement is [..., 2, 3, ...], the paths [1, 2, 3] and [1, 2, 3, 4] are each incident once on the movement; the path [2, 3, 2, 3] is incident twice; and the path [4, 5, 6] is incident zero times. These examples and others are listed in the table below.

movement

path

incidence count

[..., 2, 3, ...]

[1, 2, 3]

1

[..., 2, 3, ...]

[1, 2, 3, 4]

1

[..., 2, 3, ...]

[2, 3, 2, 3]

2

[..., 2, 3, ...]

[4, 5, 6]

0

[2, 3]

[1, 2, 3]

0

[2, 3]

[2, 3]

1

[2, 3]

[2]

0

[..., 1]

[1]

1

[..., 1]

[2, 1]

1

[..., 1]

[2, 1, 0]

0

[1, ..., 5]

[1, 5]

1

[1, ..., 5]

[1, 2, 5]

1

[1, ..., 5]

[1, 2, 3, 5]

1

[1, ..., 5]

[2, 1, 5]

0

A concrete example of movements are turns at a highway intersection. For example, the left turn from a particular leg of the intersection can be modeled as a sequence of three nodes which form a movement.

Movements are used to represent the observable portion of paths. One cannot observe a vehicle traveling along the entire length if its path, but shorter movements are observable, so the flow on the movement can be measured. These movement flow measurements can then be used to estimate path flows.

Typically users should intialize movements directly in order to model the movements that they have measured flows for.

Movement instances are used in the felt.estimate.estimate() function to help construct a path-movement incidence matrix.

Parameters

movement – the movement specification list. May include ellipsis.

Examples

Initialize a Movement instance:

>>> from felt import Movement
>>> movement = Movement([..., 2, 3, ...])

Estimating Path Flows

The last step is to estimate path flows using the felt.estimate.estimate() function.

felt.estimate.estimate(paths, movements, movement_flows, niter=100)

Estimate path flows.

Parameters

  • paths – a sequence of Path instances

  • movements – a sequence of Movement instances

  • movement_flows – a sequence of numbers, aligning with movements

  • niter – the number of iterations (optional)

Returns

path flows