core

snafu.core.addJumps(probs, td, numnodes=None, statdist=None, Xs=None)

Adjusts transition probabilities by incorporating jump behavior.

Depending on jump type (‘uniform’ or ‘stationary’), modifies the transition probabilities to allow for random jumps in the network.

Parameters:

• probs (list of list) – Original transition probabilities

• td (DataModel) – Data model containing the jump type and jump probability.

• numnodes (int, optional) – Number of nodes (required for uniform jump).

• statdist (array-like, optional) – Stationary distribution across nodes (required for stationary jump).

• Xs (list, optional) – List of token sequences (used with stationary jump).

Returns:

Jump-adjusted transition probabilities.

Return type:

list of list

snafu.core.adjustPriming(probs, td, Xs)

Modifies transition probabilities to account for priming across lists.

If an item appears at the end of a list and is followed by the same transition in the next list, it is treated as a primed transition and boosted by a configurable weight.

Parameters:

• probs (list of list) – Transition probability matrix for each list.

• td (DataModel) – Contains the priming parameter.

• Xs (list of list) – Sequences of node indices (one per participant/list).

Returns:

Transition probabilities adjusted for priming.

Return type:

list of list

snafu.core.communitynetwork(*args, **kwargs)

references conceptualNetwork

snafu.core.conceptualNetwork(Xs, numnodes=None, fitinfo={'cn_alpha': 0.05, 'cn_threshold': 2, 'cn_windowsize': 2, 'directed': False, 'estimatePerseveration': False, 'followtype': 'avg', 'other_limit': inf, 'prior_a': 2.0, 'prior_b': 1, 'prune_limit': inf, 'startGraph': 'cn_valid', 'triangle_limit': inf, 'zibb_p': 0.5}, valid=False, td=None)

Generate a semantic network using co-occurrence windows.

Builds a network by identifying how often item pairs co-occur within a specified window, and filters edges based on frequency and significance. w = window size; two items appear within +/- w steps of each other (where w=1 means adjacent items) f = filter frequency; if two items don’t fall within the same window more than f times, then no edge is inferred c = confidence interval; retain the edge if there is a <= c probability that two items occur within the same window n times by chance alone valid (t/f) ensures that graph can produce data using censored RW.

Parameters:

• Xs (list of list) – List of item sequences.

• numnodes (int, optional) – Total number of nodes.

• fitinfo (Fitinfo, optional) – Parameters controlling window size, frequency threshold, etc.

• valid (bool, optional) – If True, ensures resulting graph can produce valid walk data.

• td (DataModel, optional) – Required if valid=True.

Returns:

Binary adjacency matrix.

Return type:

ndarray

snafu.core.correlationBasedNetwork(Xs, numnodes=None, minlists=0, valid=False, td=None)

Generate a semantic network using item co-occurrence correlations.

Constructs a correlation matrix from binary item-by-list occurrence and builds a Planar Maximally Filtered Graph (PMFG) by retaining only non-redundant edges while maintaining planarity.

Parameters:

• Xs (list of list) – List of observed item sequences.

• numnodes (int, optional) – Number of unique nodes.

• minlists (int, optional) – Minimum number of lists an item must appear in to be included.

• valid (bool, optional) – If True, ensures the graph is usable with censored random walk.

• td (DataModel, optional) – Required if valid=True.

Returns:

Adjacency matrix of the PMFG network.

Return type:

ndarray

snafu.core.cost(graph, a, undirected=True)

Computes the link cost between two graphs.

Measures the number of differing edges between the estimated and target graph.

Parameters:

• graph (ndarray) – Estimated graph adjacency matrix.

• a (ndarray) – Target or comparison graph.

• undirected (bool, optional) – Whether the graphs are undirected. Default is True.

Returns:

Number of differing edges (adjusted for direction).

Return type:

float

snafu.core.costSDT(graph, a)

Computes signal detection theory metrics for graph comparison.

Returns hit, miss, false alarm, and correct rejection counts.

Parameters:

• graph (ndarray) – Estimated graph.

• a (ndarray) – Ground truth or comparison graph.

Returns:

[hits, misses, false alarms, correct rejections]

Return type:

list

snafu.core.estimateJumpProbability(group_network, data_model, fluency_list, return_ll: bool = False) → Tuple[float, float]

Grid-search jump in [0.01, 0.99] to maximize likelihood for ONE fluency list. Always returns a (best_jump, best_log_likelihood) tuple. If return_ll is False, best_log_likelihood will be np.nan and nothing is printed.

Parameters:

• group_network (np.ndarray (N x N)) – Adjacency matrix for the known network.

• data_model (DataModel) – SNAFU data model. Only the .jump field is varied here.

• fluency_list (list[int]) – Single fluency list as item indices aligned to group_network.

Returns:

Best jump probability (0.01..0.99).

Return type:

float

snafu.core.evalGraphPrior(a, prior, undirected=True)

Evaluates the log-likelihood of a graph under a prior.

Calculates the total log probability of a graph based on a learned or assumed edge prior.

Parameters:

• a (ndarray) – Graph adjacency matrix.

