RESCAL.py is a python script to compute the RESCAL algorithm as described in [1].

Example Code to use with the US Presidents Python dataset:

import pickle, sys
from rescal import rescal

rank = sys.argv[1]
X = pickle.load('us-presidents.pickle')
A, R, f, iter, exectimes = rescal(X, rank, lmbda=1.0)

The structure of $X$ must be the following: $X$ must be a list, where each entry $X_k$ is a $n \times n$ NumPy array. $X_k$ can be any real-valued array.

To use RESCAL for relational learning as described in [1] construct each $X_k$ as following: Each $X_k$ represents exactly one relation and has the entries

$X_k[i,j] = \begin{cases} 1, \text{ entities } i,j \text{ are related by relation } k \\ 0, \text{ otherwise } \end{cases}$

References

[1]	(1, 2) Maximilian Nickel, Volker Tresp, Hans-Peter Kriegel, A Three-Way Model for Collective Learning on Multi-Relational Data, ICML 2011, Bellevue, WA, USA.

API Documentation¶

rescal.rescal(X, rank, **kwargs)¶

RESCAL

Factors a three-way tensor X such that each frontal slice X_k = A * R_k * A.T. The frontal slices of a tensor are N x N matrices that correspond to the adjecency matrices of the relational graph for a particular relation.

For a full description of the algorithm see:: Maximilian Nickel, Volker Tresp, Hans-Peter-Kriegel, “A Three-Way Model for Collective Learning on Multi-Relational Data”, ICML 2011, Bellevue, WA, USA

Parameters :

Parameters :	X : list List of frontal slices X_k of the tensor X. The shape of each X_k is (‘N’, ‘N’) rank : int Rank of the factorization lmbda : float, optional Regularization parameter for A and R_k factor matrices. 0 by default init : string, optional Initialization method of the factor matrices. ‘nvecs’ (default) initializes A based on the eigenvectors of X. ‘random’ initializes the factor matrices randomly. proj : boolean, optional Whether or not to use the QR decomposition when computing R_k. True by default maxIter : int, optional Maximium number of iterations of the ALS algorithm. 500 by default. conv : float, optional Stop when residual of factorization is less than conv. 1e-5 by default
Returns :	A : ndarray array of shape (‘N’, ‘rank’) corresponding to the factor matrix A R : list list of ‘M’ arrays of shape (‘rank’, ‘rank’) corresponding to the factor matrices R_k f : float function value of the factorization iter : int number of iterations until convergence exectimes : ndarray execution times to compute the updates in each iteration

X : list

List of frontal slices X_k of the tensor X. The shape of each X_k is (‘N’, ‘N’)

rank : int

Rank of the factorization

lmbda : float, optional

Regularization parameter for A and R_k factor matrices. 0 by default

init : string, optional

Initialization method of the factor matrices. ‘nvecs’ (default) initializes A based on the eigenvectors of X. ‘random’ initializes the factor matrices randomly.

proj : boolean, optional

Whether or not to use the QR decomposition when computing R_k. True by default

maxIter : int, optional

Maximium number of iterations of the ALS algorithm. 500 by default.

conv : float, optional

Stop when residual of factorization is less than conv. 1e-5 by default

Returns :

A : ndarray

array of shape (‘N’, ‘rank’) corresponding to the factor matrix A

R : list

list of ‘M’ arrays of shape (‘rank’, ‘rank’) corresponding to the factor matrices R_k

f : float

function value of the factorization

iter : int

number of iterations until convergence

exectimes : ndarray

execution times to compute the updates in each iteration

rescal.rescal_with_random_restarts(X, rank, restarts=10, **kwargs)¶: Restarts RESCAL multiple time from random starting point and returns factorization with best fit.

RESCAL v0.1 documentation

API Documentation

API Documentation¶