Metadata-Version: 2.4
Name: smellscapy
Version: 0.2.6
Summary: A python library for analysing and representing indoor smellscape perceptual data.
Author: Giulia Torriani, Olga Somova
Author-email: Giulia Torriani <giulia.torriani@eurac.edu>, Olga Somova <olga.somova@eurac.edu>
License-Expression: BSD-3-Clause
License-File: LICENSE
Requires-Dist: loguru>=0.7.3
Requires-Dist: matplotlib>=3.10.5
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: pandas>=2.3.2
Requires-Dist: plotly>=6.5.1
Requires-Dist: scipy>=1.16.1
Requires-Dist: seaborn>=0.13.2
Requires-Python: >=3.11
Description-Content-Type: text/markdown

![Smellscapy Logo](https://raw.githubusercontent.com/EURAC-EEBgroup/smellscapy/main/docs/Logo.png) <!-- markdownlint-disable-line MD041 -->


# Smellscapy

[![PyPI version](https://badge.fury.io/py/smellscapy.svg)](https://badge.fury.io/py/smellscapy)
[![Documentation status](https://github.com/EURAC-EEBgroup/smellscapy/actions/workflows/docs.yml/badge.svg)](https://github.com/EURAC-EEBgroup/smellscapy/actions/workflows/docs.yml)
[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)

**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:

```bash
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:

```python
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](https://smellscapy.readthedocs.io/en/latest/).

## 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](LICENCE) 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]](#ref1) and implemented in the Soundscapy open-source library (c) 2025, Andrew Mitchell All rights reserved [[2]](#ref2) .
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. <a name="ref1"></a> Mitchell, A., Aletta, F., & Kang, J. (2022). How to analyse and represent quantitative soundscape data. _JASA Express Letters, 2_, 37201.
2. <a name="ref2"></a>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.
