CaLLiPer

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 26 Open GitHub ↗

[CEUS] Contrastive Language-Location Pre-training

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# CaLLiPer - Contrastive Language-Location Pre-training
Welcome! This is the repository for *CaLLiPer* model presented in our paper 
[Multimodal Contrastive Learning of Urban Space Representations from POI Data](https://doi.org/10.1016/j.compenvurbsys.2025.102299), 
published in *Computers, Environment and Urban Systems* (2025).

## :star: Highlights

- Simple and effective representation learning for urban spaces using POI data.
- The first multimodal contrastive learning model to align spatial and semantic information.
- Improved conceptualisation of urban space representations through location encoding.
- Enhanced modelling of POI semantics by pre-trained text encoders.
- State-of-the-art performance and interoperability (see also Extension — CaLLiPer+).

## Requirements
- pytorch >= 2.2.0
- transformer >= 4.43.4
- pytorch-lightning == 2.3.3
- tensorboard >= 1.14.0
- scikit-learn 
...

## Data

### POI data
The use of [OS POI data](https://www.ordnancesurvey.co.uk/products/points-of-interest) requires an Educational Licence. For demonstration purpose, we provide a sample of the POI data used in our study in `/data/london_poi_202203/sample_poi.csv`. You can easily construct your own coordinate-text pairs as training data similar to this.

### Land use data
The land use data used in our experiment was derived from [Verisk data](https://www.verisk.com/en-gb/solutions/land-buildings-data/), obtained through [Digimap](https://digimap.edina.ac.uk/roam/map/verisk). Please find it in `/data/landuse_classification/sampled_points_landuse.geojson`

### Socioeconomic status data
The NS-SeC dataset used in our experiment was obtained from [ONS](https://www.ons.gov.uk/). The original data is stored in `data/socioeconomic/lon_lsoa_ns-sec.csv`. The preprocessing code of this dataset can be found in the evaluation notebook - `sdm.ipynb`

## Training
Specifiy the hyperparameters in `configs/default.yaml` and run the following command for model training.

```bash
python main.py --cofing configs/default.yaml
```
The output will be saved in `logs/{exp_name}/`, including Tensorboard events and model checkpoints.

## Testing
After finishing the pre-training, one can evaluate the resulting CaLLiPer model checkpoint on two downstream tasks - LUC (`luc.ipynb`) and SDM (`sdm.ipynb`). For ease of replicating the results presented in our paper, we provide the pre-trained checkpoint of *CaLLiPer-SenTrans* - shared through [Google Drive](https://drive.google.com/drive/folders/1MIou67A5rSIHaGVB5DN2Sce3iHO7t_2W?usp=drive_link). Please download it and put it in `checkpoints/`.

See the two Jupyter Notebooks, `luc.ipynb` and `sdm.ipynb`, for the complete downstream model training process. The resulting downstream models will be saved in `downstream_res/...`. If you do not feel like training downstream models yourself, we have also provided them - you probably have already found them in `downstream_res/...`

Note that due to the size of *CaLLiPer-Llama*, we have not provided its checkpoint in this repo at the moment but will consider sharing it if requested.

## Extension — CaLLiPer+

We further propose **CaLLiPer+**, an extension of CaLLiPer.

- Simple modification: replace the construction of POI descriptions to include **POI names** in addition to categories.
- This enriched semantic information leads to **consistent improvements** (4–11%) in downstream tasks such as LUC and SDM.
- POI names also enhance **location retrieval**, enabling the embeddings to distinguish fine-grained concepts.

For details, please see our GIScience 2025 paper:  
[*Enriching Location Representation with Detailed Semantic Information*](https://doi.org/10.4230/LIPIcs.GIScience.2025.3).

## TODOs
We plan to add more stuff in the future:

:white_check_mark: Pre-trained results for Space2Vec and HGI. See `baselines/pretrained`.

:white_check_mark: Code for clustering visualisation (reproducing Figure 3 in the paper). See `vis_clustering.ipynb`.

🔲 Code for TF-IDF, LDA, Place2Vec. Coming soon.

## Acknowledgements

The implementation of various location encoding methods is based on [Space2Vec](https://github.com/gengchenmai/space2vec) and [Spherical Harmonics and Sinusoidal Representation Networks](https://github.com/MarcCoru/locationencoder). This work has also been inspired by [SatCLIP](https://github.com/microsoft/satclip).

We appreciate their inspiring works.

## Citation
If you find this repo useful for your research, please consider citing the following paper:
```bibtex

@article{wang2025multi,
  author    = {Wang, Xinglei and Cheng, Tao and Law, Stephen and Zeng, Zichao and Yin, Lu and Liu, Junyuan},
  title     = {Multimodal Contrastive Learning of Urban Space Representations from POI Data},
  journal   = {Computers, Environment and Urban Systems},
  volume    = {120},
  pages     = {102299},
  year      = {2025},
  publisher = {Elsevier},
  doi       = {10.1016/j.compenvurbsys.2025.102299}
}

@inproceedings{liu2025enriching,
  author    = {Liu, Junyuan and Wang, Xinglei and Cheng, Tao},
  title     = {Enriching Location Representation with Detailed Semantic Information},
  booktitle = {13th International Conference on Geographic Information Science (GIScience 2025)},
  series    = {Leibniz International Proceedings in Informatics (LIPIcs)},
  volume    = {346},
  pages     = {3:1--3:15},
  year      = {2025},
  doi       = {10.4230/LIPIcs.GIScience.2025.3}
}
```

CaLLiPer

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README