ohtli 0.1.0__py3-none-any.whl

ohtli/__init__.py

@@ -0,0 +1,43 @@
+"""
+beta_skeletons
+==============
+Librería para el cálculo y visualización de β-esqueletos.
+
+Algoritmo de fuerza bruta — O(n^3).
+
+Referencia principal:
+    Kirkpatrick, D. G. y Radke, J. D. (1985).
+    A Framework for Computational Morphology.
+    Computational Geometry, pp. 217-248.
+
+Uso básico
+----------
+>>> import numpy as np
+>>> from ohtli import adjacency_matrix, build_graph
+>>> coords = np.array([[0,0],[1,0],[2,0],[1,1]])
+>>> adj = adjacency_matrix(coords, beta=1.0)
+>>> G   = build_graph(coords, beta=2.0)
+"""
+
+from .skeleton import adjacency_matrix, build_graph
+from .geometry import point_in_lune, is_beta_neighbor
+from .metrics import relative_asymmetry, control_value
+from .viz import plot_points, plot_lune, plot_skeleton, plot_metric_bars
+
+print("Cargando la librería ohtli...")
+
+__all__ = [
+    "adjacency_matrix",
+    "build_graph",
+    "point_in_lune",
+    "is_beta_neighbor",
+    "relative_asymmetry",
+    "control_value",
+    "plot_points",
+    "plot_lune",
+    "plot_skeleton",
+    "plot_metric_bars",
+]
+
+__version__ = "0.1.0"
+__author__ = "Tu nombre"

ohtli/geometry.py

@@ -0,0 +1,99 @@
+"""
+geometry.py
+-----------
+Funciones geométricas para el cálculo de β-esqueletos.
+Implementa la definición de Kirkpatrick y Radke (1985) para
+vecindades tipo luna (lune-based neighbourhoods).
+"""
+
+import numpy as np
+
+
+def _lune_centers_and_radius(p1: np.ndarray, p2: np.ndarray, beta: float):
+    """
+    Calcula los centros y radio de los dos discos que definen
+    la luna de influencia del par (p1, p2) para un valor beta dado.
+
+    Para beta >= 1:
+        radio = beta * d(p1, p2) / 2
+        centros desplazados hacia el interior del segmento.
+
+    Para beta < 1:
+        radio = d(p1, p2) / (2 * beta)
+        centros en p1 y p2.
+
+    Parámetros
+    ----------
+    p1, p2 : np.ndarray de forma (2,)
+    beta   : float > 0
+
+    Retorna
+    -------
+    center1, center2 : np.ndarray de forma (2,)
+    r                : float
+    """
+    d = np.linalg.norm(p2 - p1)
+    if d == 0:
+        raise ValueError("Los puntos p1 y p2 son idénticos.")
+    if beta <= 0:
+        raise ValueError("beta debe ser estrictamente positivo.")
+
+    if beta >= 1:
+        r = beta * d / 2
+        direction = (p2 - p1) / d
+        center1 = p1 + (1 - beta / 2) * (p2 - p1)
+        center2 = p2 + (1 - beta / 2) * (p1 - p2)
+    else:
+        r = d / (2 * beta)
+        center1 = p1.copy()
+        center2 = p2.copy()
+
+    return center1, center2, r
+
+
+def point_in_lune(pk: np.ndarray, p1: np.ndarray, p2: np.ndarray, beta: float) -> bool:
+    """
+    Determina si el punto pk está en el interior de la luna
+    de influencia del par (p1, p2) para el parámetro beta.
+
+    Un punto está en la luna si y solo si está dentro de
+    ambos discos simultáneamente (intersección estricta).
+
+    Parámetros
+    ----------
+    pk     : np.ndarray de forma (2,) — punto a evaluar
+    p1, p2 : np.ndarray de forma (2,) — par de puntos
+    beta   : float > 0
+
+    Retorna
+    -------
+    bool : True si pk está en el interior de la luna
+    """
+    center1, center2, r = _lune_centers_and_radius(p1, p2, beta)
+    return (np.linalg.norm(pk - center1) < r and
+            np.linalg.norm(pk - center2) < r)
+
+
+def is_beta_neighbor(coords: np.ndarray, i: int, j: int, beta: float) -> bool:
+    """
+    Determina si los puntos i y j son β-vecinos en el conjunto coords,
+    es decir, si la luna de influencia del par (i, j) está vacía.
+
+    Parámetros
+    ----------
+    coords : np.ndarray de forma (n, 2)
+    i, j   : int — índices del par a evaluar
+    beta   : float > 0
+
+    Retorna
+    -------
+    bool : True si la luna está vacía (i y j son β-vecinos)
+    """
+    p1, p2 = coords[i], coords[j]
+    n = len(coords)
+    for k in range(n):
+        if k == i or k == j:
+            continue
+        if point_in_lune(coords[k], p1, p2, beta):
+            return False
+    return True

