---
license: mit
language:
- en
pretty_name: Randomized Spectral Co-Clustering
size_categories:
- n<1K
task_categories:
- other
tags:
- co-clustering
- randomized-svd
- spectral-clustering
- matlab
- text-mining
configs:
- config_name: original_artifacts_manifest
  data_files:
  - split: train
    path: docs/original_artifacts_manifest.csv
  default: true
---

# Randomized Spectral Co-Clustering

Research code accompanying work on scalable spectral co-clustering using randomized matrix approximations. The repository contains MATLAB implementations of baseline spectral co-clustering and randomized variants based on random projection, random sampling, and related low-rank approximations.

## Repository structure

- `src/` — core co-clustering algorithms.
- `src/support/` — supporting spectral-clustering and affinity-matrix routines.
- `examples/` — runnable demonstrations and benchmark scripts.
- `tests/` — lightweight smoke tests.
- `utils/` — evaluation and data-loading utilities.
- `data/` — small example datasets included for testing.
- `docs/original_artifacts_manifest.csv` — inventory of larger research artifacts omitted from GitHub.

## Requirements

- MATLAB R2021a or newer is recommended.
- Statistics and Machine Learning Toolbox.

The code uses functions including `kmeans`, `svds`, `eigs`, `spectralcluster`, and `confusionchart`.

## Quick start

Clone the repository, open MATLAB in the repository root, and run:

```matlab
run('setup_project.m');
run('tests/run_smoke_tests.m');
```

To run a small comparison example:

```matlab
run('examples/checkerboard_comparison.m');
```

Additional examples are available in the `examples/` directory.

## Included methods

The main implementations include:

- `spectral_co_clustering.m` — baseline spectral co-clustering.
- `spectral_bi_clustering.m` — spectral biclustering baseline.
- `RP_SCC.m` — random-projection spectral co-clustering.
- `RPRE_SCC.m` — randomized projection/reconstruction variant.
- `RS_SCC.m` — random-sampling spectral co-clustering.
- `ID.m` — interpolative-decomposition helper.

## Data and reproducibility

Small datasets required by the smoke tests and selected examples are included under `data/`. Larger `.mat` datasets and MATLAB `.fig` files from the original experimental workspace are omitted to keep the repository lightweight. Their original inventory is provided in `docs/original_artifacts_manifest.csv`.

To reproduce experiments that require an omitted dataset, place the corresponding file in `data/` and run the relevant script in `examples/`.

Because the randomized methods use stochastic projections, sampling, or clustering initialization, set the MATLAB random seed before a run when exact repeatability is needed:

```matlab
rng(1, 'twister');
```

## Citation

A machine-readable citation is provided in [`CITATION.cff`](CITATION.cff). GitHub will display a **Cite this repository** button once the repository is public.

For now, the software may be cited as:

> Mazdarani, F. (2026). *Randomized Spectral Co-Clustering* [Computer software]. GitHub.

When citing the research results, please cite the associated paper as well.

## License

This project is released under the MIT License. See [`LICENSE`](LICENSE).

## Contact

For questions about the code or experiments, open a GitHub issue.

<!-- BEGIN GENERATED METADATA (_publishing/generate_metadata.py) -->

## Dataset card

