{"id":28819685,"url":"https://github.com/amr-yasser226/pagerank-power-method","last_synced_at":"2026-05-09T09:14:19.637Z","repository":{"id":291181256,"uuid":"976756637","full_name":"amr-yasser226/pagerank-power-method","owner":"amr-yasser226","description":"Modular Python implementation of the PageRank algorithm via the power method, with discrete‑math foundations, end‑to‑end code, and experimental validation.","archived":false,"fork":false,"pushed_at":"2025-06-18T19:12:53.000Z","size":3038,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-18T19:45:22.198Z","etag":null,"topics":["discrete-mathematics","graph-algorithms","markov-chain","network-analysis","networks","numpy","pagerank","power-method","python","scipy"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amr-yasser226.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-02T17:34:15.000Z","updated_at":"2025-06-18T19:15:53.000Z","dependencies_parsed_at":"2025-05-02T23:19:26.614Z","dependency_job_id":"264e26d0-945f-480b-a77b-cad645c55036","html_url":"https://github.com/amr-yasser226/pagerank-power-method","commit_stats":null,"previous_names":["amr-yasser226/pagerank-power-method"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/amr-yasser226/pagerank-power-method","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amr-yasser226%2Fpagerank-power-method","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amr-yasser226%2Fpagerank-power-method/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amr-yasser226%2Fpagerank-power-method/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amr-yasser226%2Fpagerank-power-method/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amr-yasser226","download_url":"https://codeload.github.com/amr-yasser226/pagerank-power-method/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amr-yasser226%2Fpagerank-power-method/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260633483,"owners_count":23039365,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["discrete-mathematics","graph-algorithms","markov-chain","network-analysis","networks","numpy","pagerank","power-method","python","scipy"],"created_at":"2025-06-18T21:00:52.357Z","updated_at":"2026-05-09T09:14:19.600Z","avatar_url":"https://github.com/amr-yasser226.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PageRank Power Method\n\nThis repository provides a comprehensive implementation of the PageRank algorithm using the Power Method. It is organized into four deliverables that cover problem definition, mathematical formulation, code implementation, and experimental validation.\n\n---\n\n## Repository Structure\n\n```\npagerank-power-method/\n├── 01. Deliverable 1 - Problem Definition \u0026 Background/\n│   └── 01. Deliverable 1 - Problem Definition \u0026 Background.pdf\n├── 02. Deliverable 2 - Mathematical Formulation \u0026 Algorithm/\n│   └── 02. Deliverable 2 - Mathematical Formulation \u0026 Algorithm.pdf\n├── 03. Deliverable 3 - Code Implementation \u0026 Documentation/\n│   └── pagerank-power-method/  # Code modules\n├── 04. Deliverable 4 - Experiments \u0026 Validation/\n│   ├── run_toy_experiments.py\n│   ├── run_real_experiments.py\n│   ├── run_sensitivity.py\n│   └── plots/                  # Generated figures\n├── LICENSE                     # MIT License\n├── requirements.txt            # Python dependencies\n└── venv/                       # Python virtual environment (excluded from version control)\n```\n\n---\n\n## Deliverables Overview\n\n1. **Deliverable 1 – Problem Definition \u0026 Background**\n\n   * Describes the PageRank algorithm from a discrete mathematics perspective.\n   * Includes problem statement, motivation, literature review, and theoretical foundations (graph theory and Markov chains).\n\n2. **Deliverable 2 – Mathematical Formulation \u0026 Algorithm**\n\n   * Formalizes PageRank as an eigenvector problem of the Google matrix.\n   * Defines the link matrix, teleportation adjustment, and damping factor.\n   * Presents the Power Method pseudocode, convergence criteria, and complexity analysis.\n\n3. **Deliverable 3 – Code Implementation \u0026 Documentation**\n\n   * Implements a modular Python codebase for PageRank computation.\n   * Core modules:\n\n     * `graph_loader.py`    – Load graphs from edge-list or adjacency-list formats.\n     * `matrix_builder.py`  – Build the sparse transition matrix and teleportation vector.\n     * `power_method.py`    – Compute PageRank via iterative power iterations.\n     * `utils.py`           – Helper routines (vector normalization, residual computation, plotting).\n     * `run_pagerank.py`    – Command-line script to run PageRank on a given graph file.\n\n4. **Deliverable 4 – Experiments \u0026 Validation**\n\n   * Evaluates convergence on toy graphs and a real-world network (Zachary’s Karate Club).\n   * Performs sensitivity analysis with respect to the damping factor (α).\n   * Generates tables and plots illustrating residuals, iteration counts, and runtime.\n\n---\n\n## Installation\n\n1. **Clone the repository**\n\n   ```bash\n   git clone https://github.com/amr-yasser226/pagerank-power-method.git\n   cd pagerank-power-method\n   ```\n\n2. **Create and activate a Python virtual environment**\n\n   ```bash\n   python3 -m venv venv\n   source venv/bin/activate    # On Windows: venv\\Scripts\\activate\n   ```\n\n3. **Install dependencies**\n\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n---\n\n## Usage\n\n### Command-Line Interface\n\nCompute PageRank on an edge-list or adjacency-list file:\n\n```bash\npython run_pagerank.py \u003cinput_path\u003e [--format edgelist|adjlist] [--alpha ALPHA] [--tol TOL] [--max_iter MAX_ITER]\n```\n\n* `\u003cinput_path\u003e`: Path to the graph file.\n* `--format` (`-f`): File format (`edgelist` or `adjlist`, default: `edgelist`).\n* `--alpha` (`-a`): Damping factor (default: 0.85).\n* `--tol` (`-t`): Convergence tolerance on L1 residual (default: 1e-6).\n* `--max_iter` (`-m`): Maximum number of iterations (default: 100).\n\n### Example\n\n```bash\n# Compute PageRank on an edge-list\npython run_pagerank.py data/web_graph.txt --alpha 0.85 --tol 1e-8\n```\n\n### Running Experiments\n\nDeliverable 4 includes three scripts under `04. Deliverable 4 - Experiments \u0026 Validation/`:\n\n* `run_toy_experiments.py`   – Convergence on predefined toy graphs.\n* `run_real_experiments.py`  – Validation on Zachary’s Karate Club network.\n* `run_sensitivity.py`       – Sensitivity analysis for different α values.\n\nRun each script directly:\n\n```bash\npython \"04. Deliverable 4 - Experiments \u0026 Validation/run_toy_experiments.py\"\npython \"04. Deliverable 4 - Experiments \u0026 Validation/run_real_experiments.py\"\npython \"04. Deliverable 4 - Experiments \u0026 Validation/run_sensitivity.py\"\n```\n\nPlots will be saved under `04. Deliverable 4 - Experiments \u0026 Validation/plots/`.\n\n---\n\n## Module Descriptions\n\n### graph\\_loader.py\n\n* **Functions**:\n\n  * `load_edge_list(path: str, directed: bool = True) -\u003e List[Tuple[int, int]]`\n  * `load_adjacency_list(path: str) -\u003e Dict[int, List[int]]`\n  * `graph_to_edge_list(graph: nx.Graph) -\u003e List[Tuple[int, int]]`\n* **Behavior**: Reads graph definitions, supports comments/blank lines, and validates node IDs.\n\n### matrix\\_builder.py\n\n* **Function**: `build_matrix(edges: List[Tuple[int, int]], alpha: float = 0.85) -\u003e Tuple[csr_matrix, np.ndarray]`\n* **Behavior**: Constructs a column-stochastic sparse transition matrix (handling dangling nodes) and a uniform teleportation vector.\n\n### power\\_method.py\n\n* **Function**: `compute_pagerank(P: csr_matrix, v: np.ndarray, alpha: float = 0.85, tol: float = 1e-6, max_iter: int = 100) -\u003e Tuple[np.ndarray, List[float], int, float]`\n* **Behavior**: Iteratively applies the Google operator, normalizes the rank vector, and tracks L1 residuals until convergence or max iterations.\n\n### utils.py\n\n* **Functions**:\n\n  * `normalize_vector(x: np.ndarray) -\u003e np.ndarray`\n  * `compute_residual(prev: np.ndarray, curr: np.ndarray) -\u003e float`\n  * `plot_residuals(history: List[float], title: str, path: Optional[str] = None) -\u003e None`\n* **Behavior**: Provides vector normalization, residual computation, and residual-plotting utilities.\n\n---\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n---\n\n## Contact\n\nFor questions or contributions, please open an issue or pull request on GitHub.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famr-yasser226%2Fpagerank-power-method","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famr-yasser226%2Fpagerank-power-method","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famr-yasser226%2Fpagerank-power-method/lists"}