ohtli/metrics.py

@@ -0,0 +1,83 @@
+"""
+metrics.py
+----------
+Métricas de análisis sobre grafos de β-esqueletos.
+
+Incluye:
+    - Asimetría relativa (RA) por nodo
+    - Valor de control por nodo
+"""
+
+import networkx as nx
+
+
+def relative_asymmetry(G: nx.Graph) -> dict:
+    """
+    Calcula la asimetría relativa (RA) para cada nodo del grafo.
+
+    La RA mide la centralidad de un nodo en términos de profundidad
+    media respecto al resto de nodos del grafo.
+
+    Fórmula:
+        RA_i = 2 * (MD_i - 1) / (n - 2)
+
+    donde MD_i es la profundidad media del nodo i (media de las
+    longitudes de caminos más cortos hacia todos los demás nodos).
+
+    Parámetros
+    ----------
+    G : nx.Graph
+        Grafo conectado.
+
+    Retorna
+    -------
+    dict : {nodo: valor_RA}
+
+    Notas
+    -----
+    Para grafos desconectados, los nodos sin camino hacia algún otro
+    nodo tendrán RA indefinida. Se recomienda verificar conectividad
+    antes de aplicar esta métrica.
+    """
+    n = G.number_of_nodes()
+    if n < 3:
+        return {node: 0.0 for node in G.nodes()}
+
+    ra = {}
+    for node in G.nodes():
+        lengths = nx.single_source_shortest_path_length(G, node)
+        total_depth = sum(d for target, d in lengths.items() if target != node)
+        md = total_depth / (n - 1)
+        ra[node] = 2 * (md - 1) / (n - 2)
+
+    return ra
+
+
+def control_value(G: nx.Graph) -> dict:
+    """
+    Calcula el valor de control para cada nodo del grafo.
+
+    El valor de control de un nodo i es la suma de los inversos
+    del grado de cada uno de sus vecinos:
+
+        CV_i = sum_{j ∈ N(i)} 1 / deg(j)
+
+    Un nodo con alto valor de control está conectado a vecinos
+    de bajo grado, lo que le otorga mayor influencia estructural.
+
+    Parámetros
+    ----------
+    G : nx.Graph
+
+    Retorna
+    -------
+    dict : {nodo: valor_control}
+    """
+    cv = {}
+    for node in G.nodes():
+        neighbors = list(G.neighbors(node))
+        if not neighbors:
+            cv[node] = 0.0
+        else:
+            cv[node] = sum(1 / G.degree(nb) for nb in neighbors)
+    return cv

ohtli/skeleton.py

