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.

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

Installation

Smellscapy can be installed with pip:

pip install smellscapy

Requires Python 3.12.9+.

Quick Start

Here’s a minimal example using the included sample dataset.
It loads the data, validates it, computes perceptual indicators, and generates simple visualizations:

from smellscapy.surveys import validate
from smellscapy.databases.DataExample import load_example_data_Eurac
from smellscapy.calculations import calculate_pleasantness, calculate_presence
from smellscapy.plotting.scatter import plot_scatter
from smellscapy.plotting.simple_density import plot_simple_density

# Load example dataset
df = load_example_data_Eurac()

# Validate data
df, excl_df = validate(df)

# Compute perceptual indices
df = calculate_pleasantness(df)
df = calculate_presence(df)

# Visualization
plot_scatter(df)
plot_simple_density(df)
plot_density(df)
plot_dynamic(df)

#Analysis
df_stat = descriptive_statistics(df)

Tutorials for using Smellscapy can be found in the documentation.

Citation

If you are using Smellscapy in your research, please help our scientific visibility by citing our work! Please include a citation to our accompanying paper:

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.

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!

Licence

This project is licensed under the BSD 3-Clause License. Please see LICENSE for licence guidelines.

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 [2] . 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.

1. Mitchell, A., Aletta, F., & Kang, J. (2022). How to analyse and represent quantitative soundscape data. JASA Express Letters, 2, 37201.
2. Mitchell, A. (2024, October). Soundscapy: A python package for soundscape assessment and analysis. In INTER-NOISE and NOISE-CON Congress and Conference Proceedings (Vol. 270, No. 7, pp. 4029-4039). Institute of Noise Control Engineering.