| | |
|---|---|
| **Paper** | [Randomized SVD Approximations for Spectral Co-Clustering of Word-Document Matrices](https://doi.org/10.48550/arXiv.2609.19243) |
| **Venue** | arXiv preprint arXiv:2609.19243, 2026 |
| **Authors** | Fateme Mazdarani, Alberto Campos Hernandez, Carlos Toxtli |
| **License** | MIT License (`mit`) |
| **Dataset DOI** | [10.5281/zenodo.24179048](https://doi.org/10.5281/zenodo.24179048) |
| **Version** | 1.0.0 |
| **Code repository** | https://github.com/mazdarani/randomized-spectral-co-clustering |
| **Maintainer** | [Human-AI Empowerment Lab, Clemson University](https://haielab.org) |

## Dataset structure

| Path | Format | Size | Records |
|---|---|---|---|
| `REPRODUCIBILITY.md` | md | 1.9 KB |  |
| `setup_project.m` | m | 222 B |  |
| `data/Checkerboard4x3_1000.mat` | mat | 7.6 MB |  |
| `data/Checkerboard_100.mat` | mat | 80.1 KB |  |
| `data/News4_wcsimp.mat` | mat | 338.1 KB |  |
| `data/README.md` | md | 289 B |  |
| `docs/original_artifacts_manifest.csv` | csv | 5.5 KB | 86 |
| `examples/cancerdoc_demo.m` | m | 1.8 KB |  |
| `examples/checkerboard_benchmark.m` | m | 2.7 KB |  |
| `examples/checkerboard_comparison.m` | m | 4.1 KB |  |
| `examples/news20_spectral_cluster_demo.m` | m | 639 B |  |
| `examples/synthetic_coclustering_demo.m` | m | 1.5 KB |  |
| `examples/synthetic_largescale_coclustering_demo.m` | m | 1.4 KB |  |
| `src/ID.m` | m | 194 B |  |
| `src/RPRE_SCC.m` | m | 1.1 KB |  |
| `src/RP_SCC.m` | m | 996 B |  |
| `src/RS_SCC.m` | m | 696 B |  |
| `src/spectral_bi_clustering.m` | m | 501 B |  |
| `src/spectral_co_clustering.m` | m | 780 B |  |
| `src/support/cosineSimilarity.m` | m | 237 B |  |
| `src/support/full_euclidean_affinity_matrix.m` | m | 358 B |  |
| `src/support/knn_affinity_matrix.m` | m | 424 B |  |
| `src/support/l1_affinity_matrix.m` | m | 242 B |  |
| `src/support/laplacian.m` | m | 603 B |  |
| `src/support/spectral_cluster.m` | m | 218 B |  |
| `tests/run_smoke_tests.m` | m | 1.2 KB |  |
| `utils/AccMeasure.m` | m | 1.4 KB |  |
| `utils/require_data_file.m` | m | 389 B |  |

28 files, 8.1 MB in total (metadata files excluded). Records are rows for CSV/TSV/JSONL files and list length for JSON arrays.

## Loading the data

```python
from datasets import load_dataset

ds = load_dataset("ai4he/randomized-spectral-co-clustering", "original_artifacts_manifest")
```

Available subsets: `original_artifacts_manifest`. All other files can be downloaded with `huggingface_hub.snapshot_download` or from the Zenodo record.

## Known limitations

- Only small sample matrices are included; larger working files (e.g. CancerDoc.mat, 169 MB) are inventoried in docs/original_artifacts_manifest.csv but not distributed.

## Personal and sensitive information

None.

## License

The data and documentation are released under the [MIT License](https://opensource.org/licenses/MIT).

## Citation

If you use this dataset, please cite the paper:

```bibtex
@misc{Mazdarani2026Randomized,
 title = {Randomized SVD Approximations for Spectral Co-Clustering of Word-Document Matrices},
 author = {Mazdarani, Fateme and Toxtli, Carlos},
 year = {2026},
 eprint = {2609.19243},
 archiveprefix = {arXiv},
 primaryclass = {cs.LG},
 doi = {10.48550/arXiv.2609.19243},
 url = {https://arxiv.org/abs/2609.19243}
}
```

and the dataset:

```bibtex
@dataset{Mazdarani2026RandomizedSpectralCoClusData,
  author = {Mazdarani, Fateme and Campos Hernandez, Alberto and Toxtli, Carlos},
  title = {{Randomized Spectral Co-Clustering}: Dataset for ``Randomized SVD Approximations for Spectral Co-Clustering of Word-Document Matrices''},
  year = {2026},
  version = {1.0.0},
  publisher = {Zenodo},
  doi = {10.5281/zenodo.24179048},
  url = {https://doi.org/10.5281/zenodo.24179048}
}
```

<!-- END GENERATED METADATA -->