@@ -0,0 +1,111 @@
+"""
+skeleton.py
+-----------
+Algoritmo de fuerza bruta para calcular β-esqueletos.
+Complejidad temporal: O(n^3).
+
+Referencia:
+    Kirkpatrick, D. G. y Radke, J. D. (1985).
+    A Framework for Computational Morphology.
+    Computational Geometry, pp. 217-248.
+"""
+
+import numpy as np
+import networkx as nx
+
+from .geometry import is_beta_neighbor
+
+
+def adjacency_matrix(coords: np.ndarray, beta: float = 1.0) -> np.ndarray:
+    """
+    Calcula la matriz de adyacencia del β-esqueleto de un conjunto
+    de puntos mediante fuerza bruta.
+
+    Para cada par (i, j), verifica si la luna de influencia está vacía.
+    La matriz resultante es simétrica y sin auto-lazos.
+
+    Complejidad: O(n^3)
+
+    Parámetros
+    ----------
+    coords : np.ndarray de forma (n, 2)
+        Coordenadas de los n puntos en el plano.
+    beta   : float > 0
+        Parámetro que controla el tamaño de la región de influencia.
+        beta = 1  → Grafo de Gabriel
+        beta = 2  → Grafo de vecindad relativa (RNG)
+
+    Retorna
+    -------
+    np.ndarray de forma (n, n), dtype int
+        Matriz de adyacencia binaria y simétrica.
+
+    Ejemplos
+    --------
+    >>> import numpy as np
+    >>> from beta_skeletons import adjacency_matrix
+    >>> coords = np.array([[0,0],[1,0],[2,0]])
+    >>> adjacency_matrix(coords, beta=1.0)
+    array([[0, 1, 0],
+           [1, 0, 1],
+           [0, 1, 0]])
+    """
+    coords = np.asarray(coords, dtype=float)
+    if coords.ndim != 2 or coords.shape[1] != 2:
+        raise ValueError("coords debe tener forma (n, 2).")
+    if beta <= 0:
+        raise ValueError("beta debe ser estrictamente positivo.")
+
+    n = len(coords)
+    matrix = np.zeros((n, n), dtype=int)
+
+    for i in range(n):
+        for j in range(i + 1, n):
+            if is_beta_neighbor(coords, i, j, beta):
+                matrix[i, j] = 1
+                matrix[j, i] = 1
+
+    return matrix
+
+
+def build_graph(
+    coords: np.ndarray,
+    beta: float = 1.0,
+    labels: list | None = None,
+) -> nx.Graph:
+    """
+    Construye el β-esqueleto como un grafo de NetworkX.
+
+    Cada nodo almacena su posición ('pos') y, opcionalmente,
+    su etiqueta ('label').
+
+    Parámetros
+    ----------
+    coords : np.ndarray de forma (n, 2)
+    beta   : float > 0
+    labels : list de str, opcional
+        Nombres de los nodos. Si es None se usan índices enteros.
+
+    Retorna
+    -------
+    nx.Graph
+        Grafo con atributos 'pos' y 'label' en cada nodo.
+    """
+    coords = np.asarray(coords, dtype=float)
+    n = len(coords)
+
+    if labels is not None and len(labels) != n:
+        raise ValueError("labels debe tener la misma longitud que coords.")
+
+    adj = adjacency_matrix(coords, beta=beta)
+    G = nx.Graph()
+
+    for i, (x, y) in enumerate(coords):
+        G.add_node(i, pos=(x, y), label=labels[i] if labels is not None else str(i))
+
+    for i in range(n):
+        for j in range(i + 1, n):
+            if adj[i, j] == 1:
+                G.add_edge(i, j)
+
+    return G

ohtli/viz.py

