cosmos-odor 1.0.2

A Data-Driven Probabilistic Time Series Simulator for Chemical Plumes

COSMOS: A Data-Driven Probabilistic Time Series Simulator for Chemical Plumes Across Spatial Scales

The development of robust odor navigation strategies for automated environmental monitoring applications requires realistic simulations of odor time series for agents moving across large spatial scales. Traditional approaches that rely on computational fluid dynamics (CFD) methods can capture the spatiotemporal dynamics of odor plumes, but are impractical for large-scale simulations due to their computational expense. On the other hand, puff-based simulations, although computationally tractable for large scales and capable of capturing the stochastic nature of plumes, fail to reproduce naturalistic odor statistics. Here, we present COSMOS (Configurable Odor Simulation Model over Scalable Spaces), a data-driven probabilistic framework that synthesizes realistic odor time series from spatial and temporal features of real datasets. COSMOS generates similar distributions of key statistical features such as whiff frequency, duration, and concentration as observed in real data, while dramatically reducing computational overhead. By reproducing critical statistical properties across a variety of flow regimes and scales, COSMOS enables the development and evaluation of agent-based navigation strategies with naturalistic odor experiences. To demonstrate its utility, we compare odor-tracking agents exposed to CFD-generated plumes versus COSMOS simulations, showing that both their odor experiences and resulting behaviors are quite similar.

Below is a graphical representation of how the algorithm works.

License

This repository is dedicated to the public domain under CC0 1.0 Universal.

Requirements

1. Install Packages:

   pip install pandas
   pip install h5py
   pip install numpy
   pip install matplotlib
   pip install figurefirst
   pip install tables
   pip install POT
   pip install tsfresh
   

2. To install requirements:

   pip install -r requirements.txt
   

3. Data Setup (Required):

   All data, trained models and figures are available for download from data dryad. Please place the folder data and svgs in the home folder of COSMOS to run all scripts.

   Rigolli's data can be found here, download and place coordinates.mat, crosswind_v.mat, downwind_v.mat, ground_data.mat, nose_data.mat, vertical_v.mat, in the data/rigolli location.

   After setup, your directory should look like:

   COSMOS/
   ├── cosmos/              # Package code
   ├── data/               # Downloaded from Dryad
   │   ├── hws/
   │   ├── lws/  
   │   ├── forest/
   │   └── rigolli/        # Additional files from Zenodo
   └── svgs/               # Downloaded from Dryad
   

4. For Package Usage (Simplified Interface):

   pip install -e .  # Install COSMOS as package
   

   Then use the simplified interface:

   import cosmos
   model = cosmos.predictor('desert-hws')
   concentration = model.step_update(1.0, 0.5)
   

   Refer Usage for more details.

5. To visualize the figures and see the results and calculations, you will need to install the following:

   • FlyPlotLib
   • FigureFirst
   • Inkscape 1.2

Follow the setup of FigureFirst into inkscape.

Files:

Example Notebooks & Scripts

Minimal Usage & API Demos

• Minimal Example Notebook: Jupyter notebook showing minimal usage of the COSMOS package and API.
• Minimal Example (script): Python script for the simplest possible COSMOS usage.

Training & Evaluation

• Training COSMOS Spatial: How to train a COSMOS spatial model (if present).
• Testing Trajectory with COSMOS: Test a trajectory using the COSMOS algorithm (if present).

Agent-Based Tracking & Analysis

• Agent Based Tracking: Surge and cast implementation using COSMOS and CFD Rigolli for odor experience.
• Agent Tracking Trajectory Comparison: Compare agent-based tracking using COSMOS and CFD, including timing diagrams.
• COSMOS Batch Algorithm: Batch testing of trajectories with COSMOS.
• COSMOS Tracking Algorithm: Algorithm for use with agent tracking.
• Helper for CFD Methods: Utilities for working with CFD (Rigolli) data.
• Helper for Odor Statistics Calculation: Scripts for odor statistics calculations.

Figures & Visualization

• Algorithm Figure Notebook: Generates the main algorithm figure.
• Results Notebooks, results_lws.ipynb, results_forest.ipynb, results_rigolli.ipynb: Notebooks for reproducing results figures.
• Tracking Results Notebook: Agent-based tracking results and comparison.
• Supplemental Figure Notebook: Supplemental analysis and flow diagrams.

Pre-trained Models and Data and Figure svgs

All data, trained models and figures are available for download from data dryad. Please place the folder data and svgs to in the home folder of COSMOS to run all scripts. Rigolli's data can be found here, download and place coordinates.mat, crosswind_v.mat, downwind_v.mat, ground_data.mat, nose_data.mat, vertical_v.mat, in the data/rigolli location.

Results

Our algorithm achieved similar outdoor statistical distribution, with a high observed wasserstein distance (higher p value representing more similarity). Below is results for desert dataset which had a windspeed ranging between 3.5m/s to 6m/s (HWS). The result can be reproduced using this script.

Figures

Below are interactive notebooks, which can be used using Jupyter Notebook and run using python 3.8 and inskcape to generate the figures and results. These figures were generated using figurefirst

Main Text Figures:

1. Figure 1 : Overview of COSMOS algorithm
2. Figure 2 : COSMOS results on HWS desert data
3. Figure 3 : COSMOS results on Rigolli odor simulator data
4. Figure 4 : Agent based tracking using COSMOS and CFD, trajectory comparison and timing diagram

Supplemental Figure

1. Figure 5 : COSMOS results on HWS desert data
2. Figure 6 : COSMOS results on HWS desert data
3. Figure 7 : Binning of whiff statistics, in depth flow diagram for concentration modeling and intermittency modeling.