MethaneSignalProcessor (MSP) is an open-source tool for processing high-frequency CH₄ (methane) concentration time-series acquired with floating chambers. The routine separates diffusive and ebullitive emission components, applies advanced signal correction, and exports numerical summaries together with graphical outputs.
MSP is designed to support automated, standardized, and reproducible analysis of aquatic methane signals, particularly those obtained with low-cost sensors under field conditions.
Main capabilities:
- Automated data cleaning and preprocessing
- Advanced digital filtering
- Adaptive peak detection for ebullition events
- Dual-branch correction with multi-scale refinement
- Regression-based diffusive flux estimation
- Structured export of numerical results and figures
MethaneSignalProcessor (MSP)
├── main.py # Main CLI entry point
├── inc/functions.py # Core processing logic
├── Raw data/ # Input .txt files
├── Processed data/ # Output data and figures
│ ├── data/ # Processed .csv files
│ ├── results/ # Text summaries (fluxes & bubbles)
│ └── plots/ # Output figures
├── example_outputs/ # Example outputs for reference
├── build_exe.bat # Script to build Windows executable
├── requirements.txt # Python dependencies
└── README.md # Project documentation
- Python ≥ 3.8
- pip (Python package manager)
To build the Windows executable, PyInstaller is required (handled automatically by build_exe.bat).
- Clone the repository:
git clone https://github.com/ACBonet/MethaneSignalProcessor.git
cd MethaneSignalProcessor- (Optional but recommended) Create a virtual environment:
python -m venv venv
source venv/bin/activate # Linux / macOS
venv\Scripts\activate # Windows- Install dependencies:
pip install -r requirements.txt- Run the processor:
python main.pyAfter compilation, simply double-click:
CH4Processor.exeor run it from the terminal.
The program will prompt you to:
- Process a single .txt file, or
- Process all .txt files located in the Raw data/ folder
Outputs are automatically written to the Processed data/ directory.
To generate the executable from source:
-
Install Python from https://www.python.org (ensure “Add Python to PATH” is checked)
-
Open the project folder
-
Double-click build_exe.bat (or run it from the terminal)
The executable CH4Processor.exe will be created. It expects the folders Raw data/ and Processed data/ to be located at the same level.
python main.py # Python usage
CH4Processor.exe # Executable usage- Load .txt files from Raw data/
- Apply filtering, peak detection, and correction
- Export results to Processed data/, including:
- Text summaries of diffusive flux segments
- Summary statistics of diffusive fluxes
- Ebullitive event metrics (counts, rates, relative contribution)
Saved in Processed data/plots/:
- Original vs processed signal with detected peaks
- Step-like representation of ebullitive events
- Linear fits on diffusive segments (with slope and R²)
Representative outputs generated by MSP can be previewed in the example_outputs/ folder. These examples illustrate the typical graphical and numerical results obtained after processing a CH₄ time-series.
A minimal working example is provided in the example_outputs/ folder to allow users to quickly verify correct installation and execution of the pipeline before processing their own data.
The following figures are produced automatically for each processed file:
Overlay of the original signal, corrected signal, and validated ebullitive peaks.
Step-like reconstruction of ebullitive contributions derived from validated peaks.
Linear regression fits applied to diffusive segments, including slope and coefficient of determination (R²).
These figures are also saved automatically for user data in Processed data/plots/.
The files provided in the example_outputs/ folder were generated by running MSP on representative CH₄ time-series acquired with floating chambers under field conditions.
To reproduce similar outputs using your own data:
- Place one or more input
.txtfiles in theRaw data/folder. - Run the processor:
python main.pyor, on Windows:
CH4Processor.exe- Select whether to process a single file or all files in the folder.
For each input file, MSP automatically generates:
- Graphical outputs in Processed data/plots/
- Numerical summaries in Processed data/results/
- Processed time-series files in Processed data/data/
The structure, content, and interpretation of these outputs are directly comparable to the examples shown in example_outputs/.
Each processed file generates a text report summarizing diffusive and ebullitive components. An example report is provided as:
- example_outputs/example_results.txt
This file contains a structured summary of the analysis, including:
- Diffusive Flux Segments ---
- Slope: 0.0427 ppm/s | R²: 0.923 | T: 23.0°C | P: 610.0 mmHg | Diffusive Flux: 1016.07 µmol/m²·h
- Slope: 0.1091 ppm/s | R²: 0.997 | T: 24.7°C | P: 610.0 mmHg | Diffusive Flux: 2578.50 µmol/m²·h
- Slope: 0.0155 ppm/s | R²: 0.990 | T: 26.1°C | P: 610.0 mmHg | Diffusive Flux: 365.23 µmol/m²·h
- Slope: 0.0432 ppm/s | R²: 0.987 | T: 26.2°C | P: 610.0 mmHg | Diffusive Flux: 1016.65 µmol/m²·h
- Slope: 0.0217 ppm/s | R²: 0.970 | T: 26.6°C | P: 610.0 mmHg | Diffusive Flux: 509.01 µmol/m²·h
- Slope: 0.0093 ppm/s | R²: 0.939 | T: 26.6°C | P: 610.0 mmHg | Diffusive Flux: 218.17 µmol/m²·h
- Slope: 0.0106 ppm/s | R²: 0.917 | T: 26.2°C | P: 610.0 mmHg | Diffusive Flux: 249.16 µmol/m²·h
--- Summary Statistics of Diffusive Fluxes (µmol/m²·h) ---
count 7.00
mean 850.40
std 832.12
min 218.17
25% 307.20
50% 509.01
75% 1,016.36
max 2,578.50
--- Summary of Ebullitive Events ---
Peak Analysis Interval: 10
Total Adjusted CH₄ Concentration (ppm): 6.48
Final CH₄ Concentration (ppm): 33.49
Relative Contribution of Ebullition (%): 19.34
Number of Bubbles: 6
Index of Bubbles: [39, 125, 162, 216, 270, 305]
Total Bubble Time (h): 0.028
Bubble Rate (bubbles/h): 213.4
Equivalent numerical reports are automatically generated for user-provided data in Processed data/result
Input .txt files must include:
- A time column (regularly sampled)
- A CH₄ concentration column (ppm)
- Optional temperature and pressure columns
By default, MSP expects column names such as time_s (time in seconds) and CH4_ppm (methane concentration in ppm), as defined in inc/functions.py.
Example input files are provided in the Raw data/ folder.
This error typically indicates that required Python packages are not installed.
- Ensure all dependencies are installed:
pip install -r requirements.txt- If you are using multiple Python versions, make sure pip corresponds to the same Python interpreter used to run MSP.
On some systems, Python is invoked as python3 instead of python.
- Try running MSP with:
python3 main.py- If this works, you may consistently use python3 instead of python.
If Python is not installed, download it from: https://www.python.org/downloads/
When using the Windows executable (CH4Processor.exe or main.py):
- Ensure that the folder Raw data/ is located in the same directory as the executable.
- Verify that input files use the .txt extension and are readable.
MSP assumes a specific structure for input files:
- A time column expressed in seconds
- A CH₄ concentration column expressed in ppm
By default, column names are expected to match those defined in inc/functions.py (e.g. time and methane concentration labels).
If your dataset uses different column names, sampling units, or additional variables, these can be adapted directly in functions.py prior to execution.
Several physical parameters required for flux calculation are defined in functions.py, including (but not limited to):
- Chamber volume
- Chamber footprint area
Users must update these parameters to match their experimental setup. They are not requested interactively at runtime in order to:
- Avoid repeated manual input when processing multiple files
- Ensure consistency across batch analyses
- Reduce the risk of user input errors during execution
This design choice prioritizes reproducibility and efficient batch processing.
- In signals with very low-amplitude fluctuations or short acquisition windows, MSP may not detect ebullitive peaks.
- This does not indicate a processing error, but rather the absence of statistically significant bubble-driven events.
- Users are encouraged to visually inspect the processed signal and consider the environmental context.
- Diffusive flux estimation assumes quasi-linear CH₄ accumulation between ebullition events.
- Rapid environmental changes (e.g. wind-induced turbulence, temperature shifts) may introduce non-linear behavior.
- Segments with low R² values are automatically excluded to ensure robustness of diffusive flux estimates.
- Verify input data formatting and consistent time sampling.
- Strong sensor noise or drift may affect peak detection reliability.
- While MSP includes adaptive filtering and correction steps, extremely noisy signals should be interpreted with caution.
- MSP is sensor-agnostic, but absolute flux values depend on sensor calibration, chamber geometry, and deployment conditions.
- When comparing results across sensors or sites, consistent preprocessing and calibration procedures are recommended.
- MSP is designed for time-series CH₄ data acquired with floating chambers.
- The pipeline assumes quasi-steady diffusive accumulation between ebullition events.
- Strong hydrodynamic forcing, rapid environmental transitions, or highly turbulent conditions may introduce non-linearities not captured by linear regression.
- MSP provides automated signal decomposition and relative flux estimates; absolute flux accuracy depends on sensor calibration, chamber geometry, and environmental conditions.
- Validation xagainst independent reference methods (e.g. GC-based measurements) should be considered when available.
This project is released as open-source.
If you use MSP in your work, please cite the associated publication https://doi.org/10.1016/J.ECOINF.2026.103781.