pystruct.models.EdgeFeatureGraphCRF

class pystruct.models.EdgeFeatureGraphCRF(n_states=2, n_features=None, n_edge_features=1, inference_method='lp', class_weight=None, symmetric_edge_features=None, antisymmetric_edge_features=None)

Pairwise CRF with features/strength associated to each edge.

Pairwise potentials are asymmetric and shared over all edges. They are weighted by an edge-specific features, though. This allows for contrast sensitive potentials or directional potentials (using a {-1, +1} encoding of the direction for example).

More complicated interactions are also possible, of course.

Node features and edge features are given as a tuple of shape (n_nodes, n_features) and (n_edges, n_edge_features) respectively.

An instance x is represented as a tuple (node_features, edges, edge_features) where edges is an array of shape (n_edges, 2), representing the graph.

Labels y are given as array of shape (n_features)

Parameters :

n_states : int, default=2

Number of states for all variables.

n_features : int, default=None

Number of features per node. None means n_states.

n_edge_features : int, default=1

Number of features per edge.

inference_method : string, default=”lp”

Function to call do do inference and loss-augmented inference. Possible values are:

  • ‘qpbo’ for QPBO + alpha expansion.
  • ‘dai’ for LibDAI bindings (which has another parameter).
  • ‘lp’ for Linear Programming relaxation using GLPK.
  • ‘ad3’ for AD3 dual decomposition.

class_weight : None, or array-like

Class weights. If an array-like is passed, it must have length n_classes. None means equal class weights.

symmetric_edge_features : None or list

Indices of edge features that are forced to be symmetric. Often the direction of the edge has no immediate meaning.

antisymmetric_edge_features : None or list

Indices of edge features that are forced to be anti-symmetric.

Methods

batch_inference(X, w[, relaxed])
batch_loss(Y, Y_hat)
batch_loss_augmented_inference(X, Y, w[, ...])
batch_psi(X, Y[, Y_true])
continuous_loss(y, y_hat)
get_edges(x)
get_features(x)
get_pairwise_potentials(x, w) Computes pairwise potentials for x and w.
get_unary_potentials(x, w) Computes unary potentials for x and w.
inference(x, w[, relaxed, return_energy]) Inference for x using parameters w.
loss(y, y_hat)
loss_augmented_inference(x, y, w[, relaxed, ...]) Loss-augmented Inference for x relative to y using parameters w.
max_loss(y)
psi(x, y) Feature vector associated with instance (x, y).
__init__(n_states=2, n_features=None, n_edge_features=1, inference_method='lp', class_weight=None, symmetric_edge_features=None, antisymmetric_edge_features=None)
get_pairwise_potentials(x, w)

Computes pairwise potentials for x and w.

Parameters :

x : tuple

Instance Representation.

w : ndarray, shape=(size_psi,)

Weight vector for CRF instance.

Returns :

pairwise : ndarray, shape=(n_states, n_states)

Pairwise weights.

get_unary_potentials(x, w)

Computes unary potentials for x and w.

Parameters :

x : tuple

Instance Representation.

w : ndarray, shape=(size_psi,)

Weight vector for CRF instance.

Returns :

unary : ndarray, shape=(n_states)

Unary weights.

inference(x, w, relaxed=False, return_energy=False)

Inference for x using parameters w.

Finds (approximately) armin_y np.dot(w, psi(x, y)) using self.inference_method.

Parameters :

x : tuple

Instance of a graph with unary evidence. x=(unaries, edges) unaries are an nd-array of shape (n_nodes, n_states), edges are an nd-array of shape (n_edges, 2)

w : ndarray, shape=(size_psi,)

Parameters for the CRF energy function.

relaxed : bool, default=False

Whether relaxed inference should be performed. Only meaningful if inference method is ‘lp’ or ‘ad3’. By default fractional solutions are rounded. If relaxed=True, fractional solutions are returned directly.

return_energy : bool, default=False

Whether to return the energy of the solution (x, y) that was found.

Returns :

y_pred : ndarray or tuple

By default an inter ndarray of shape=(width, height) of variable assignments for x is returned. If relaxed=True and inference_method is lp or ad3, a tuple (unary_marginals, pairwise_marginals) containing the relaxed inference result is returned. unary marginals is an array of shape (width, height, n_states), pairwise_marginals is an array of shape (n_states, n_states) of accumulated pairwise marginals.

loss_augmented_inference(x, y, w, relaxed=False, return_energy=False)

Loss-augmented Inference for x relative to y using parameters w.

Finds (approximately) armin_y_hat np.dot(w, psi(x, y_hat)) + loss(y, y_hat) using self.inference_method.

Parameters :

x : tuple

Instance of a graph with unary evidence. x=(unaries, edges) unaries are an nd-array of shape (n_nodes, n_features), edges are an nd-array of shape (n_edges, 2)

y : ndarray, shape (n_nodes,)

Ground truth labeling relative to which the loss will be measured.

w : ndarray, shape=(size_psi,)

Parameters for the CRF energy function.

relaxed : bool, default=False

Whether relaxed inference should be performed. Only meaningful if inference method is ‘lp’ or ‘ad3’. By default fractional solutions are rounded. If relaxed=True, fractional solutions are returned directly.

return_energy : bool, default=False

Whether to return the energy of the solution (x, y) that was found.

Returns :

y_pred : ndarray or tuple

By default an inter ndarray of shape=(n_nodes) of variable assignments for x is returned. If relaxed=True and inference_method is lp or ad3, a tuple (unary_marginals, pairwise_marginals) containing the relaxed inference result is returned. unary marginals is an array of shape (n_nodes, n_states), pairwise_marginals is an array of shape (n_states, n_states) of accumulated pairwise marginals.

psi(x, y)

Feature vector associated with instance (x, y).

Feature representation psi, such that the energy of the configuration (x, y) and a weight vector w is given by np.dot(w, psi(x, y)).

Parameters :

x : tuple

Input representation.

y : ndarray or tuple

Either y is an integral ndarray, giving a complete labeling for x. Or it is the result of a linear programming relaxation. In this case, y=(unary_marginals, pariwise_marginals).

Returns :

p : ndarray, shape (size_psi,)

Feature vector associated with state (x, y).