Classes, Solvers and Utilities

Graph_Class

class NuMeTriS.Graph_Class.Graph(adjacency=None)[source]

Graph instance must be initialised with the weighted adjacency matrix in 2D numpy array format. On initialization it computes in-degrees, out-degrees, reciprocated degrees, out-strengths, in-strengths, reciprocated strengths and triadic statistics such as occurrences, intensities and fluxes.

Parameters:: adjacency (np.ndarray) – Weighted adjacency matrix in 2D numpy array format.

numerical_triadic_zscores(n_ensemble=1000, percentiles=(2.5, 97.5))[source]

Compute triadic network structures on a statistical ensemble of networks. The computed statistics are triadic occurrences for DBCM and RBCM, and occurrences, intensities and fluxes for DBCM+CReMa and RBCM+CRWCM. After computing triadic statistics, also z-scores and significance scores are computed.

Parameters:

n_ensemble (float) – Chosen model, default is 1000.
percentiles (tuple) – Computed percentiles for estimated confidence interval in tuple format, default is (2.5,97.5) correspondent to a 95% CI.

plot_zscores(color='blue', linestyle='-', marker='o', alpha=0.3, export_path_zscores='', export_path_significance='', type='z-scores', label=None, show=False)[source]

Plot function for z-scores. If the model is DBCM or RBCM it plots z-scores for triadic occurrences. If it is DBCM+CReMa and RBCM+CRWCM, it plots z-scores for triadic occurrences, intensities and fluxes.

Parameters:

color (string) – Color of profiles and CIs, default is ‘blue’.
linestyle (string) – Linestyle for profiles.
marker (string) – Marker for profiles
alpha (string) – Degree of transparency for CI.
export_path_zscores – Export path for z-scores plot.
export_path_zscores – Export path for significance plot.
type – Type of plot, ‘z-scores’, ‘significance’ or ‘both’.
label (string) – Label for the legend in the plot.
show (boolean) – Arg for showing the plot in display.

solver(model, imported_params=numpy.array, imported_top_params=numpy.array, use_guess=numpy.array, maxiter=30, verbose=0.0, tol=1e-06)[source]

Optimize chosen model for Graph instance and compute log-likelihoods, jacobian, infinite norms and relative norms. The available models are DBCM and RBCM for the binary optimisation and DBCM+CReMa and RBCM+CRWCM for the mixture models.

Parameters:

model (string) – Chosen model
imported_params (np.ndarray) – If used, uses wanted parameters as solution, default is empty array.
imported_top_params – If used for mixture models, uses wanted parameters as solution for the binary problem, default is empty array.
use_guess (np.ndarray) – If used, uses wanted parameters as starters in the optimization, default is empty array.
maxiter (int) – Maximum Iterations of solver function, default is 30.
verbose (boolean) – True if you want to see every n*print_steps iterations, default is 0.
tol (float) – tolerance for infinite norm in the optimization process, default is 1e-06.

Utility Functions

NuMeTriS.Utility_Functions.IT_sampling_Exponential(random_array, cond_wij): Inverse Transform Sampling for the Exponential distribution.

NuMeTriS.Utility_Functions.L_rec(adj): Computes number of reciprocated links.

NuMeTriS.Utility_Functions.armijo_condition(f_old, f_new, alpha, grad_f, p, c1=0.0001): return boolean indicator if armijo wolfe condition are respected.

NuMeTriS.Utility_Functions.binarize(input): Compute binary projection of numpy matrix

NuMeTriS.Utility_Functions.compute_zscores(stat_emp, stat_exp, stat_down, stat_up, stat_std): Compute z-scores given expected statistics, empirical statistics and wanted percentiles.

NuMeTriS.Utility_Functions.curvature_condition(grad_f, grad_f_new, p, c2=0.9): return boolean indicator if curvature wolfe condition are respected.

NuMeTriS.Utility_Functions.deg(adj): Computes the degree centrality given binary adjacency matrix.

NuMeTriS.Utility_Functions.deg_left(adj): Computes the non-reciprocated in-degree centrality given binary adjacency matrix.

NuMeTriS.Utility_Functions.deg_out(adj): Computes the out-degree centrality given binary adjacency matrix.

NuMeTriS.Utility_Functions.deg_rec(adj): Computes the reciprocated degree centrality given binary adjacency matrix.

NuMeTriS.Utility_Functions.deg_right(adj): Computes the non-reciprocated out-degree centrality given binary adjacency matrix.

NuMeTriS.Utility_Functions.gen_binary_adjacencies(adj): Computes reciprocated and non-reciprocated components of binary adjacencies.

NuMeTriS.Utility_Functions.gen_rec_weighted_adjacencies(adj, w_adj): Computes reciprocated components of weighted adjacencies for fast computation of triadic fluxes.