• prior (tuple) – A tuple of (priordict, item dictionary).

• undirected (bool, optional) – Whether the graph is undirected.

Returns:

Total log-likelihood of the graph given the prior.

Return type:

float

snafu.core.firstEdge(Xs, numnodes=None)

Constructs a graph connecting only the first two nodes of each list.

Parameters:

• Xs (list of list) – Node sequences.

• numnodes (int, optional) – Number of unique nodes.

Returns:

Binary adjacency matrix.

Return type:

ndarray

snafu.core.fullyConnected(numnodes)

Generate a fully connected undirected graph.

Parameters:

numnodes (int) – Number of nodes in the graph.

Returns:

Binary adjacency matrix with all non-diagonal elements set to 1.

Return type:

ndarray

snafu.core.genGraphPrior(graphs, items, fitinfo={'cn_alpha': 0.05, 'cn_threshold': 2, 'cn_windowsize': 2, 'directed': False, 'estimatePerseveration': False, 'followtype': 'avg', 'other_limit': inf, 'prior_a': 2.0, 'prior_b': 1, 'prune_limit': inf, 'startGraph': 'cn_valid', 'triangle_limit': inf, 'zibb_p': 0.5}, mincount=1, undirected=True, returncounts=False)

Generate edge prior probabilities from a collection of graphs.

Uses a beta-binomial or zero-inflated beta-binomial model to calculate edge presence probability across subjects or samples.

Parameters:

• graphs (list of ndarray) – List of adjacency matrices (one per subject).

• items (list of dict) – Mapping of item index to item label (one per graph).

• fitinfo (Fitinfo, optional) – Configuration object controlling prior method.

• mincount (int, optional) – Minimum number of observations required to include an edge.

• undirected (bool, optional) – Whether the graph is undirected.

• returncounts (bool, optional) – If True, returns raw counts instead of probabilities.

Returns:

Nested dictionary of edge probabilities or counts.

Return type:

dict

snafu.core.genStartGraph(Xs, numnodes, td, fitinfo)

Generate an initial graph for U-INVITE fitting based on strategy.

Strategy is determined by fitinfo.startGraph, which can include: - “cn_valid”, “pf_valid”, “rw”, “fully_connected”, etc.

Parameters:

• Xs (list of list) – Input fluency data.

• numnodes (int) – Number of unique nodes.

• td (DataModel) – Model configuration.

• fitinfo (Fitinfo) – Model fitting configuration.

Returns:

Starting adjacency matrix.

Return type:

ndarray

snafu.core.gtom(graph)

Compute the Generalized Topological Overlap Measure (GTOM).

Measures how similar nodes are in terms of shared neighbors. Currently supports GTOM with n=2.

Parameters:

graph (ndarray) – Adjacency matrix of a graph.

Returns:

Symmetric matrix of pairwise GTOM scores.

Return type:

ndarray

snafu.core.hierarchicalUinvite(Xs, items, numnodes=None, td={'censor_fault': 0.0, 'emission_fault': 0.0, 'jump': 0.0, 'jumponcensored': None, 'jumptype': 'stationary', 'priming': 0.0, 'start_node': 'stationary', 'trim': 1.0}, irts=False, fitinfo={'cn_alpha': 0.05, 'cn_threshold': 2, 'cn_windowsize': 2, 'directed': False, 'estimatePerseveration': False, 'followtype': 'avg', 'other_limit': inf, 'prior_a': 2.0, 'prior_b': 1, 'prune_limit': inf, 'startGraph': 'cn_valid', 'triangle_limit': inf, 'zibb_p': 0.5}, seed=None, debug=True)

Fit subject-level U-INVITE models in a hierarchical manner.

Iteratively fits subject graphs by conditioning on others’ graphs and generates a prior from group estimates. Process continues until no more changes in graphs are detected.

Parameters:

• Xs (list of list) – List of subject fluency data (sequences).

• items (list of dict) – Mapping of item indices to labels.

• numnodes (int or list of int, optional) – Number of unique nodes. If list, must match number of subjects.

• td (DataModel, optional) – Configuration for U-INVITE model.

• irts (list or bool, optional) – IRTs per subject or False to ignore.

• fitinfo (Fitinfo, optional) – Model settings (starting graph, limits, etc.).

• seed (int, optional) – Random seed.

• debug (bool, optional) – If True, prints debug output.

Returns:

• list of ndarray – List of fitted subject-level graphs.

• dict – Final group prior dictionary.

snafu.core.makeValid(Xs, graph, td, seed=None)

Modify the graph to ensure all transitions in Xs are reachable.

If a transition results in zero probability, adds necessary edges to make the sequence valid under the model.

Parameters:

• Xs (list of list) – Observed sequences.

• graph (ndarray) – Initial adjacency matrix.

• td (DataModel) – Configuration object.

• seed (int, optional) – Random seed for reproducibility.

Returns:

Modified, valid adjacency matrix.

Return type:

ndarray

snafu.core.naiveRandomWalk(Xs, numnodes=None, directed=False)

Build a graph by connecting items based on their sequential occurrence.

Parameters:

• Xs (list of list) – Lists of node sequences.

