`modeling`¶

Provide standalone modeling and inference functions for Adjacency matrices.

Each function takes an Adjacency instance as its first argument (adj).

Methods:

Name	Description
`bootstrap`	Bootstrap statistics using efficient online algorithms.
`convert_bootstrap_results_to_adjacency`	Convert bootstrap results dictionary to Adjacency format.
`generate_permutations`	Generate permuted versions of an Adjacency instance lazily.
`regress`	Run a regression on an adjacency instance.
`social_relations_model`	Estimate the social relations model from a matrix for a round-robin design.

Methods¶

`bootstrap`¶

bootstrap(adj, stat, *, n_samples = 5000, save_boots = False, percentiles = (2.5, 97.5), tail = 2, n_jobs = -1, random_state = None, progress_bar = False)

Bootstrap statistics using efficient online algorithms.

Uses memory-efficient bootstrap infrastructure with CPU parallelization. Supports simple aggregation statistics (mean, std, median, sum, min, max).

Parameters:

Name	Description	Default
`adj`	(Adjacency) Adjacency instance containing multiple matrices	required
`stat`	(str) Statistic to bootstrap. Options: - Simple stats: ‘mean’, ‘median’, ‘std’, ‘sum’, ‘min’, ‘max’	required
`n_samples`	(int) Number of bootstrap iterations. Default: 5000	`5000`
`save_boots`	(bool) If True, store all bootstrap samples (memory intensive). Default: False	`False`
`percentiles`	(tuple) Percentiles for confidence intervals. Default: (2.5, 97.5)	`(2.5, 97.5)`
`tail`	2	‘two’ (two-tailed, default) or 1
`n_jobs`	(int) Number of CPU cores for parallelization. -1 means all CPUs.	`-1`
`random_state`	(int, optional) Random seed for reproducibility	`None`
`progress_bar`	(bool) If True, show a progress bar. Default False.	`False`

Returns:

Name	Type	Description
`dict`		Dictionary with keys: ‘Z’, ‘p’, ‘mean’, ‘std’, ‘ci_lower’, ‘ci_upper’ (all Adjacency objects). If save_boots=True, also includes ‘samples’.

Examples:

>>> # Simple aggregation
>>> boot = bootstrap(adj, stat='mean', n_samples=1000)
>>> assert 'mean' in boot
>>> assert isinstance(boot['mean'], Adjacency)

`convert_bootstrap_results_to_adjacency`¶

convert_bootstrap_results_to_adjacency(adj, result, save_boots = False)

Convert bootstrap results dictionary to Adjacency format.

Helper function to convert numpy arrays from bootstrap functions into Adjacency objects.

Parameters:

Name	Description	Default
`adj`	(Adjacency) Adjacency instance (used for matrix_type metadata)	required
`result`	(dict) Result dictionary from bootstrap function with keys: ‘mean’, ‘std’, ‘Z’, ‘p’, ‘ci_lower’, ‘ci_upper’, and optionally ‘samples’	required
`save_boots`	(bool) If True, include ‘samples’ key in output	`False`

Returns:

Name	Type	Description
`dict`		Dictionary with Adjacency objects for each statistic

`generate_permutations`¶

generate_permutations(adj, n_permute, random_state = None)

Generate permuted versions of an Adjacency instance lazily.

This is useful for iterative comparisons.

Parameters:

Name	Type	Description	Default
`adj`		(Adjacency) Adjacency instance	required
`n_permute`	`int`	number of permutations	required
`random_state`	`int or RandomState`	random seed for reproducibility. Defaults to None.	`None`

Examples:

>>> for perm in generate_permutations(adj, 1000):
>>>     out = neural_distance_mat.similarity(perm)
>>>     ...

Yields:

Name	Type	Description
`Adjacency`		permuted version of adj

`regress`¶

regress(adj, X, method = 'ols', tail = 2)

Run a regression on an adjacency instance. You can decompose an adjacency instance with another adjacency instance. You can also decompose each pixel by passing a design_matrix instance.

Parameters:

Name	Description	Default
`adj`	(Adjacency) Adjacency instance	required
`X`	Design matrix can be an Adjacency or DesignMatrix instance	required
`method`	type of regression (default: ols) - only ‘ols’ is currently supported	`‘ols’`
`tail`	2	‘two’ (two-tailed, default) or 1

Returns:

Name	Type	Description
`stats`		(dict) dictionary of stats outputs.

social_relations_model(adj, summarize_results = True, nan_replace = True)

Estimate the social relations model from a matrix for a round-robin design.

X_{ij} = m + \alpha_i + \beta_j + g_{ij} + \epsilon_{ijl}

(1)

where $X_{ij}$ is the score for person i rating person j, $m$ is the group mean, $\alpha_i$ is person i’s actor effect, $\beta_j$ is person j’s partner effect, $g_{ij}$ is the relationship effect and $\epsilon_{ijl}$ is the error in measure l for actor i and partner j.

This model is primarily concerned with partioning the variance of the various effects.

Code is based on implementation presented in Chapter 8 of Kenny, Kashy, & Cook (2006). Tests replicate examples presented in the book. Note, that this method assumes that actor scores are rows (lower triangle), while partner scores are columnns (upper triangle). The minimal sample size to estimate these effects is 4.

In the future we might update the formulas and standard errors based on Bond and Lashley, 1996

Parameters:

Name	Description	Default
`adj`	(Adjacency) can be a single matrix or many matrices for each group	required
`summarize_results`	(bool) will provide a formatted summary of model results	`True`
`nan_replace`	(bool) will replace nan values with row and column means	`True`

Returns:

Type	Description
estimated effects: (pd.Series/pd.DataFrame) All of the effects estimated using SRM

modeling

modeling¶

Methods¶

bootstrap¶

convert_bootstrap_results_to_adjacency¶

generate_permutations¶

regress¶

social_relations_model¶

`modeling`¶

`bootstrap`¶

`convert_bootstrap_results_to_adjacency`¶

`generate_permutations`¶

`regress`¶

`social_relations_model`¶