Initial commit: Range–CoMine impl + baselines + experiments + lattice export + tests + CI + packaging + docker

Author: srikanthbaride

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test-and-plots:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install deps
+        run: python -m pip install -U pip pytest matplotlib
+      - name: Run tests
+        run: pytest -q
+      - name: Generate example plots
+        run: |
+          python experiments.py --mode min_prev --mins 0.3,0.5 --d1 8 --d2 25 --features 3 --instances 4 --seed 5 --algos range,naive --export_svg
+          python experiments.py --mode range --min_prev 0.5 --d1s 3 --d2s 6,8 --csv examples/toy.csv --algos range,naive --export_svg
+          python lattice_export.py --outfile lattice_demo --d1 8 --d2 30 --min_prev 0.5 --features 4 --instances 5 --seed 7 --cross_level --png
+      - name: Upload plots
+        uses: actions/upload-artifact@v4
+        with:
+          name: plots
+          path: plots/**

Dockerfile

@@ -0,0 +1,21 @@
+
+# Simple reproducible container for Range–CoMine
+FROM python:3.11-slim
+
+# System deps for matplotlib (headless)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    libfreetype6-dev \
+    libpng-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY . /app
+
+# Install package + deps
+RUN python -m pip install -U pip && \
+    pip install -r requirements.txt && \
+    pip install -e .
+
+# Default command runs tests; override with `docker run ... <cmd>`
+CMD ["pytest", "-q"]

Makefile

@@ -0,0 +1,38 @@
+.PHONY: install test plots lattice all
+
+install:
+	python -m pip install -U pip pytest matplotlib
+
+test:
+	pytest -q
+
+plots:
+	python experiments.py --mode min_prev --mins 0.3,0.5 --d1 8 --d2 25 --features 3 --instances 4 --seed 5 --algos range,naive --export_svg
+	python experiments.py --mode range --min_prev 0.5 --d1s 3 --d2s 6,8 --csv examples/toy.csv --algos range,naive --export_svg
+
+lattice:
+	python lattice_export.py --outfile lattice_demo --d1 8 --d2 30 --min_prev 0.5 --features 4 --instances 5 --seed 7 --cross_level --png
+
+all: install test plots lattice
+
+
+lock:
+	pip install -r requirements.txt && pip freeze > requirements.lock
+
+docker-build:
+	docker build -t range-comine:latest .
+
+docker-test:
+	docker run --rm -v $(PWD)/plots:/app/plots range-comine:latest
+
+docker-minprev:
+	docker run --rm -v $(PWD)/plots:/app/plots range-comine:latest \
+		python experiments.py --mode min_prev --mins 0.3,0.5 --d1 8 --d2 25 --features 3 --instances 4 --seed 5 --algos range,naive --export_svg
+
+docker-range:
+	docker run --rm -v $(PWD)/plots:/app/plots range-comine:latest \
+		python experiments.py --mode range --min_prev 0.5 --d1s 3 --d2s 6,8 --csv examples/toy.csv --algos range,naive --export_svg
+
+docker-lattice:
+	docker run --rm -v $(PWD)/plots:/app/plots range-comine:latest \
+		python lattice_export.py --outfile lattice_demo --d1 8 --d2 30 --min_prev 0.5 --features 4 --instances 5 --seed 7 --cross_level --png

README.md

@@ -0,0 +1,135 @@
+# Range–CoMine (demo implementation)
+
+This repository contains a **reference implementation** of *Range–CoMine* (single‑pass colocation mining for a **distance range**) and two baselines (Naive and RangeInc‑Mining). It is designed for clarity and correctness on small–medium datasets.
+
+## Quick start
+
+```bash
+# (In this folder)
+python -m range_comine.cli --synthetic --features 4 --instances 6 --d1 10 --d2 35 --min_prev 0.5 --algo range_comine
+```
+
+Use the baselines:
+```bash
+python -m range_comine.cli --synthetic --features 4 --instances 6 --d1 10 --d2 35 --min_prev 0.5 --algo naive
+python -m range_comine.cli --synthetic --features 4 --instances 6 --d1 10 --d2 35 --min_prev 0.5 --algo range_inc
+```
+
+## Data format
+
+If using real data, prepare a CSV with header:
+```
+id,feature,x,y
+A.1,A,12.3,45.6
+...
+```
+
+## Notes
+
+- This demo uses an O(n^2) star‑neighborhood build and a naive clique enumeration for k≥3. It is faithful to the paper’s logic but not tuned for very large datasets.
+- For production scale, replace the neighbor construction with an **R‑tree/IR‑tree** and use a **join‑less** clique enumeration with star instances as in the paper.
+- The **critical distance** computation follows the 3‑step procedure (map → cumulative union → PI sweep) and **CDMP** pruning.
+
+## Citation
+
+Please cite the original paper when using this code.
+
+
+## Credits
+
+This reference implementation follows the ideas presented in:
+
+> **Srikanth Baride, Anuj S. Saxena, Vikram Goyal.** *Efficiently Mining Colocation Patterns for Range Query.* **Big Data Research**, 31:100369, 2023.
+
+If you use this repository in academic work, please cite the above paper. (BibTeX sketch)
+
+```bibtex
+@article{Baride2023RangeCoMine,
+  title   = {Efficiently Mining Colocation Patterns for Range Query},
+  author  = {Baride, Srikanth and Saxena, Anuj S. and Goyal, Vikram},
+  journal = {Big Data Research},
+  volume  = {31},
+  pages   = {100369},
+  year    = {2023},
+  issn    = {2214-5796}
+}
+```
+
+
+## Experiments (CLI + SVG export)
+
+Synthetic:
+```bash
+python experiments.py --mode min_prev --mins 0.2,0.4,0.6 --d1 10 --d2 35 --features 4 --instances 8 --seed 13 --algos range,naive,range_inc --export_svg
+```
+
+CSV dataset:
+```bash
+python experiments.py --mode range --min_prev 0.5 --d1s 5,10 --d2s 20,30 --csv examples/toy.csv --algos range,naive --export_svg
+```
+
+## Lattice export (PDF/SVG)
+```bash
+python lattice_export.py --outfile lattice_demo --d1 8 --d2 30 --min_prev 0.5 --features 4 --instances 5 --seed 7
+# outputs plots/lattice_demo.pdf and plots/lattice_demo.svg
+```
+
+## Tests
+```bash
+pytest -q
+```
+
+
+## Makefile shortcuts
+```bash
+make install   # deps
+make test      # run pytest
+make plots     # quick sweeps + SVG
+make lattice   # lattice export (PDF/SVG/PNG, cross-level edges)
+make all       # install + test + plots + lattice
+```
+
+## CI (GitHub Actions)
+A workflow at `.github/workflows/ci.yml` runs:
+- `pytest`
+- sample experiments (min_prev/range) with SVG export
+- lattice export with cross-level edges and PNG
+- uploads `plots/` as build artifacts
+
+
+## Packaging
+Install in editable/development mode:
+```bash
+./dev_install.sh
+# or
+pip install -e .
+```
+
+
+## Console scripts
+After `pip install -e .`, you can run:
+```bash
+range-comine-cli --synthetic --features 4 --instances 6 --d1 10 --d2 35 --min_prev 0.5 --algo range_comine
+range-comine-exp --mode min_prev --mins 0.2,0.4,0.6 --d1 10 --d2 35 --features 4 --instances 8 --seed 13 --algos range,naive,range_inc --export_svg
+range-comine-lattice --outfile lattice_demo --d1 8 --d2 30 --min_prev 0.5 --features 4 --instances 5 --seed 7 --cross_level --png
+```
+
+## Lockfiles
+- Classic pip:
+  ```bash
+  make lock        # creates requirements.lock via pip freeze
+  ```
+- Using **uv**:
+  ```bash
+  uv venv && uv pip install -e .
+  uv lock          # creates uv.lock
+  ```
+
+## Docker
+```bash
+make docker-build      # build image
+make docker-test       # run tests in container
+make docker-minprev    # min_prev sweep (plots mounted to ./plots)
+make docker-range      # range sweep (plots mounted to ./plots)
+make docker-lattice    # lattice export (PDF/SVG/PNG)
+```

dev_install.sh

@@ -0,0 +1,6 @@
+
+#!/usr/bin/env bash
+set -euo pipefail
+python -m pip install -U pip
+pip install -e .
+echo "Installed range-comine in editable mode."

examples/toy.csv

@@ -0,0 +1,13 @@
+id,feature,x,y
+A.1,A,0,0
+A.2,A,10,0
+A.3,A,20,0
+B.1,B,0,8
+B.2,B,12,1
+B.3,B,22,2
+C.1,C,1,20
+C.2,C,13,19
+C.3,C,25,18
+D.1,D,2,28
+D.2,D,14,27
+D.3,D,26,26