NuMeTriS.Utility_Functions.gen_top_mat_DBCM(params): Generate a sample of the binary adjacency matrix via DBCM

NuMeTriS.Utility_Functions.gen_top_mat_RBCM(params): Generate a sample of the binary adjacency matrix via RBCM

NuMeTriS.Utility_Functions.gen_w_mat_CRWCM(weighted_params, fij_adj): Generate a sample of the weighted adjacency matrix via CRWCM

NuMeTriS.Utility_Functions.gen_w_mat_CReMa(weighted_params, fij_adj): Generate a sample of the weighted adjacency matrix via CReMa

NuMeTriS.Utility_Functions.gen_weighted_adjacencies(adj, w_adj): Computes reciprocated and non-reciprocated components of weighted adjacencies for fast computation of triadic intensities.

NuMeTriS.Utility_Functions.hess_CRWCM_after_RBCM_rec(params, s_rec_out, s_rec_in, params_RBCM): Computes opposite of the hessian function for the conditional weighted model CRWCM after the solution of RBCM, for the reciprocated sub-problem.

NuMeTriS.Utility_Functions.hess_CRWCM_after_RBCM_rl(params, s_right, s_left, params_RBCM): Computes opposite of the hessian function for the conditional weighted model CRWCM after the solution of RBCM, for the non-reciprocated sub-problem.

NuMeTriS.Utility_Functions.hess_CReMa_after_DBCM(params, s_out, s_in, params_DBCM)

Computes opposite of the hessian function for the conditional weighted model CReMa after the solution of DBCM.

Parameters:

params (np.ndarray) – Parameters for the CReMa after the solution of DBCM.
s_out (np.ndarray) – Empirical out-strength.
s_in (np.ndarray) – Empirical in-strength.
params_DBCM (np.ndarray) – Parameters for the solution of DBCM.

Returns:

Opposite of the hessian function for the CReMa model, after the solution of DBCM

Return type:

np.ndarray

NuMeTriS.Utility_Functions.hess_DBCM(params, k_out, k_in)

Computes opposite of the Hessian function for the DBCM.

Parameters:

params (np.ndarray) – parameter value for the computation of hessian.
k_out (np.ndarray) – empirical out-degree.
k_in (np.ndarray) – empirical in-degree.

Returns:

Opposite of Hessian.

Return type:

np.ndarray

NuMeTriS.Utility_Functions.hess_RBCM(params, k_right, k_left, k_rec)

Computes opposite of the Hessian function for the RBCM.

Parameters:

params (np.ndarray) – Parameters for the solution of RBCM.
k_right (np.ndarray) – Empirical non-reciprocated out-degree.
k_left (np.ndarray) – Empirical non-reciprocated in-degree.
k_rec (np.ndarray) – Empirical reciprocated degree.

Returns:

Opposite of the Hessian function for the RBCM

Return type:

np.ndarray

NuMeTriS.Utility_Functions.hessian_regulariser_function(B, eps): Auxiliary function to regularise hessian during Newton Optimisation.

NuMeTriS.Utility_Functions.is_pos_def(x): Auxiliary function to test definite positiveness of a matrix

NuMeTriS.Utility_Functions.jac_CRWCM_after_RBCM(params, s_right, s_left, s_rec_out, s_rec_in, params_RBCM): Computes opposite of the jacobian function for the conditional weighted model CRWCM after the solution of RBCM. Saved in self.jacobian.

NuMeTriS.Utility_Functions.jac_CRWCM_after_RBCM_rec(params, s_rec_out, s_rec_in, params_RBCM): Computes opposite of the jacobian function for the conditional weighted model CRWCM after the solution of RBCM, for the reciprocated sub-problem.

NuMeTriS.Utility_Functions.jac_CRWCM_after_RBCM_rl(params, s_right, s_left, params_RBCM): Computes opposite of the jacobian function for the conditional weighted model CRWCM after the solution of RBCM, for the non-reciprocated sub-problem.

NuMeTriS.Utility_Functions.jac_CReMa_after_DBCM(params, s_out, s_in, params_DBCM): Computes opposite of the jacobian function for the conditional weighted model CReMa after the solution of DBCM.

NuMeTriS.Utility_Functions.jac_DBCM(params, k_out, k_in): Opposite Jacobian for the DBCM, saved in self.jacobian

NuMeTriS.Utility_Functions.jac_RBCM(params, k_right, k_left, k_rec): Opposite jacobian function for the RBCM, saved in self.ll

NuMeTriS.Utility_Functions.linsearch_fun_CRWCM_separated(X, args): Function for the linear search of optimal parameter for Newton optimisation of CRWCM and CReMa.

