complexeva 0.1.5__tar.gz

complexeva-0.1.5/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.1
+Name: complexeva
+Version: 0.1.5
+Home-page: 
+Author: Don Yin
+Author-email: don_yin@outlook.com
+Description-Content-Type: text/markdown
+
+# overview
+computing fractal dimensions (and other complexity measures) and complexity measures in networks and matrices. The package includes:
+
+# some functions (thus far)
+- Box-counting fractal dimension calculation for networks and matrices
+- Higuchi fractal dimension implementation
+- Network-to-matrix and image-to-matrix conversions
+- Dummy fractal generators for testing

complexeva-0.1.5/README.md

@@ -0,0 +1,8 @@
+# overview
+computing fractal dimensions (and other complexity measures) and complexity measures in networks and matrices. The package includes:
+
+# some functions (thus far)
+- Box-counting fractal dimension calculation for networks and matrices
+- Higuchi fractal dimension implementation
+- Network-to-matrix and image-to-matrix conversions
+- Dummy fractal generators for testing

complexeva-0.1.5/complexeva/dummies/__init__.py

@@ -0,0 +1,4 @@
+from .matrix import DummyAdjacencyMatrix
+from .networks import WebFractalNetwork, SierpinskiFractal
+
+__all__ = ["DummyAdjacencyMatrix", "WebFractalNetwork", "SierpinskiFractal"]

complexeva-0.1.5/complexeva/dummies/matrix.py

