Welcome to SmellscaPy
SmellscaPy is a Python library for analysing and representing indoor smellscape perceptual data.
It provides tools for data validation, calculation of perceptual indices, visualization, descriptive statistics and modelling to support reproducible research in smellscape studies.
Key Features
- Data validation & preprocessing of smellscape survey datasets
- Computation of perceptual indicators (i.e., pleasantness, presence)
- Visualizations: scatter plots, density plots, simplified density plots, dynamic plots
- Integration with the Python scientific stack (Pandas, NumPy, Matplotlib)
- Ready-to-use example datasets for tutorials and testing
- Analysis: descriptive statistics and modelling
Installation
SmellscaPy can be installed with pip:
pip install smellscapy
Requires Python 3.12.9+.
Documentation
This documentation is designed to help you understand and use SmellscaPy effectively.
Tutorials
Practical examples showing how to use our project in real-world scenarios. For more information, please see the Tutorials section.
License
This project is licensed under the BSD 3-Clause License. Please see LICENSE for licence guidelines.
Contributing
If you would like to contribute or if you have any bugs you have found while using `SmellscaPy', please feel free to get in touch or submit an issue or pull request!
Aknowledgment
The smellscape-representation methods implemented in the plotting functions of SmellscaPy are derived and adapted from the probabilistic soundscape framework described in the publication by Andrew Mitchell et al. [1] and implemented in the Soundscapy open-source library (c) 2025, Andrew Mitchell All rights reserved. We gratefully acknowledge the authors of Soundscapy for their conceptual and methodological foundation, which significantly informed the development of the smellscape visualisation tools in this project.
Citation
Please cite us if you use the SmellscaPy library:
G. Torriani, R. Albatici, F. Babich, M. Vescovi, M. Zampini, S. Torresin, Developing a principal components model of indoor smellscape perception in office buildings, Build Environ 279 (2025) 113044. https://doi.org/10.1016/j.buildenv.2025.113044.