ManyWaves: A Visual Analytics Approach for Exploring Multivariate Spatiotemporal Data Based on the Graph Wavelet Transform

Implementation of the preprocessing steps and visual system from the paper "ManyWaves: A Visual Analytics Approach for Exploring Multivariate Spatiotemporal Data Based on the Graph Wavelet Transform" published at Computer Graphics Forum.

Requirements

The code is based in Python, both for preprocessing and for initializing the visual system. We recommend using conda to configure the virtual environments. To install the dependencies of this code, use:

conda env create -f environment.yml 
conda activate wavelet_code

Repository Structure

.
├── app.py                 # Main script to start serving the visual system
├── .env.example           # Template for the .env file with the Mapbox token
├── static/                # JS and CSS code for the visual system implemented with D3.js
├── templates/             # HTML templates of the visual system
└── wavelet_code/          # Implementation of preprocessing steps of the visual system (GWT, Autoencoder)
    ├── data/              # Input data and generated files (not versioned)
    ├── notebooks/         # Code to generate figures, synthetic examples and the input data
    └── scripts/           # Main preprocessing functionalities, such as the GWT and some plotting functions
        └── prepare_visual_system.py  # Generates the files required by the visual system

Data preprocessing and starting the server

These instructions use the Brazilian Legal Amazon dataset from the paper, named BLACities_Year2 in the code: BLACities is the spatial division (municipalities) and Year2 is the time interval. Run all commands from the root of the repository.

1. Add the input files

Download files from the following link. Place these files inside wavelet_code/data/:

File	Content
polygon_data/BLACities_Year2.csv	One row for each polygon and date, with the columns date, id_poly and one column per feature
adj_matrix/BLACities.npy	Adjacency matrix of the polygons, ordered by id_poly (.npz sparse matrices are also accepted)
shapefiles/BLACities.geojson	Polygon geometries, with an id_poly property

2. Generate the files for the visual system

python wavelet_code/scripts/prepare_visual_system.py --poly-division BLACities --time-interval Year2

This takes a few minutes on a CPU and saves the following files inside wavelet_code/data/:

File	Content
similarity_matrix/BLACities_Year2.csv	Correlation between each pair of features
coeffs/BLACities_Year2.csv	Scaled graph wavelet transform coefficients of each feature
projections/BLACities_Year2.csv	2D position of each polygon, obtained with an autoencoder and t-SNE

The projection is reproducible for a given seed, which can be changed with --seed (default: 0). Use --steps to run only some of the steps (similarity, wavelet, projection); the projection step needs the output of the wavelet step.

To use another dataset, provide the same input files with its names, pass them to the script, and set POLY_TIME = "<poly_division>_<time_interval>" at the top of app.py. The name of the spatial division can't contain underscores.

3. Configure the Mapbox token

The map view uses Mapbox GL JS, which requires a Mapbox access token. Create a free account at mapbox.com, copy your default public token (it starts with pk.), and save it in a .env file at the root of the repository:

cp .env.example .env
# then edit .env and set MAPBOX_TOKEN=pk.your_token_here

Instead of using the file, you can also set the variable in your shell with export MAPBOX_TOKEN=pk.your_token_here.

4. Start the server

Then, finally, to start the server run:

python app.py

And open your browser at http://127.0.0.1:8000/.

Contact

For any questions or issues, please reach me at: giovani.valdrighi at ic.unicamp.br

Citation

If you use this code in your research, please cite the following paper:

@inproceedings{valdrighi2026manywaves,
  title={ManyWaves: A Visual Analytics Approach for Exploring Multivariate Spatiotemporal Data Based on the Graph Wavelet Transform},
  author={Valdrighi, Giovani and Garcia-Zanabria, Germain and Diaz, Mauro and Nonato, Luis Gustavo and Ferreira, Nivan and Poco, Jorge},
  booktitle={Computer Graphics Forum},
  pages={e70653},
  year={2026},
  organization={Wiley Online Library}
}