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, lower average degrees, and smaller connected components. The graphs also have lower average shortest path length and network diameter per fixed word length (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.

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