NuMeTriS.Utility_Functions.linsearch_fun_DBCM(X, args): Function for the linear search of optimal parameter for Newton optimisation of DBCM.

NuMeTriS.Utility_Functions.linsearch_fun_RBCM(X, args): Function for the linear search of optimal parameter for Newton optimisation of RBCM.

NuMeTriS.Utility_Functions.ll_CRWCM_after_RBCM(params, s_right, s_left, s_rec_out, s_rec_in, params_RBCM): Computes opposite of the log-likelihood function for the conditional weighted model CRWCM after the solution of RBCM. Saved in self.ll.

NuMeTriS.Utility_Functions.ll_CRWCM_after_RBCM_rec(params, s_rec_out, s_rec_in, params_RBCM): Computes opposite of the log-likelihood function for the conditional weighted model CRWCM after the solution of RBCM for the reciprocated sub-problem.

NuMeTriS.Utility_Functions.ll_CRWCM_after_RBCM_rl(params, s_right, s_left, params_RBCM): Computes opposite of the log-likelihood function for the conditional weighted model CRWCM after the solution of RBCM for the non-reciprocated sub-problem.

NuMeTriS.Utility_Functions.ll_CReMa_after_DBCM(params, s_out, s_in, params_DBCM): Computes opposite of the log-likelihood function for the conditional weighted model CReMa after the solution of DBCM.

NuMeTriS.Utility_Functions.ll_DBCM(params, k_out, k_in): Opposite Log-likelihood function for the DBCM, saved in self.ll

NuMeTriS.Utility_Functions.ll_RBCM(params, k_right, k_left, k_rec): Opposite Log-likelihood function for the RBCM, saved in self.ll

NuMeTriS.Utility_Functions.matrixate(input): Compute a numpy matrix from corresponding flattened vector

NuMeTriS.Utility_Functions.n_edges_func(adj): Computes number of links.

NuMeTriS.Utility_Functions.occurrence_ensembler_DBCM(params, n_ensemble=1000, percentiles=(0, 100))[source]: Computes triadic occurrences as expected according to the DBCM.

NuMeTriS.Utility_Functions.occurrence_ensembler_RBCM(params, n_ensemble=1000, percentiles=(0, 100)): Computes triadic occurrences as expected according to the RBCM.

NuMeTriS.Utility_Functions.occurrence_intensity_fluxes_ensembler_DBCM_CReMa(params, n_ensemble=1000, percentiles=(0, 100))[source]: Computes triadic intensities and flusxes as expected according to the DBCM+CReMa.

NuMeTriS.Utility_Functions.occurrence_intensity_fluxes_ensembler_RBCM_CRWCM(params, n_ensemble=1000, percentiles=(0, 100))[source]: Computes triadic intensities and flusxes as expected according to the RBCM+CRWCM.

NuMeTriS.Utility_Functions.relative_error_CRWCM_after_RBCM(params, s_right, s_left, s_rec_out, s_rec_in, params_RBCM): Computes opposite of the relative error function for the conditional weighted model CRWCM after the solution of RBCM. Saved in self.relative_error.

NuMeTriS.Utility_Functions.relative_error_CReMa_after_DBCM(params, s_out, s_in, params_DBCM): Computes opposite of the relative_error function for the conditional weighted model CReMa after the solution of DBCM.

NuMeTriS.Utility_Functions.relative_error_DBCM(params, k_out, k_in): Relative error function for the DBCM, saved in self.relative_error.

NuMeTriS.Utility_Functions.relative_error_RBCM(params, k_right, k_left, k_rec): Relative error in the solution of the RBCM, saved in self.relative_error

NuMeTriS.Utility_Functions.solve_CRWCM_after_RBCM(s_right, s_left, s_rec_out, s_rec_in, params_RBCM, verbose=0, use_guess=numpy.array, maxiter=10, tol=1e-07)[source]

Solver for CRWCM after the solution of the RBCM.

Parameters:

s_right (np.nadarray) – empirical non-reciprocated out-strength
s_left (np.nadarray) – empirical non-reciprocated in-strength
s_rec_out (np.nadarray) – empirical reciprocated out-strength
s_rec_in (np.nadarray) – empirical reciprocated in-strength
params_RBCM (np.nadarray) – solution for the RBCM.
use_guess (np.ndarray) – initial guess for the solver.
maxiter (float) – maximum number of iterations for the solver, default is 10.
tol (float) – tolerance for the infinite norm of the jacobian for DBCM, default is 1e-07.

Returns:

solution of the optimisation problem.

Return type:

np.ndarray

NuMeTriS.Utility_Functions.solve_CReMa_after_DBCM(s_out, s_in, params_DBCM, verbose=0, use_guess=numpy.array, maxiter=10, tol=1e-07)[source]