• numnodes (int, optional) – Total number of unique nodes.

• directed (bool, optional) – Whether to treat transitions as directed edges. Default is False.

Returns:

Binary adjacency matrix of the random walk graph.

Return type:

ndarray

snafu.core.pathfinder(Xs, numnodes=None, valid=False, td=None)

Constructs a Pathfinder network (minimal spanning tree) based on item co-occurrences.

The function builds a weighted graph from co-occurrence distances and then reduces it to a minimum spanning tree using the Pathfinder MST algorithm.

Parameters:

• Xs (list of list) – Sequence of observed node transitions.

• numnodes (int, optional) – Number of unique nodes.

• valid (bool, optional) – If True, ensures that the resulting graph can generate data using censored RW.

• td (DataModel, optional) – Used when valid=True.

Returns:

Binary adjacency matrix of the Pathfinder network.

Return type:

ndarray

snafu.core.priorToGraph(*args, **kwargs)

References priorToNetwork

snafu.core.priorToNetwork(priordict, items, cutoff=0.5, undirected=True)

Convert a prior probability dictionary into a binary graph.

Adds an edge between nodes if the prior probability exceeds a threshold.

Parameters:

• priordict (dict) – Nested dictionary of prior edge probabilities.

• items (dict) – Mapping of node index to item label.

• cutoff (float, optional) – Threshold for edge inclusion. Default is 0.5.

• undirected (bool, optional) – Whether to mirror edges for symmetry. Default is True.

Returns:

Binary adjacency matrix.

Return type:

ndarray

snafu.core.probX(Xs, a, td, irts={'data': [], 'irttype': 'none', 'rcutoff': 20}, prior=None, origmat=None, changed=[])

Compute the likelihood of observed sequences under a transition model.

Calculates the log-likelihood of each sequence under the given adjacency matrix using the U-INVITE framework. Supports censoring, priming, jumping, and IRT models.

Parameters:

• Xs (list of list) – Sequences of node transitions.

• a (ndarray) – Adjacency matrix representing the transition structure.

• td (DataModel) – Configuration object (jump, priming, censoring).

• irts (Irts, optional) – Inter-response time model. Default is empty.

• prior (tuple, optional) – (priordict, items) for computing graph priors.

• origmat (list of list, optional) – Previously computed probability matrix (for delta updates).

• changed (list, optional) – List of nodes that changed since origmat.

Returns:

• float – Log-likelihood of the data.

• list of list – Transition probabilities for each sequence.

snafu.core.probXhierarchical(Xs, graphs, items, td, priordict=None, irts={'data': [], 'irttype': 'none', 'rcutoff': 20})

Compute the total log-likelihood of a set of subject graphs under a hierarchical U-INVITE model.

For each subject, this function calculates the likelihood of their observed data given their individual graph and optionally a shared group prior. Returns the sum of log-likelihoods across all subjects.

Parameters:

• Xs (list of list) – Observed sequences for each subject.

• graphs (list of ndarray) – Individual graph (adjacency matrix) for each subject.

• items (list of dict) – Mapping of node indices to item labels for each subject.

• td (DataModel) – Data model settings including jump, priming, and censoring behavior.

• priordict (dict, optional) – Group prior used to condition each subject’s likelihood. If None, prior is not used.

• irts (Irts, optional) – Inter-response time data, one list per subject. Default is empty.

Returns:

Sum of log-likelihoods across all subjects.

Return type:

float

snafu.core.uinvite(Xs, td={'censor_fault': 0.0, 'emission_fault': 0.0, 'jump': 0.0, 'jumponcensored': None, 'jumptype': 'stationary', 'priming': 0.0, 'start_node': 'stationary', 'trim': 1.0}, numnodes=None, irts={'data': [], 'irttype': 'none', 'rcutoff': 20}, fitinfo={'cn_alpha': 0.05, 'cn_threshold': 2, 'cn_windowsize': 2, 'directed': False, 'estimatePerseveration': False, 'followtype': 'avg', 'other_limit': inf, 'prior_a': 2.0, 'prior_b': 1, 'prune_limit': inf, 'startGraph': 'cn_valid', 'triangle_limit': inf, 'zibb_p': 0.5}, prior=None, debug=True, seed=None)

Fit a graph to fluency data using the U-INVITE algorithm.

Iteratively searches over graph space to find a structure that maximizes likelihood under a random walk model, using triangle-based heuristics and pruning. Optionally adjusts for IRTs and perseverations.

Parameters:

• Xs (list of list) – Observed sequences of node transitions.

• td (DataModel, optional) – Model configuration (jump, priming, censoring).

• numnodes (int, optional) – Number of unique nodes in the network.

• irts (Irts, optional) – IRT model information.

• fitinfo (Fitinfo, optional) – Algorithm parameters including edge strategy and convergence criteria.

• prior (tuple, optional) – Prior probability dictionary and item mappings.

• debug (bool, optional) – If True, prints debug output.

• seed (int, optional) – Random seed.

Returns:

• ndarray – Fitted graph adjacency matrix.

• float – Log-likelihood of the fitted graph.