Análisis de redes

Leer las redes: métricas globales, centralidad por nodo, detección de comunidades, asortatividad y composición de comunidades, más el informe de calidad específico de la red de co-citación.

network_metrics

network_metrics(g: _Graph) -> dict[str, object]

Densidad, nº de componentes y clustering promedio del grafo.

Parameters:

Name	Type	Description	Default
g	_Graph	Grafo NetworkX (no dirigido).	required

Returns:

Type	Description
dict[str, object]	Dict con claves 'density', 'num_components', 'avg_clustering'.

centrality

centrality(g: _Graph) -> dict[str, dict[Any, float]]

Centralidad de grado e intermediación por nodo.

Parameters:

Name	Type	Description	Default
g	_Graph	Grafo NetworkX (no dirigido).	required

Returns:

Type	Description
dict[str, dict[Any, float]]	Dict con claves 'degree' y 'betweenness', cada una mapeando
dict[str, dict[Any, float]]	nodo → valor de centralidad.

detect_communities

detect_communities(
    g: _Graph,
    method: str = "louvain",
    *,
    random_state: int | None = None,
    resolution: float = 1.0,
) -> dict[Any, int]

Detecta comunidades en el grafo con el método indicado.

R2 (ADR 0017 enmendado): el parámetro random_state siembra el generador de Louvain de forma determinista cuando se provee. Pasarlo derivado del corpus_hash de contenido (ver facade.py) garantiza "mismo corpus + mismo spec → mismas comunidades".

Parameters:

Name	Type	Description	Default
g	_Graph	Grafo NetworkX (no dirigido).	required
method	str	Algoritmo de detección. Uno de 'louvain', 'label_prop', 'greedy_modularity'.	'louvain'
random_state	int | None	Semilla entera para reproducibilidad de Louvain (solo se usa cuando method='louvain'). Si es None, Louvain corre sin semilla (no reproducible).	None
resolution	float	Parámetro de resolución para Louvain (best_partition). Default 1.0 = comportamiento estándar de python-louvain. Se ignora para label_prop y greedy_modularity (no es un error; esos algoritmos no tienen parámetro de resolución equivalente).	1.0

Returns:

Type	Description
dict[Any, int]	Dict nodo → id de comunidad (int).

Raises:

Type	Description
ImportError	Si se solicita 'louvain' y python-louvain no está instalado. Falla explícito con el nombre del paquete a instalar (lección 7 de v0; AGENTS.md §manejo de errores).
ValueError	Si method no es reconocido.

assortativity

assortativity(
    g: _Graph,
    *,
    attribute: str | None = None,
    by_degree: bool = True,
    proxy: str | None = None,
) -> dict[str, object]

Asortatividad por atributo categórico configurable y/o por grado.

El atributo y sus categorías son config del usuario (no se hardcodea ningún campo como 'region'; crítica #5 del sandbox IED).

Cuando se pasa proxy, el resultado incluye 'proxy_disclaimer' advirtiendo que el atributo es un proxy, no el campo real (D4).

Parameters:

Name	Type	Description	Default
g	_Graph	Grafo NetworkX (no dirigido).	required
attribute	str | None	Nombre del atributo de nodo para asortatividad categórica. Si es None, no se calcula la asortatividad por atributo.	None
by_degree	bool	Si True, calcula asortatividad por grado.	True
proxy	str | None	Si se pasa un string, indica que attribute es un proxy del campo real (p. ej. 'affiliation_per_paper'). Se añade un disclaimer al resultado.	None

Returns:

Type	Description
dict[str, object]	Dict con 'attribute_assortativity' (si attribute fue dado),
dict[str, object]	'degree_assortativity' (si by_degree=True), y
dict[str, object]	'proxy_disclaimer' (si proxy fue dado).

community_composition

community_composition(
    g: _Graph, communities: dict[Any, int], attribute: str
) -> dict[int, dict[str, float]]

Composición porcentual de cada comunidad por atributo categórico.

Parameters:

Name	Type	Description	Default
g	_Graph	Grafo NetworkX con atributos de nodo.	required
communities	dict[Any, int]	Dict nodo → id de comunidad (salida de detect_communities).	required
attribute	str	Nombre del atributo de nodo a usar.	required

Returns:

Type	Description
dict[int, dict[str, float]]	Dict comunidad → Dict categoría → fracción (0.0 a 1.0). La suma de
dict[int, dict[str, float]]	fracciones por comunidad es 1.0 si todos los nodos tienen el atributo.

cocitation_quality_report

cocitation_quality_report(
    corpus: Corpus,
    *,
    thresholds: QualityThresholds | None = None,
) -> dict[str, object]

Informe de calidad de la red de co-citación según metodología §4.

Evalúa 4 criterios configurables y devuelve un dict estructurado (D6): {criterio: {valor, umbral, pasa}} + "overall_pass": bool. Sin score ponderado.

R5: param muerto g eliminado (Nota 06, catálogo de secundarios). El grafo no se usaba en ningún criterio; pasarlo era un anti-patrón que ARCHITECTURE §8 dice evitar.

Parameters:

Name	Type	Description	Default
corpus	Corpus	Corpus a evaluar.	required
thresholds	QualityThresholds | None	Umbrales configurables. Si None, usa QualityThresholds() con los defaults de metodología §4.	None

Returns:

Type	Description
dict[str, object]	Dict con claves por criterio y "overall_pass": bool.

QualityThresholds

Bases: BaseModel

Umbrales configurables para el informe de calidad de co-citación.

Los defaults sensatos son los de metodología §4. Se pueden sobreescribir para adaptar a otros campos de investigación (crítica #5).

Attributes:

Name	Type	Description
min_volume	int	Número mínimo de papers en el corpus.
min_doi_refs_pct	float	Fracción mínima de papers con DOI.
min_countries	int	Número mínimo de países distintos (vía institutions_id).
min_recurrent_authors	int	Nº mínimo de autores que aparecen en ≥2 papers.