@@ -0,0 +1,150 @@
+"""
+    Fractal adjacency matrix generation and analysis with varying degrees of complexity
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+
+class DummyAdjacencyMatrix:
+    def __init__(self, size, fractal_dimension):
+        """Initialize the FractalAdjacencyMatrix with a given size and fractal dimension.
+
+        Parameters:
+        size (int): The desired size of the adjacency matrix.
+        fractal_dimension (float): The target fractal dimension.
+        """
+        self.size, self.fractal_dimension = size, fractal_dimension
+
+    def generate_matrix(self, remove_upper_triangle=False, save_as=None):
+        """Generate the fractal adjacency matrix based on the specified fractal dimension.
+
+        Parameters:
+        fractal_dimension (float): The target fractal dimension.
+
+        Returns:
+        numpy.ndarray: The generated adjacency matrix.
+        """
+        max_m = min(self.size, 10)
+        m, pattern = self.calculate_m_and_pattern(self.fractal_dimension, max_m)
+        iterations = int(np.ceil(np.log(self.size) / np.log(m)))
+        actual_size = m**iterations
+        matrix = np.ones((actual_size, actual_size), dtype=bool)
+        self.apply_pattern(matrix, 0, 0, actual_size, m, pattern, iterations)
+
+        # Resize matrix if needed
+        if actual_size != self.size:
+            if actual_size > self.size:
+                matrix = matrix[: self.size, : self.size]
+            else:
+                pad_size = self.size - actual_size
+                matrix = np.pad(matrix, ((0, pad_size), (0, pad_size)), mode="constant", constant_values=False)
+
+        matrix = self.post_processing_matrix(matrix, remove_upper_triangle)
+
+        if save_as:
+            save_as = save_as if save_as.endswith(".png") else f"{save_as}.png"
+            plt.figure(figsize=(8, 8))
+            plt.imshow(matrix, cmap="binary", interpolation="nearest")
+            plt.title("Dummy Fractal Adjacency Matrix / FD ~ {:.2f}".format(self.fractal_dimension))
+            plt.axis("off")
+            plt.tight_layout()
+            plt.savefig(save_as, dpi=420, bbox_inches="tight")
+            plt.close()
+
+        return matrix
+
+    @staticmethod
+    def post_processing_matrix(matrix, remove_upper_triangle=False):
+        matrix = matrix.astype(int)
+        if remove_upper_triangle:
+            matrix = np.tril(matrix)
+        return matrix
+
+    def calculate_m_and_pattern(self, target_dimension, max_scaling_factor=10):
+        """Calculate the scaling factor 'm' and the base pattern for the fractal.
+
+        Parameters:
+        target_dimension (float): The target fractal dimension.
+        max_m (int): The maximum value of 'm' to consider (default is 10).
+
+        Returns:
+        tuple: A tuple containing 'm' and the 'pattern' numpy.ndarray.
+        """
+        best_dimension_diff = float("inf")
+        best_scaling_factor = None
+        best_pattern = None
+
+        for scaling_factor in range(2, max_scaling_factor + 1):
+            total_cells = scaling_factor * scaling_factor
+            # Iterate over possible numbers of cells to remove
+            for removed_cells in range(1, total_cells):
+                remaining_cells = total_cells - removed_cells
+                fractal_dim = np.log(remaining_cells) / np.log(scaling_factor)
+                dimension_diff = abs(fractal_dim - target_dimension)
+
+                if dimension_diff < best_dimension_diff:
+                    best_dimension_diff = dimension_diff
+                    best_scaling_factor = scaling_factor
+                    # Create the base pattern
+                    pattern = np.ones((scaling_factor, scaling_factor), dtype=bool)
+                    # Determine which cells to remove, starting from the center
+                    indices = [(i, j) for i in range(scaling_factor) for j in range(scaling_factor)]
+                    center = scaling_factor // 2
+                    indices_sorted = sorted(
+                        indices,
+                        key=lambda x: (abs(x[0] - center) + abs(x[1] - center), x[0], x[1]),
+                    )
+                    for i, j in indices_sorted[:removed_cells]:
+                        pattern[i, j] = False
+                    best_pattern = pattern.copy()
+
+                if best_dimension_diff == 0:
+                    return best_scaling_factor, best_pattern
+
+        return best_scaling_factor, best_pattern
+
+    def apply_pattern(self, matrix, x_start, y_start, size, m, pattern, iterations_left):
+        """Recursively apply the fractal pattern to the matrix.
+
+        Parameters:
+        matrix (numpy.ndarray): The matrix to modify.
+        x_start (int): The starting x-coordinate in the matrix.
+        y_start (int): The starting y-coordinate in the matrix.
+        size (int): The size of the current square in the matrix.
+        m (int): The scaling factor.
+        pattern (numpy.ndarray): The base pattern to apply.
+        iterations_left (int): The number of iterations left to apply.
+        """
+        if iterations_left == 0:
+            return
+        step = size // m
+        for i, j in np.ndindex(m, m):
+            x_slice = slice(x_start + j * step, x_start + (j + 1) * step)
+            y_slice = slice(y_start + i * step, y_start + (i + 1) * step)
+            if not pattern[i, j]:
+                matrix[y_slice, x_slice] = False
+            else:
+                self.apply_pattern(
+                    matrix,
+                    x_start + j * step,
+                    y_start + i * step,
+                    step,
+                    m,
+                    pattern,
+                    iterations_left - 1,
+                )
+
+
+if __name__ == "__main__":
+    size = 256
+    fractal_dimensions = np.linspace(1.0, 2.0, 10)
+
+    for idx, dimension in enumerate(fractal_dimensions):
+        generator = DummyAdjacencyMatrix(size, dimension)
+        plt.figure(figsize=(6, 6))
+        plt.title(f"Fractal Dimension ~ {dimension:.2f}", pad=20)
+        plt.imshow(generator.matrix, cmap="binary", interpolation="nearest")
+        plt.axis("off")
+        plt.savefig(f"fractal_{idx}.png")
+        plt.close()

complexeva-0.1.5/complexeva/dummies/networks.py

@@ -0,0 +1,111 @@
+#!/Users/donyin/miniconda3/envs/rotation-1/bin/python
+
+"""
+all the networkx class dummy implementations
+"""
+
+import numpy as np
+import networkx as nx
+
+
+class WebFractalNetwork:
+    """
+    Generates a pseudo-fractal network using an iterative method.
+
+    Usage:
+    web_fractal = WebFractalNetwork(complexity=3)
+    network = web_fractal.network
+    """
+
+    def __init__(self, complexity=3):
+        self.complexity = complexity
+        self.network = self._generate_network()
+        self.diameter = nx.diameter(self.network)
+
+    def _generate_network(self):
+        """
+        Generates the pseudo-fractal network.
+        """
+        G = nx.Graph()
+        G.add_edges_from([(0, 1), (1, 2), (2, 0)])
+        for _ in range(self.complexity):
+            G = self._fractal_step(G)
+        return G
+
+    def _fractal_step(self, G):
+        """
+        Performs one iteration of the fractal construction.
+        """
+        new_edges = []
+        max_node = max(G.nodes())
+        for u, v in G.edges():
+            new_node = max_node + 1
+            max_node += 1
+            new_edges.extend([(new_node, u), (new_node, v)])
+        G.add_edges_from(new_edges)
+        return G
+
+
+class SierpinskiFractal:
+    """
+    Generates a Sierpinski gasket fractal network.
+
+    Usage:
+    sierpinski = SierpinskiFractal(recursion_depth=3)
+    network = sierpinski.network
+    """
+
+    def __init__(self, recursion_depth=3):
+        self.recursion_depth = recursion_depth
+        self.points = {}
+        self.edges = set()
+        self.point_index = 0
+        self.network = self._generate_network()
+
+    def _generate_network(self):
+        """
+        Generates the Sierpinski gasket fractal network.
+        """
+        vertices = [(0, 0), (0.5, np.sqrt(3) / 2), (1, 0)]
+        self._sierpinski_recursive(vertices, self.recursion_depth)
+        return self._build_graph()
+
+    def _sierpinski_recursive(self, vertices, depth):
+        """
+        Recursively generates the Sierpinski gasket fractal.
+        """
+
+        def add_triangle(v1, v2, v3, current_depth):
+            if current_depth == 0:
+                for v in [v1, v2, v3]:
+                    if v not in self.points:
+                        self.points[v] = self.point_index
+                        self.point_index += 1
+                i1, i2, i3 = self.points[v1], self.points[v2], self.points[v3]
+                self.edges.update([(i1, i2), (i2, i3), (i3, i1)])
+            else:
+                m1 = ((v1[0] + v2[0]) / 2, (v1[1] + v2[1]) / 2)
+                m2 = ((v2[0] + v3[0]) / 2, (v2[1] + v3[1]) / 2)
+                m3 = ((v3[0] + v1[0]) / 2, (v3[1] + v1[1]) / 2)
+                add_triangle(v1, m1, m3, current_depth - 1)
+                add_triangle(m1, v2, m2, current_depth - 1)
+                add_triangle(m3, m2, v3, current_depth - 1)
+
+        add_triangle(vertices[0], vertices[1], vertices[2], depth)
+
+    def _build_graph(self):
+        """
+        Builds the NetworkX graph from the generated points and edges.
+        """
+        G = nx.Graph()
+        for coord, idx in self.points.items():
+            G.add_node(idx, pos=coord)
+        G.add_edges_from(self.edges)
+        return G
+
+
+if __name__ == "__main__":
+    network = SierpinskiFractal(recursion_depth=7)
+    # network = WebFractalNetwork(complexity=4)
+    # handler = FractalHandlerNetworkX(network.network)
+    # handler.compute_fractal_dimensions(box_sizes="auto", iterations=10)

complexeva-0.1.5/complexeva/measures/__init__.py

@@ -0,0 +1,5 @@
+from .higuchi import hfd_matlab_equivalent, hfd_pyeeg
+from .cbb_matrix import FractalHandlerMatrix
+from .cbb_networkx import FractalHandlerNetworkX
+
+__all__ = ["hfd_matlab_equivalent", "hfd_pyeeg", "FractalHandlerMatrix", "FractalHandlerNetworkX"]

complexeva-0.1.5/complexeva/measures/cbb_matrix.py

@@ -0,0 +1,134 @@
+import numpy as np
+import matplotlib.pyplot as plt
+from matplotlib import animation
+
+
+class FractalHandlerMatrix:
+    """
+    Handles the fractal dimension calculation of a binary matrix using an improved Compact Box-Burning algorithm.
+    """
+
+    def __init__(self, matrix: np.ndarray):
+        self.matrix = matrix
+
+    def compute_fractal_dimension(self, save_plot_as=None, save_animated_as=None):
+        """
+        Calculate the fractal dimension of the matrix using the improved Compact Box-Burning algorithm.
+
+        Parameters:
+            save_plot_as (str, optional): Path to save the static plot showing fractal dimension calculation
+            save_animated_as (str, optional): Path to save the animated GIF showing box counting process
+
+        Returns:
+            float: The fractal dimension of the matrix.
+        """
+        assert np.all((self.matrix == 0) | (self.matrix == 1)), "> warning: Matrix should be binary (0s and 1s only)"
+        binary_matrix = self.matrix.astype(np.uint8)
+        min_dim = min(binary_matrix.shape)
+        max_scale = 2 ** int(np.floor(np.log2(min_dim)))
+
+        num_scales = int(np.floor(np.log2(max_scale))) * 10
+        scales = np.unique(np.floor(np.logspace(0, np.log2(max_scale), num=num_scales, base=2))).astype(int)
+        scales = scales[scales >= 1]
+
+        box_counts = []
+        padded_matrices = []
+
+        # Animation setup if needed
+        if save_animated_as:
+            fig, ax = plt.subplots(figsize=(8, 8))
+
+        for scale in scales:
+            padded_size = (
+                int(np.ceil(binary_matrix.shape[0] / scale)) * scale,
+                int(np.ceil(binary_matrix.shape[1] / scale)) * scale,
+            )
+            padded_matrix = np.zeros(padded_size, dtype=np.uint8)
+            padded_matrix[: binary_matrix.shape[0], : binary_matrix.shape[1]] = binary_matrix
+
+            if save_animated_as:
+                padded_matrices.append((padded_matrix, scale))
+
+            reshaped = padded_matrix.reshape(padded_size[0] // scale, scale, padded_size[1] // scale, scale)
+            summed = reshaped.sum(axis=(1, 3))
+            occupied_boxes = np.count_nonzero(summed)
+            box_counts.append(occupied_boxes)
+
+        # calculate fractal dimension
+        scales = np.array(scales)
+        box_counts = np.array(box_counts)
+        nonzero = box_counts > 0
+        scales = scales[nonzero]
+        box_counts = box_counts[nonzero]
+
+        log_scales = np.log(1 / scales)
+        log_box_counts = np.log(box_counts)
+
+        coeffs = np.polyfit(log_scales, log_box_counts, 1)
+        fractal_dimension = coeffs[0]
+
+        # save static plot if requested
+        if save_plot_as:
+            save_plot_as = save_plot_as if save_plot_as.endswith(".png") else save_plot_as + ".png"
+            plt.figure(figsize=(8, 6))
+            plt.plot(log_scales, log_box_counts, "o-", label="Data")
+            plt.plot(
+                log_scales,
+                np.polyval(coeffs, log_scales),
+                "r--",
+                label=f"Fit (D = {fractal_dimension:.4f})",
+            )
+            plt.xlabel("log(1/ε)")
+            plt.ylabel("log(N(ε))")
+            plt.title("Fractal Dimension via Compact Box-Burning")
+            plt.legend()
+            plt.grid(True)
+            plt.tight_layout()
+            plt.savefig(save_plot_as, dpi=420, bbox_inches="tight")
+            plt.close()
+
+        # Create and save animation if requested
+        if save_animated_as:
+
+            def init():
+                ax.imshow(binary_matrix, cmap="binary", interpolation="nearest")
+                ax.axis("off")
+                return []
+
+            def update(frame):
+                padded_matrix, scale = padded_matrices[frame]
+                ax.clear()
+                ax.imshow(padded_matrix, cmap="binary", interpolation="nearest")
+                ax.set_title(f"Scale: {scale} pixels, Boxes: {box_counts[frame]}")
+                ax.axis("off")
+
+                # Overlay red boxes on occupied regions
+                for y in range(0, padded_matrix.shape[0], scale):
+                    for x in range(0, padded_matrix.shape[1], scale):
+                        if np.any(padded_matrix[y : y + scale, x : x + scale]):
+                            rect = plt.Rectangle(
+                                (x - 0.5, y - 0.5),
+                                scale,
+                                scale,
+                                edgecolor="red",
+                                facecolor="none",
+                                lw=1,
+                            )
+                            ax.add_patch(rect)
+                return []
+
+            ani = animation.FuncAnimation(
+                fig,
+                update,
+                frames=len(scales),
+                init_func=init,
+                blit=False,
+                repeat=False,
+            )
+
+            if not save_animated_as.endswith((".png", ".gif")):
+                save_animated_as += ".gif"
+            ani.save(save_animated_as.replace(".png", ".gif"), writer="pillow", fps=2)
+            plt.close(fig)
+
+        return fractal_dimension

complexeva-0.1.5/complexeva/measures/cbb_networkx.py

@@ -0,0 +1,288 @@
+#!/Users/donyin/miniconda3/bin/python
+import random
+from PIL import Image
+import numpy as np
+import networkx as nx
+from tqdm import tqdm
+from scipy import stats
+import matplotlib.pyplot as plt
+from networkx.exception import NetworkXError
+import matplotlib.animation as animation
+
+
+"""
+reference:
+- https://github.com/PeterTKovacs/boxes/blob/main/boxes/cbb.py
+"""
+
+
+class FractalHandlerNetworkX:
+    """
+    Handles fractal analysis of NetworkX graphs using box-covering method.
+    """
+
+    def __init__(self, network: nx.Graph):
+        self.network = network
+
+    def auto_pick_box_sizes(self):
+        diameter = nx.diameter(self.network) if nx.is_connected(self.network) else 1
+        min_size = max(1, diameter // 21)
+        max_size = diameter
+        return np.logspace(np.log10(min_size), np.log10(max_size), num=12, dtype=int)
+
+    def compute_fractal_dimensions(self, box_sizes="auto", iterations=10, save_plot_as=None, save_animated_as=None):
+        box_sizes = self.auto_pick_box_sizes() if box_sizes == "auto" else box_sizes
+        network_image, box_counts = self.plot_network(), []
+
+        # If animation is requested, set up storage for animation frames
+        if save_animated_as:
+            animation_data = []
+            pos = nx.spring_layout(self.network, dim=3)  # 3D layout
+
+            # Create a color mapping based on z-coordinates
+            z_coords = np.array([pos[node][2] for node in self.network.nodes()])
+            z_min, z_max = z_coords.min(), z_coords.max()
+            node_colors = {}
+            for node in self.network.nodes():
+                z = pos[node][2]
+                # Normalize z to [0,1] range for color mapping
+                color_val = (z - z_min) / (z_max - z_min) if z_max != z_min else 0
+                node_colors[node] = plt.cm.rainbow(color_val)
+
+        for max_distance in tqdm(box_sizes, desc="Box sizes"):
+            num_boxes_list = []
+            boxes_for_animation = []
+            for _ in tqdm(range(iterations), desc=f"Networks for size {max_distance}", leave=False):
+                boxes = self.random_box_covering(max_distance)
+                num_boxes_list.append(len(boxes))
+                if save_animated_as:
+                    boxes_for_animation.append(boxes)
+            avg_num_boxes = sum(num_boxes_list) / iterations
+            box_counts.append(avg_num_boxes)
+
+            if save_animated_as:
+                # For animation, store the boxes from the first iteration
+                animation_data.append(
+                    {
+                        "boxes": boxes_for_animation[0],
+                        "max_distance": max_distance,
+                        "num_boxes": num_boxes_list[0],
+                    }
+                )
+
+        log_box_sizes, log_counts = np.log(box_sizes), np.log(box_counts)
+
+        try:
+            slope, intercept, r_value, p_value, std_err = stats.linregress(log_box_sizes, log_counts)
+        except ValueError:
+            slope, intercept, r_value = 0, 0, 0
+        fractal_dimension = -slope
+
+        if save_plot_as:
+            save_plot_as = save_plot_as if save_plot_as.endswith(".png") else f"{save_plot_as}.png"
+            fig, ax = plt.subplots(figsize=(10, 6))
+            ax.scatter(log_box_sizes, log_counts, color="blue", label="Data")
+            ax.plot(
+                log_box_sizes,
+                slope * log_box_sizes + intercept,
+                color="red",
+                label=f"Fit (D={fractal_dimension:.2f})",
+                linestyle="-",
+            )
+            ax.set_xlabel("log(Box Size)", fontsize=21)
+            ax.set_ylabel("log(Number of Boxes)", fontsize=21)
+            ax.set_title("Fractal Dimension Regression", fontsize=21)
+            ax.legend(fontsize=21)
+            ax.grid(True)
+            ax.tick_params(axis="both", which="major", labelsize=21)
+            fig.canvas.draw()
+            plot_image = np.array(fig.canvas.renderer.buffer_rgba())
+            network_height, network_width = network_image.shape[:2]
+            plot_height, plot_width = plot_image.shape[:2]
+            aspect_ratio = network_width / network_height
+            new_network_height = plot_height
+            new_network_width = int(new_network_height * aspect_ratio)
+            resized_network_image = np.array(Image.fromarray(network_image).resize((new_network_width, new_network_height)))
+            resized_network_image = resized_network_image[:, :, :3]
+            plot_image = plot_image[:, :, :3]
+            combined_image = np.hstack((resized_network_image, plot_image))
+            plt.figure(
+                figsize=(
+                    combined_image.shape[1] / 100,
+                    combined_image.shape[0] / 100,
+                )
+            )
+            plt.imshow(combined_image)
+            plt.axis("off")
+            plt.tight_layout()
+            plt.savefig(save_plot_as, dpi=420, bbox_inches="tight")
+            plt.close()
+
+        # Create and save animation if requested
+        if save_animated_as:
+            fig = plt.figure(figsize=(15, 8))  # Wider figure to accommodate legend
+            gs = plt.GridSpec(1, 2, width_ratios=[2, 1])  # 2:1 ratio for plot and legend
+            ax = fig.add_subplot(gs[0], projection="3d")
+            legend_ax = fig.add_subplot(gs[1])  # Create legend subplot once
+            legend_ax.axis("off")
+            legend_ax.spines["top"].set_visible(False)
+
+            def update(frame):
+                ax.clear()
+                legend_ax.clear()  # Clear previous legend
+
+                data = animation_data[frame]
+                boxes = data["boxes"]
+                max_distance = data["max_distance"]
+                num_boxes = data["num_boxes"]
+
+                # Draw network and boxes in 3D subplot
+                edge_list = list(self.network.edges())
+
+                # Assign box colors based on average z-coordinate of nodes in each box
+                box_colors = []
+                for box in boxes:
+                    box_nodes = list(box)
+                    box_colors.append(np.mean([node_colors[node] for node in box_nodes], axis=0))
+
+                # Create a mapping of nodes to their box colors
+                node_to_color = {}
+                for box, color in zip(boxes, box_colors):
+                    for node in box:
+                        node_to_color[node] = color
+
+                # Draw edges with box colors
+                for edge in edge_list:
+                    start = pos[edge[0]]
+                    end = pos[edge[1]]
+                    # Use color of both nodes for edge
+                    start_color = node_to_color.get(edge[0], "gray")
+                    end_color = node_to_color.get(edge[1], "gray")
+                    edge_color = start_color if np.array_equal(start_color, end_color) else "gray"
+
+                    mid_point = (start + end) / 2
+                    offset = np.random.normal(0, 0.05, 3)
+                    control_point = mid_point + offset
+                    t = np.linspace(0, 1, 20)
+                    curve = np.array([(1 - t) ** 2 * start + 2 * (1 - t) * t * control_point + t**2 * end for t in t])
+                    ax.plot3D(curve[:, 0], curve[:, 1], curve[:, 2], c=edge_color, alpha=0.7, linewidth=1.5)
+
+                # Draw boxes and create legend elements
+                legend_elements = []
+                for box_idx, (box, color) in enumerate(zip(boxes, box_colors)):
+                    box_nodes = list(box)
+                    box_pos = np.array([pos[node] for node in box_nodes])
+                    scatter = ax.scatter(
+                        box_pos[:, 0], box_pos[:, 1], box_pos[:, 2], c=[color], s=150, alpha=0.8, edgecolor="white"
+                    )
+                    legend_elements.append((scatter, f"Box {box_idx+1}"))
+
+                # Set 3D plot properties
+                ax.set_title(f"Step {frame+1}/{len(animation_data)}\nBox Size = {max_distance}\nBoxes Required: {num_boxes}")
+                ax.set_xlabel("X")
+                ax.set_ylabel("Y")
+                ax.set_zlabel("Z")
+
+                # Calculate optimal number of columns based on number of boxes
+                n_boxes = len(boxes)
+                n_cols = min(4, n_boxes)  # Max 4 columns for more spacing
+                n_rows = (n_boxes + n_cols - 1) // n_cols  # Ceiling division
+
+                # Create legend with more spacing
+                legend = legend_ax.legend(
+                    *zip(*legend_elements),
+                    loc="center",
+                    ncol=n_cols,
+                    bbox_to_anchor=(0.5, 0.5),
+                    borderaxespad=1,
+                    labelspacing=1.5,  # Increase vertical spacing between legend entries
+                    handletextpad=1.2,  # Increase spacing between marker and text
+                    title="Box Groups",
+                    frameon=True,  # Add frame around legend
+                    fancybox=True,  # Round corners
+                    shadow=True,  # Add shadow
+                )
+                legend.get_title().set_fontsize(14)
+                for text in legend.get_texts():
+                    text.set_fontsize(12)
+
+            ax.set_box_aspect([1, 1, 1])
+            ax.view_init(elev=20, azim=45)
+            ax.dist = 8
+
+            ani = animation.FuncAnimation(fig, update, frames=len(animation_data), interval=2000, repeat=True)
+
+            save_animated_as = save_animated_as if save_animated_as.endswith((".png", ".gif")) else save_animated_as + ".gif"
+            ani.save(save_animated_as.replace(".png", ".gif"), writer="pillow", fps=0.5)
+            plt.close(fig)
+
+        return fractal_dimension, r_value**2, log_box_sizes, log_counts
+
+    # ---- functional helpers ----
+    def random_box_covering(self, max_distance: int):
+        """
+        [NOTE] This implementation handles disconnected graphs by processing each connected component separately.
+
+        This function implements the random box covering algorithm to estimate
+        the boxes needed to cover a network at a given maximum distance.
+
+        Args:
+            max_distance (int): The maximum distance allowed within each box, in number of hops.
+
+        Returns:
+            List[Set]: A list of sets, each containing the nodes in a box.
+        """
+        boxes = []
+        for component in nx.connected_components(self.network):
+            subgraph = self.network.subgraph(component)
+            uncovered_nodes = set(subgraph.nodes())
+            while uncovered_nodes:
+                p = random.choice(list(uncovered_nodes))
+                distances = nx.single_source_shortest_path_length(subgraph, p)
+                box_nodes = set(node for node, dist in distances.items() if dist <= max_distance).intersection(uncovered_nodes)
+                boxes.append(box_nodes)
+                uncovered_nodes -= box_nodes
+        return boxes
+
+    def plot_network(self):
+        pos = nx.get_node_attributes(self.network, "pos")
+        fig = plt.figure(figsize=(10, 8))
+        ax = fig.add_subplot(111, projection="3d")
+
+        if pos:
+            # Use provided positions if they exist
+            pos_3d = {node: (x, y, 0) for node, (x, y) in pos.items()}  # Convert 2D to 3D
+        else:
+            # Generate 3D spring layout
+            pos_3d = nx.spring_layout(self.network, dim=3)
+
+        # Draw edges with curves
+        for edge in self.network.edges():
+            start = np.array(pos_3d[edge[0]])
+            end = np.array(pos_3d[edge[1]])
+            ax.plot([start[0], end[0]], [start[1], end[1]], [start[2], end[2]], "gray", alpha=0.5)
+
+        # Draw nodes
+        node_pos = np.array([pos_3d[node] for node in self.network.nodes()])
+        ax.scatter(node_pos[:, 0], node_pos[:, 1], node_pos[:, 2], c="lightblue", s=30)
+
+        ax.set_title("3D Network Visualization")
+        ax.set_xlabel("X")
+        ax.set_ylabel("Y")
+        ax.set_zlabel("Z")
+
+        plt.tight_layout()
+        fig.canvas.draw()
+        image = np.array(fig.canvas.renderer.buffer_rgba())
+        plt.close(fig)
+        return image
+
+
+if __name__ == "__main__":
+    from src.dummies.networks import WebFractalNetwork, SierpinskiFractal
+
+    network = SierpinskiFractal(recursion_depth=6)
+    network = WebFractalNetwork(complexity=4)
+
+    handler = FractalHandlerNetworkX(network.network)
+    handler.compute_fractal_dimensions(box_sizes=np.linspace(1, 10, 20), iterations=10)

complexeva-0.1.5/complexeva/measures/co_activation.py

@@ -0,0 +1,100 @@
+#!/Users/donyin/miniconda3/envs/rotation-1/bin/python
+
+"""
+- now we have two 1d series as signals make dummy data using numpy
+- use either a sliding window or regression method to produce a new signal that represents the co-activation between the two signals
+- in the sliding_window method, the window_size parameter is used to determine the size of the window used to calculate the co-activation
+- it moves one step at a time and calculates the correlation between the two signals in the window
+- in the regression method, the two signals are used as independent and dependent variables in a linear regression model
+- the resulting signal is the predicted dependent variable
+- if we use the sliding_window method, the window_size parameter must be an integer greater than 0
+- if we use the regression method, we must plot the two signal and the resulting signal
+"""
+
+import numpy as np
+from sklearn.linear_model import LinearRegression
+import matplotlib.pyplot as plt
+
+
+def get_co_activation(
+    signal_1: np.ndarray, signal_2: np.ndarray, method: str, window_size: int = None, save_plot_as=None
+) -> np.ndarray:
+    """
+    Get a measure of co-activation between two 1D signals.
+
+    Args:
+        signal_1: First 1D time series signal
+        signal_2: Second 1D time series signal
+        method: Either 'sliding_window' or 'regression'
+        window_size: Size of the window for 'sliding_window' method (must be an integer greater than 0)
+
+    Returns:
+        np.ndarray: A new signal representing the co-activation between the two signals
+    """
+    match method:
+        case "sliding_window":
+            if window_size is None or window_size <= 0:
+                raise ValueError("window_size must be an integer greater than 0 for sliding_window method")
+            correlations = []
+            num_windows = len(signal_1) - window_size + 1
+            for i in range(num_windows):
+                window_signal_1 = signal_1[i : i + window_size]
+                window_signal_2 = signal_2[i : i + window_size]
+                corr = np.corrcoef(window_signal_1, window_signal_2)[0, 1]
+                correlations.append(corr)
+
+            # Plot signals and correlations
+            correlations = np.array(correlations)
+            if save_plot_as:
+                plt.figure(figsize=(10, 5))
+                plt.plot(signal_1, label="Signal 1", alpha=0.7)
+                plt.plot(signal_2, label="Signal 2", alpha=0.7)
+                plt.plot(
+                    np.arange(window_size // 2, len(correlations) + window_size // 2),
+                    correlations,
+                    label="Sliding Window Correlation",
+                    linestyle="--",
+                )
+                plt.legend()
+                plt.title(f"Sliding Window Method Co-Activation (window size={window_size})")
+                plt.savefig(save_plot_as, dpi=320)
+                plt.close()
+
+            return correlations
+
+        case "regression":
+            # Reshape signals for regression
+            X = signal_1.reshape(-1, 1)
+            y = signal_2
+
+            # Fit linear regression
+            model = LinearRegression()
+            model.fit(X, y)
+
+            # Predict y
+            y_pred = model.predict(X)
+
+            # Plot signals
+            if save_plot_as:
+                plt.figure(figsize=(10, 5))
+                plt.plot(signal_1, label="Signal 1 (IV)")
+                plt.plot(signal_2, label="Signal 2 (DV)")
+                plt.plot(y_pred, label="Predicted DV", linestyle="--")
+                plt.legend()
+                plt.title("Regression Method Co-Activation")
+                plt.savefig(save_plot_as, dpi=320)
+                plt.close()
+
+            return y_pred
+
+        case _:
+            raise ValueError("method must be 'sliding_window' or 'regression'")
+
+
+if __name__ == "__main__":
+    t = np.linspace(0, 10, 1000)
+    signal1 = np.sin(2 * np.pi * 0.5 * t) + 0.2 * np.random.randn(1000)
+    signal2 = 0.8 * np.sin(2 * np.pi * 0.5 * t + np.pi / 4) + 0.2 * np.random.randn(1000)
+
+    get_co_activation(signal1, signal2, method="sliding_window", window_size=32, save_plot_as="coactivation_sliding_window.png")
+    get_co_activation(signal1, signal2, method="regression", save_plot_as="coactivation_regression.png")

complexeva-0.1.5/complexeva/measures/higuchi.py

@@ -0,0 +1,91 @@
+#!/Users/donyin/miniconda3/envs/rotation-1/bin/python
+
+
+import numpy
+from scipy.fft import fft, ifft
+import matplotlib.pyplot as plt
+from donware import inspect_package
+from numba import njit
+
+
+def hfd_matlab_equivalent(data, k_max):
+    """
+    [translated from MATLAB code]
+
+    [output]
+    - produce values between 1 and 2
+    """
+    N = len(data)
+    L = numpy.zeros(k_max)
+    x = numpy.zeros(k_max)
+    y = numpy.zeros(k_max)
+
+    for k in range(1, k_max + 1):
+        Lk = numpy.zeros(k)
+        for m in range(1, k + 1):
+            norm_factor = (N - 1) / (numpy.round((N - m) / k) * k)
+            X = numpy.sum(numpy.abs(numpy.diff(data[m - 1 :: k])))
+            Lk[m - 1] = X * norm_factor / k
+
+        y[k - 1] = numpy.log(numpy.sum(Lk) / k)
+        x[k - 1] = numpy.log(1 / k)
+
+    D = numpy.polyfit(x, y, 1)
+    HFD = D[0]
+
+    return HFD
+
+
+@njit
+def compute_L_x(X, k_max):
+    N = len(X)
+    L = numpy.zeros(k_max)
+    x = numpy.zeros(k_max)
+    for k in range(1, k_max + 1):
+        Lk = numpy.zeros(k)
+        for m in range(k):
+            Lmk = 0.0
+            n_max = (N - m) // k
+            for i in range(1, n_max):
+                Lmk += abs(X[m + i * k] - X[m + (i - 1) * k])
+            Lmk *= (N - 1) / (n_max * k)
+            Lk[m] = Lmk
+        L[k - 1] = numpy.log(Lk.mean())
+        x[k - 1] = numpy.log(1.0 / k)
+    return x, L
+
+
+def hfd_pyeeg(X, k_max):
+    x, L = compute_L_x(X, k_max)
+    A = numpy.column_stack((x, numpy.ones_like(x)))
+    beta, _, _, _ = numpy.linalg.lstsq(A, L, rcond=None)
+    return beta[0]
+
+
+def _hfd_pyeeg(X, k_max):
+    """
+    [from PyEEG package]
+    Higuchi Fractal Dimension of a time series X. kmax is an HFD parameter
+
+    [output]
+    - for some reasons produce values between 0 and 1
+
+    [modifications]
+    - kmax should be inclusive, Kmax + 1
+    """
+    L = []
+    x = []
+    N = len(X)
+    for k in range(1, k_max + 1):
+        Lk = []
+        for m in range(0, k):
+            Lmk = 0
+            for i in range(1, int(numpy.floor((N - m) / k))):
+                Lmk += abs(X[m + i * k] - X[m + i * k - k])
+            Lmk = Lmk * (N - 1) / numpy.floor((N - m) / float(k)) / k
+            Lk.append(Lmk)
+        L.append(numpy.log(numpy.mean(Lk)))
+        x.append([numpy.log(float(1) / k), 1])
+
+    (p, _, _, _) = numpy.linalg.lstsq(x, L, rcond=None)
+    return p[0]

complexeva-0.1.5/complexeva/measures/validate.py

@@ -0,0 +1,96 @@
+#!/Users/donyin/miniconda3/envs/rotation-1/bin/python
+
+
+import numpy
+from scipy.fft import fft, ifft
+import matplotlib.pyplot as plt
+from donware import inspect_package
+from complexeva.measures.higuchi import hfd_pyeeg, hfd_matlab_equivalent
+
+
+class HiguchiMethodValidate:
+    def __init__(self, funcs, k_max: int, timeseries_len=1000, num_hurst=200):
+        self.funcs, self.k_max, self.num_hurst, self.timeseries_len = funcs, k_max, num_hurst, timeseries_len
+
+    def fbm(self, hurst):
+        """
+        Generate fractional Brownian motion (fBm) time series.
+
+        This method uses the spectral synthesis method to generate a fBm time series
+        with a specified Hurst exponent.
+
+        Parameters:
+        -----------
+        hurst : float
+            The Hurst exponent, a value between 0 and 1 that characterizes
+            the fractal properties of the time series.
+
+        Returns:
+        --------
+        numpy.ndarray
+            A 1D array representing the generated fBm time series.
+
+        Notes:
+        ------
+        - The length of the generated time series is determined by self.timeseries_len.
+        - This method uses the Fourier filtering method to generate fBm.
+        - The first frequency component is set to a small non-zero value (1e-6) to avoid division by zero.
+        """
+
+        n = self.timeseries_len
+        f = numpy.fft.fftfreq(n)
+        f[0] = 1e-6  # avoid division by zero
+        psd = numpy.abs(f) ** (-2 * hurst - 1)
+        gaussian = numpy.random.randn(n) + 1j * numpy.random.randn(n)
+        fBm = numpy.fft.ifft(gaussian * numpy.sqrt(psd)).real
+        return fBm
+
+    def plot_hfd_vs_hurst(self):
+        hurst_exponent = numpy.linspace(0.001, 1, self.num_hurst)
+        fBm_series = [self.fbm(h) for h in hurst_exponent]
+        expected_hfd = [2 - h for h in hurst_exponent]
+        hfd_results = []
+
+        for func in self.funcs:
+            hfd_results.append([func(series, self.k_max) for series in fBm_series])
+
+        # ---- plotting ----
+        fig, axs = plt.subplots(3, 1, figsize=(9, 10))
+
+        axs[0].plot(fBm_series[0])
+        axs[0].set_title(f"fBm series with H = {hurst_exponent[0]:.3f}", fontsize=21)
+        mid_index = len(hurst_exponent) // 2
+        axs[1].plot(fBm_series[mid_index])
+        axs[1].set_title(f"fBm series with H = {hurst_exponent[mid_index]:.3f}", fontsize=21)
+        axs[2].plot(fBm_series[-1])
+        axs[2].set_title(f"fBm series with H = {hurst_exponent[-1]:.3f}", fontsize=21)
+
+        for ax in axs:
+            ax.set_xlabel("Time", fontsize=21)
+            ax.set_ylabel("Value", fontsize=21)
+            ax.tick_params(axis="both", which="major", labelsize=12)
+            ax.grid(True)
+
+        plt.tight_layout()
+        plt.savefig("fBm_series_examples.png", dpi=320, bbox_inches="tight")
+
+        # Original HFD vs Hurst plot
+        plt.figure(figsize=(9, 7))
+        plt.plot(hurst_exponent, expected_hfd, label="Expected HFD")
+        for i, func in enumerate(self.funcs):
+            plt.plot(hurst_exponent, hfd_results[i], label=f"HFD ({func.__name__})")
+        plt.xlabel("Hurst Exponent (H)", fontsize=14)
+        plt.ylabel("Higuchi Fractal Dimension (HFD)", fontsize=14)
+        plt.title(f"HFD vs Hurst Exponent ({len(hurst_exponent)} points)", fontsize=16)
+        plt.tight_layout()
+        plt.grid(True)
+        plt.xticks(fontsize=21)
+        plt.yticks(fontsize=21)
+        plt.legend(fontsize=21, bbox_to_anchor=(1.05, 1), loc="upper left")
+        plt.savefig("hfd_vs_hurst.png", dpi=320, bbox_inches="tight")
+
+
+if __name__ == "__main__":
+    k_max = 30
+    validator = HiguchiMethodValidate([hfd_pyeeg, hfd_matlab_equivalent], k_max)
+    validator.plot_hfd_vs_hurst()

complexeva-0.1.5/complexeva/utils/__init__.py

@@ -0,0 +1,2 @@
+from .convert_image_matrix import image_to_adjacency_matrix
+from .convert_matrix_network import matrix_to_networkx

complexeva-0.1.5/complexeva/utils/convert_image_matrix.py

@@ -0,0 +1,48 @@
+#!/Users/donyin/miniconda3/envs/rotation-1/bin/python
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+import numpy as np
+from skimage.io import imread
+from skimage.color import rgb2gray
+from skimage.filters import threshold_otsu
+from skimage.morphology import remove_small_objects, remove_small_holes
+
+
+def image_to_adjacency_matrix(image_path, threshold=128, hole_area_threshold_ratio=0.05, save_as=None):
+    """
+    Convert an image to a binary adjacency matrix using scikit-image preprocessing.
+    - save_as: The path to save the processed binary image.
+    - threshold: The threshold value for binarization. max value is 255.
+    - hole_area_threshold_ratio: The ratio of the hole area to the image area to be removed (ratio to the diagnal length).
+    """
+    image = imread(image_path)
+    if image.ndim == 3:
+        if image.shape[2] == 4:
+            image = image[..., :3]
+        image = rgb2gray(image)
+
+    threshold = threshold_otsu(image)
+    binary_image = image > threshold
+
+    # ---- some clean up ----
+    # binary_image = remove_small_objects(binary_image, min_size=64)
+    area_threshold = hole_area_threshold_ratio * np.hypot(*binary_image.shape)
+    binary_image = remove_small_holes(binary_image, area_threshold=area_threshold)
+    binary_matrix = binary_image.astype(np.uint8)
+
+    if save_as:
+        plt.figure(figsize=(16, 8))
+        plt.subplot(1, 2, 1)
+        plt.imshow(imread(image_path), interpolation="nearest")
+        plt.title("Original Image")
+        plt.axis("off")
+        plt.subplot(1, 2, 2)
+        plt.imshow(binary_matrix, cmap="binary", interpolation="nearest")
+        plt.title("Processed Binary Image")
+        plt.axis("off")
+        plt.tight_layout()
+        plt.savefig(save_as, dpi=300, bbox_inches="tight")
+        plt.close()
+    return binary_matrix

complexeva-0.1.5/complexeva/utils/convert_matrix_network.py

@@ -0,0 +1,71 @@
+import networkx as nx
+import numpy as np
+import matplotlib.pyplot as plt
+from rich import print
+
+
+def matrix_to_networkx(matrix, method: str = "laplacian", save_as=None):
+    """
+    Convert a symmetric adjacency matrix to a NetworkX graph.
+    Parameters: matrix (numpy.ndarray): A 2D numpy array representing the adjacency matrix.
+    Returns: networkx.Graph: A NetworkX graph object.
+    """
+
+    assert method in ["adjacency", "laplacian"], "> method should be either 'adjacency' or 'laplacian'"
+
+    match method:
+        case "adjacency":
+            """
+            convert a binary matrix representing a 2D fractal image into a NetworkX graph.
+            - nodes are pixels with value 1, and edges connect neighboring pixels.
+            - check neighbors (4-connectivity)
+            """
+            G = nx.Graph()
+            rows, cols = matrix.shape
+            for i in range(rows):
+                for j in range(cols):
+                    if matrix[i, j]:
+                        G.add_node((i, j))
+                        for dx, dy in [(-1, 0), (1, 0), (0, -1), (0, 1)]:
+                            ni, nj = i + dx, j + dy
+                            if 0 <= ni < rows and 0 <= nj < cols and matrix[ni, nj]:
+                                G.add_edge((i, j), (ni, nj))
+
+        case "laplacian":
+            if matrix.shape[0] != matrix.shape[1]:
+                previous_size = matrix.shape
+                matrix = np.pad(matrix, ((0, max(matrix.shape) - matrix.shape[0]), (0, max(matrix.shape) - matrix.shape[1])))
+                print(f"> warning: Laplacian matrix should be square. padded matrix: {previous_size} -> {matrix.shape}")
+            G = nx.from_numpy_array(matrix)
+            G.remove_nodes_from(list(nx.isolates(G)))
+
+    if save_as:
+        save_as = save_as if save_as.endswith(".png") else save_as + ".png"
+        fig = plt.figure(figsize=(12, 5))
+
+        # Plot matrix in first subplot
+        ax1 = fig.add_subplot(121)
+        ax1.imshow(matrix, cmap="viridis")
+        ax1.set_title("Original Matrix")
+        ax1.axis("off")
+
+        # Plot 3D network graph
+        ax2 = fig.add_subplot(122, projection="3d")
+        pos = nx.spring_layout(G, dim=3)
+
+        # Draw edges
+        edge_pos = np.array([(pos[u], pos[v]) for u, v in G.edges()])
+        for edge in edge_pos:
+            ax2.plot3D(edge[:, 0], edge[:, 1], edge[:, 2], "gray", alpha=0.6)
+
+        # Draw nodes
+        node_pos = np.array([pos[node] for node in G.nodes()])
+        ax2.scatter(node_pos[:, 0], node_pos[:, 1], node_pos[:, 2], c="blue", s=20, alpha=0.6)
+
+        ax2.set_title("3D Network Graph")
+
+        plt.tight_layout()
+        plt.savefig(save_as, dpi=300, bbox_inches="tight")
+        plt.close()
+
+    return G

complexeva-0.1.5/complexeva/utils/device.py

@@ -0,0 +1,29 @@
+import torch
+
+
+def select_device(priority=["cuda", "cpu"]):  # mps in the middle
+    """
+    Selects the device based on the given priority list.
+    If top priority device is not available, it will try the next device in the list.
+    E.g., it will try to select "cuda" first, then "mps", and finally "cpu"
+    So we can have the same code on local machine and on the server.
+    Just with
+
+    - local: select_device(["cuda", "cpu"])
+    - server: select_device(["cuda", "cpu"])
+
+    Parameters:
+        - priority (list): List of strings representing device priorities.
+
+    Returns:
+        - torch.device: Device selected based on priority.
+    """
+
+    if "cuda" in priority and torch.cuda.is_available():
+        return torch.device("cuda")
+    if "mps" in priority and torch.backends.mps.is_available() and torch.backends.mps.is_built():
+        return torch.device("mps")
+    if "cpu" in priority:
+        return torch.device("cpu")
+
+    raise ValueError("No valid device found in priority list.")

complexeva-0.1.5/complexeva.egg-info/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.1
+Name: complexeva
+Version: 0.1.5
+Home-page: 
+Author: Don Yin
+Author-email: don_yin@outlook.com
+Description-Content-Type: text/markdown
+
+# overview
+computing fractal dimensions (and other complexity measures) and complexity measures in networks and matrices. The package includes:
+
+# some functions (thus far)
+- Box-counting fractal dimension calculation for networks and matrices
+- Higuchi fractal dimension implementation
+- Network-to-matrix and image-to-matrix conversions
+- Dummy fractal generators for testing

complexeva-0.1.5/complexeva.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+README.md
+setup.py
+complexeva/__init__.py
+complexeva.egg-info/PKG-INFO
+complexeva.egg-info/SOURCES.txt
+complexeva.egg-info/dependency_links.txt
+complexeva.egg-info/top_level.txt
+complexeva/dummies/__init__.py
+complexeva/dummies/matrix.py
+complexeva/dummies/networks.py
+complexeva/measures/__init__.py
+complexeva/measures/cbb_matrix.py
+complexeva/measures/cbb_networkx.py
+complexeva/measures/co_activation.py
+complexeva/measures/higuchi.py
+complexeva/measures/validate.py
+complexeva/utils/__init__.py
+complexeva/utils/convert_image_matrix.py
+complexeva/utils/convert_matrix_network.py
+complexeva/utils/device.py

complexeva-0.1.5/complexeva.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

complexeva-0.1.5/complexeva.egg-info/top_level.txt

@@ -0,0 +1 @@
+complexeva

complexeva-0.1.5/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

complexeva-0.1.5/setup.py

@@ -0,0 +1,15 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="complexeva",
+    version="0.1.5",
+    packages=find_packages(),
+    install_requires=[],
+    author="Don Yin",
+    author_email="don_yin@outlook.com",
+    description="",
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
+    url="",
+    pyhon_requires=">=3.11",
+)