Solver for CReMa after the solution of the DBCM.

Parameters:

s_out (np.nadarray) – empirical out-strength
s_in (np.nadarray) – empirical in-strength
params_DBCM (np.nadarray) – solution for the DBCM.
use_guess (np.ndarray) – initial guess for the solver.
maxiter (float) – maximum number of iterations for the solver, default is 10.
tol (float) – tolerance for the infinite norm of the jacobian for DBCM, default is 5e-03.

Returns:

solution of the optimisation problem.

Return type:

np.ndarray

NuMeTriS.Utility_Functions.solve_DBCM(k_out, k_in, use_guess=numpy.array, tol=0.005, maxiter=10)[source]

Solver for DBCM.

Parameters:

k_out (np.nadarray) – empirical out-degree
k_in (np.nadarray) – empirical in-degree
use_guess (np.nadarray) – initial guess for the solver.
tol (float) – tolerance for the infinite norm of the jacobian for DBCM, default is 5e-03.
maxiter (float) – maximum number of iterations for the solver, default is 10.

Returns:

solution of the optimisation problem.

Return type:

np.ndarray

NuMeTriS.Utility_Functions.solve_RBCM(k_right, k_left, k_rec, use_guess=numpy.array, tol=0.005, maxiter=10)[source]

Solver for RBCM.

Parameters:

k_right (np.nadarray) – empirical non-reciprocated out-degree
k_left (np.nadarray) – empirical non-reciprocated in-degree
k_rec (np.nadarray) – empirical reciprocated degree
use_guess (np.nadarray) – initial guess for the solver.
tol (float) – tolerance for the infinite norm of the jacobian for DBCM, default is 5e-03.
maxiter (float) – maximum number of iterations for the solver, default is 10.

Returns:

solution of the optimisation problem.

Return type:

np.ndarray

NuMeTriS.Utility_Functions.solver_newton(x0, ll, jac, hess, args=(), trust_mult=1e-05, lins=numba.jit, tol=1e-08, eps=1e-08, beta=0.5, alfa1=1, max_steps=1000, print_steps=numpy.inf)

Newton Optimisation Solver with optimal linear search and hessian trust region regularisation.

Parameters:

x0 (np.ndarry) – initial guess for the Optimiser
ll (object) – criterion function to be minimised.
jac (object) – jacobian of the criterion function to be minimised.
hess (object) – hessian of the criterion function to be minimised.
args (tuple) – args of the criterion function.
trust_mult (float) – trust radius for hessian regularisation, default is 1e-05
lins (object) – function for optimal linear search, default is the linsearch function for the CRWCM.
tol (float) – tolerance for the infinite norm of solution jacobian, default is 1e-08.
eps (float) – tolerance for difference of parameters during optimisation, default is 1e-08.
beta (float) – multiplier for the step during optimal linear search procedure.
alfa1 (float) – initialisation for the linear search parameter alfa.
max_steps (float) – maximum step during Newton optimisation, default is 1000.
print_steps (float) – interval in which steps are printed, default is np.inf (no printing).

Returns:

solution parameters

Return type:

np.ndarray

NuMeTriS.Utility_Functions.st_left(adj, w_adj): Computes the non-reciprocated in-strength centrality given binary adjacency matrix and weighted adjacency matrix.

NuMeTriS.Utility_Functions.st_rec_in(adj, w_adj): Computes the reciprocated in-strength centrality given binary adjacency matrix and weighted adjacency matrix.

NuMeTriS.Utility_Functions.st_rec_out(adj, w_adj): Computes the reciprocated out-strength centrality given binary adjacency matrix and weighted adjacency matrix.

NuMeTriS.Utility_Functions.st_right(adj, w_adj): Computes the non-reciprocated out-strength centrality given binary adjacency matrix and weighted adjacency matrix.

NuMeTriS.Utility_Functions.symmetrize(input): Symmetrize numpy matrix in input.

NuMeTriS.Utility_Functions.triadic_fluxes(adj_right, adj_left, adj_rec, adj_unrec, wadj_right, wadj_left, wadj_rec_out, wadj_rec_in): Computes the triadic average flux for the 13 triadic occurrences given the reciprocated and non-reciprocated components of the weighted adjacency matrix.

NuMeTriS.Utility_Functions.triadic_intensities(adj_right, adj_left, adj_rec, adj_unrec): Computes the triadic intensity for the 13 triadic occurrences given the reciprocated and non-reciprocated components of the weighted adjacency matrix.

NuMeTriS.Utility_Functions.triadic_occurrences(adj_right, adj_left, adj_rec, adj_unrec): Computes the triadic occurrence for the 13 triadic occurrences given the reciprocated and non-reciprocated components of the binary adjacency matrix.