@@ -0,0 +1,232 @@
+"""
+viz.py
+------
+Funciones de visualización para β-esqueletos y sus métricas.
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.cm as cm
+import networkx as nx
+from matplotlib.patches import Circle
+from adjustText import adjust_text
+
+from .geometry import _lune_centers_and_radius
+from .skeleton import build_graph
+
+
+def plot_points(
+    coords: np.ndarray,
+    labels: list | None = None,
+    ax: plt.Axes | None = None,
+    title: str = "Conjunto de puntos",
+) -> plt.Axes:
+    """
+    Grafica un conjunto de puntos con etiquetas opcionales.
+
+    Parámetros
+    ----------
+    coords : np.ndarray de forma (n, 2)
+    labels : list de str, opcional
+    ax     : plt.Axes, opcional — si None se crea una figura nueva
+    title  : str
+
+    Retorna
+    -------
+    plt.Axes
+    """
+    if ax is None:
+        _, ax = plt.subplots(figsize=(10, 10))
+
+    ax.scatter(coords[:, 0], coords[:, 1], color="steelblue", s=50, zorder=5)
+
+    if labels is not None:
+        texts = [ax.text(x, y, labels[i], fontsize=8)
+                 for i, (x, y) in enumerate(coords)]
+        adjust_text(
+            texts, ax=ax,
+            arrowprops=dict(arrowstyle="->", color="gray", lw=0.5),
+            expand_points=(1.2, 1.2),
+        )
+
+    ax.set_xlabel("Longitud")
+    ax.set_ylabel("Latitud")
+    ax.set_title(title)
+    ax.axis("equal")
+    ax.grid(True)
+    return ax
+
+
+def plot_lune(
+    coords: np.ndarray,
+    i: int,
+    j: int,
+    beta: float = 1.0,
+    labels: list | None = None,
+    ax: plt.Axes | None = None,
+) -> plt.Axes:
+    """
+    Visualiza la luna de influencia del par (i, j) para un beta dado,
+    clasificando los puntos restantes según si caen dentro o fuera.
+
+    Parámetros
+    ----------
+    coords : np.ndarray de forma (n, 2)
+    i, j   : int — índices del par a visualizar
+    beta   : float > 0
+    labels : list de str, opcional
+    ax     : plt.Axes, opcional
+
+    Retorna
+    -------
+    plt.Axes
+    """
+    if ax is None:
+        _, ax = plt.subplots(figsize=(10, 10))
+
+    p1, p2 = coords[i], coords[j]
+    center1, center2, r = _lune_centers_and_radius(p1, p2, beta)
+    n = len(coords)
+
+    in_lune, out_lune = [], []
+    for k in range(n):
+        if k in (i, j):
+            continue
+        pk = coords[k]
+        inside = (np.linalg.norm(pk - center1) < r and
+                  np.linalg.norm(pk - center2) < r)
+        (in_lune if inside else out_lune).append((pk, k))
+
+    if out_lune:
+        pts = np.array([p for p, _ in out_lune])
+        ax.scatter(pts[:, 0], pts[:, 1], color="lightgray",
+                   label="Fuera de la luna", zorder=3)
+
+    if in_lune:
+        pts = np.array([p for p, _ in in_lune])
+        ax.scatter(pts[:, 0], pts[:, 1], color="steelblue",
+                   label="Dentro de la luna", zorder=4)
+
+    ax.scatter([p1[0], p2[0]], [p1[1], p2[1]],
+               color="crimson", zorder=5, label="Par evaluado")
+    ax.plot([p1[0], p2[0]], [p1[1], p2[1]], "k--", alpha=0.4)
+
+    name_i = labels[i] if labels else str(i)
+    name_j = labels[j] if labels else str(j)
+    offset = r * 0.03
+    ax.text(p1[0] + offset, p1[1] + offset, name_i, fontsize=9)
+    ax.text(p2[0] + offset, p2[1] + offset, name_j, fontsize=9)
+
+    ax.add_patch(Circle(center1, r, color="steelblue",
+                        fill=False, linestyle="--",
+                        label=f"Disco de {name_i}"))
+    ax.add_patch(Circle(center2, r, color="seagreen",
+                        fill=False, linestyle="--",
+                        label=f"Disco de {name_j}"))
+
+    ax.set_xlabel("Longitud")
+    ax.set_ylabel("Latitud")
+    ax.set_title(f"Luna β = {beta}  —  '{name_i}' y '{name_j}'")
+    ax.axis("equal")
+    ax.grid(True)
+    ax.legend(fontsize=8)
+    return ax
+
+
+def plot_skeleton(
+    coords: np.ndarray,
+    beta: float = 1.0,
+    labels: list | None = None,
+    node_color: str | list = "skyblue",
+    cmap=None,
+    colorbar_label: str | None = None,
+    ax: plt.Axes | None = None,
+    title: str | None = None,
+) -> tuple[plt.Axes, nx.Graph]:
+    """
+    Calcula y grafica el β-esqueleto.
+
+    Parámetros
+    ----------
+    coords         : np.ndarray de forma (n, 2)
+    beta           : float > 0
+    labels         : list de str, opcional
+    node_color     : str o list — color fijo o lista de valores numéricos
+    cmap           : colormap de matplotlib, opcional
+    colorbar_label : str, opcional — título de la barra de color
+    ax             : plt.Axes, opcional
+    title          : str, opcional
+
+    Retorna
+    -------
+    (plt.Axes, nx.Graph)
+    """
+    if ax is None:
+        _, ax = plt.subplots(figsize=(12, 12))
+
+    G = build_graph(coords, beta=beta, labels=labels)
+    pos = nx.get_node_attributes(G, "pos")
+    node_labels = nx.get_node_attributes(G, "label")
+
+    draw_kwargs = dict(
+        pos=pos, ax=ax, with_labels=False,
+        node_size=100, edge_color="gray",
+    )
+
+    if cmap is not None and isinstance(node_color, (list, np.ndarray)):
+        norm = plt.Normalize(vmin=min(node_color), vmax=max(node_color))
+        draw_kwargs.update(node_color=node_color, cmap=cmap)
+        sm = cm.ScalarMappable(cmap=cmap, norm=norm)
+        sm.set_array([])
+        cbar = plt.colorbar(sm, ax=ax, shrink=0.7)
+        if colorbar_label:
+            cbar.set_label(colorbar_label)
+    else:
+        draw_kwargs["node_color"] = node_color
+
+    nx.draw(G, **draw_kwargs)
+
+    if labels is not None:
+        texts = [ax.text(pos[i][0], pos[i][1], node_labels[i], fontsize=8)
+                 for i in G.nodes()]
+        adjust_text(
+            texts,
+            arrowprops=dict(arrowstyle="->", color="gray", lw=0.5),
+            expand_points=(1.2, 1.2),
+        )
+
+    ax.set_title(title or f"β-esqueleto (β = {beta})")
+    ax.axis("equal")
+    ax.grid(True)
+    return ax, G
+
+
+def plot_metric_bars(
+    metric_values: dict,
+    metric_name: str = "Métrica",
+    ax: plt.Axes | None = None,
+) -> plt.Axes:
+    """
+    Grafica un diagrama de barras de una métrica por nodo.
+
+    Parámetros
+    ----------
+    metric_values : dict {nodo: valor}
+    metric_name   : str — nombre de la métrica para etiquetas
+    ax            : plt.Axes, opcional
+
+    Retorna
+    -------
+    plt.Axes
+    """
+    if ax is None:
+        _, ax = plt.subplots(figsize=(20, 6))
+
+    nodes, values = zip(*sorted(metric_values.items()))
+    ax.bar(nodes, values)
+    ax.set_xticks(nodes)
+    ax.set_xlabel("Nodo")
+    ax.set_ylabel(metric_name)
+    ax.set_title(f"{metric_name} por nodo")
+    ax.grid(axis="y", linestyle="--", alpha=0.5)
+    return ax

ohtli-0.1.0.dist-info/METADATA

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: ohtli
+Version: 0.1.0
+Summary: Cálculo y visualización de β-esqueletos mediante fuerza bruta
+Author-email: Sara Luz Valenzuela Camacho <saraluz@gmail.com>
+Maintainer-email: Sara Luz Valenzuela Camacho <saraluz@gmail.com>
+Project-URL: Homepage, https://github.com/SaraLuzVC/Tesis-ITAM
+Project-URL: Documentation, https://github.com/SaraLuzVC/Tesis-ITAM/tree/main/ohtli/README.md
+Keywords: beta-skeleton,computational geometry,graph,archaeology
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Requires-Dist: networkx>=3.0
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: adjustText>=0.8
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+
+# beta-skeletons
+
+Librería para el cálculo y visualización de β-esqueletos mediante fuerza bruta.
+
+## Instalación
+
+```bash
+pip install beta-skeletons
+```
+
+O en modo desarrollo:
+
+```bash
+git clone https://github.com/tu-usuario/beta-skeletons.git
+cd beta-skeletons
+pip install -e ".[dev]"
+```
+
+## Uso básico
+
+```python
+import numpy as np
+from beta_skeletons import adjacency_matrix, build_graph, plot_skeleton
+from beta_skeletons import relative_asymmetry, control_value, plot_metric_bars
+
+coords = np.array([[0,0],[1,0],[2,0],[1,1]], dtype=float)
+names  = ["A", "B", "C", "D"]
+
+# Matriz de adyacencia
+adj = adjacency_matrix(coords, beta=1.0)
+
+# Grafo de NetworkX
+G = build_graph(coords, beta=2.0, labels=names)
+
+# Visualización
+ax, G = plot_skeleton(coords, beta=1.0, labels=names)
+
+# Métricas
+ra = relative_asymmetry(G)
+cv = control_value(G)
+plot_metric_bars(ra, metric_name="Asimetría relativa")
+```
+
+## Estructura del paquete
+
+```
+beta_skeletons/
+├── geometry.py   # cálculo de lunas y vecindades
+├── skeleton.py   # matriz de adyacencia y construcción del grafo
+├── metrics.py    # asimetría relativa y valor de control
+└── viz.py        # visualizaciones
+```
+
+## Referencia
+
+Kirkpatrick, D. G. y Radke, J. D. (1985).
+*A Framework for Computational Morphology*.
+Computational Geometry, pp. 217-248.

ohtli-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+ohtli/__init__.py,sha256=KCWpG4dzl4IKXgHTFzZGq3c3b2dfZvjDqsNPR765FF4,1083
+ohtli/geometry.py,sha256=AnW8UIjRGRUttXuG7Hnd36QlwvEYA_RaIgA9EMr73aE,2783
+ohtli/metrics.py,sha256=nAx83Ex3JZKqV4VQuFqw7K-p7r81AGznze9pTLOJIZ8,2051
+ohtli/skeleton.py,sha256=GgFwu5G-CSpLDfMpWqlPdOf5YFziLLF-KE5rYRP1zTI,2974
+ohtli/viz.py,sha256=_CyuyTu2CKcXvs5x3Gd8F-KDhm6glFAqnUlS2FLjbYM,6557
+ohtli-0.1.0.dist-info/METADATA,sha256=t9xw6ydDJcjrMnw5VmtP1KZiYqyoH7cParwo2J0ysTo,2299
+ohtli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ohtli-0.1.0.dist-info/top_level.txt,sha256=O1kypZQ6C0kIsDWRoxlECWCMn1DoqSr0WCjwKjtN5nw,6
+ohtli-0.1.0.dist-info/RECORD,,

ohtli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ohtli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ohtli