PsychiatryNLPKit.analysis.structural_graph

PsychiatryNLPKit.analysis.structural_graph(content_words, directed=True, weighted=True, sections=None, n_random_graphs=1000)

Constructs a structural graph from lemmatized content words per section and immediately computes all network metrics.

Notes:

Theoretical basis - Graphs from schizophrenia patients show fewer nodes and edges, higher average weighted degrees, and smaller connected components. Structural graphs also exhibit more random-like organization (lower z-scores for largest connected component and average shortest path length relative to Erdos-Renyi null models) (Nikzad et al., 2022).

Args:

content_words: Dict mapping section names to lists of lemmatized content

words.

directed: Whether the constructed graph is directed (word transitions).

Defaults to True.

weighted: Whether to assign edge weights based on repetition count. Edge

weight equals consecutive occurrence count; distance = 1/weight for path calculations.

sections: Sections to process. None processes all sections in

content_words.

n_random_graphs: Number of random graphs to generate for z-score

computation. Defaults to 1000. Performance note: this incurs a non negligible runtime cost. For each section, n_random_graphs random graphs are generated and analyzed. With N sections, total cost is O(N * n_random_graphs). For large datasets, consider reducing this parameter or pre-computing null distributions for common node/edge counts.

Returns:

Dict mapping section names to a metric dict with keys: nodes_count, edges_count, average_degree, density, diameter, average_shortest_path_length, largest_connected_component, largest_strongly_connected_component, lcc/n, lsc/n, edge_weight_repetition_index, lcc_z_score, lsc_z_score, aspl_z_score, degree_distribution_z_score. Metrics lcc_z_score and aspl_z_score follow Nikzad et al. (2022); the remaining network-size, connectivity, and degree-distribution metrics are extensions beyond the original paper. Sections with no content words keep nodes_count and edges_count at 0.0 and receive float("nan") for every derived metric; z-scores are also float("nan") when the null distribution has no variance.

References:

Nikzad, A. H., Cong, Y., Berretta, S., Hänsel, K., Cho, S., Pradhan, S., Behbehani, L., DeSouza, D. D., Liberman, M. Y., & Tang, S. X. (2022). Who does what to whom? graph representations of action-predication in speech relate to psychopathological dimensions of psychosis. Schizophrenia, 8(1), 58. https://doi.org/10.1038/s41537-022-00263-7