plotair 0.1.1__py3-none-any.whl → 0.2.1__py3-none-any.whl

plotair/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.1"

plotair/config.toml

@@ -0,0 +1,67 @@
+[data]
+max_missing_samples = 4
+
+[plot]
+size = [15, 10]
+font_family = 'Noto Sans'  # Set to '' to use default system font
+font_scale = 1.8
+grid2_opacity = 0.7        # 0 is fully transparent and 1 is fully opaque
+grid1_line_style = '-'     # Options: '-', '--', ':' and '-.'
+grid2_line_style = '--'
+default_line_style = '-'
+limit_zone_opacity = 0.075
+limit_line_opacity = 0.7
+limit_line_style = '--'
+"pm2.5_line_style" = '-'
+"pm10_line_style" = '-.'
+date_rotation = 30
+
+# Options: 'best', 'upper right', 'upper left', 'lower left', 'lower right',
+# 'center left', 'center right', 'lower center', 'upper center', 'center'
+legend_location = 'upper left'
+
+[axis_ranges]
+co2 = [0, 2000]
+humidity = [0, 80]
+temp = [0, 80]
+tvoc = [0, 500]
+co = [0, 50]
+form = [0, 50]
+"pm2.5" = [0, 70]
+"pm10" = [0, 70]
+
+[labels]
+co2 = 'CO₂ (ppm)'
+temp = 'Température (°C)'
+humidity = 'Humidité (%)'
+tvoc = 'COVT (ppb)'
+tvoc_limit = 'Limite LEED, WELL et LBC'
+co = 'Monoxyde de carbone (ppm)'
+co_limit = 'Limite Environnement Canada'
+form = 'Formaldéhyde (ppb)'
+form_limit = 'Limite anomalie légère BBI'
+"pm2.5" = 'PM2.5 (µg/m³)'
+"pm2.5_limit" = 'Limite concentration moyenne annuelle PM2.5 OMS'
+"pm10" = 'PM10 (µg/m³)'
+"pm10_limit" = 'Limite concentration moyenne annuelle PM10 OMS'
+
+[limits]
+humidity = [40, 60]
+tvoc = 218  # ppb
+co = 5      # ppm
+form = 16   # ppb
+"pm2.5" = 10
+"pm10" = 50
+
+[colors]
+# See Matplotlib documentation for valid colors:
+# https://matplotlib.org/stable/gallery/color/named_colors.html
+co2 = 'tab:blue'
+tvoc = 'tab:purple'
+co = 'tab:cyan'
+form = 'tab:red'
+humidity = 'tab:green'
+temp = 'tab:orange'
+"pm2.5" = 'tab:orange'
+"pm10" = 'tab:green'
+

plotair/main.py

@@ -14,12 +14,17 @@ Licensed under the MIT License. See the LICENSE file for details.
 """
 
 # Standard library imports
-from datetime import datetime
+import argparse
+import csv
+import glob
 import logging
 import os
 import re
 import shutil
 import sys
+import tomllib
+from datetime import datetime
+from pathlib import Path
 
 # Third-party library imports
 import matplotlib.pyplot as plt
@@ -27,64 +32,208 @@ import numpy as np
 import pandas as pd
 import seaborn as sns
 
-# Configuration constants
-MIN_CSV_COLUMNS = 5  # Most rows have 5 columns
-MAX_CSV_COLUMNS = 6  # Some rows have 6 columns
-MAX_MISSING_SAMPLES = 4
-PLOT_FONT_SCALE = 1.4
-PLOT_WIDTH = 11
-PLOT_HEIGHT = 8.5
-CO2_LABEL = 'CO₂ (ppm)'
-HUMIDITY_LABEL = 'Humidité (%)'
-TEMP_LABEL = 'Température (°C)'
-Y1_AXIS_LABEL = 'CO₂ (ppm)'
-Y2_AXIS_LABEL_1 = 'Température (°C)' + '  '  # Spaces separate from humidity
-Y2_AXIS_LABEL_2 = '  ' + 'Humidité (%)'      # Spaces separate from temperature
-X_AXIS_ROTATION = 30
-HUMIDITY_ZONE_MIN = 40
-HUMIDITY_ZONE_MAX = 60
-HUMIDITY_ZONE_ALPHA = 0.075
-
-# 8000/4000/2000/1600 span for y1 axis work well with 80 span for y2 axis
-# 6000/3000/    /1200 span for y1 axis work well with 60 span for y2 axis
-Y1_AXIS_MIN_VALUE = 0
-Y1_AXIS_MAX_VALUE = 1200
-Y2_AXIS_MIN_VALUE = 10
-Y2_AXIS_MAX_VALUE = 70
-
-# See Matplotlib documentation for valid colors:
-# https://matplotlib.org/stable/gallery/color/named_colors.html
-CO2_COLOR = 'tab:blue'
-HUMIDITY_COLOR = 'tab:green'
-TEMP_COLOR = 'tab:orange'
+# Add project root to sys.path so script can be called directly w/o 'python3 -m'
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+# Local imports
+from plotair import __version__
+
+CONFIG = {}
 
 # Get a logger for this script
 logger = logging.getLogger(__name__)
 
 
 def main():
-    # sys.argv[0] is the script name, so arguments start from index 1
-    if len(sys.argv) < 2:
-        logger.error("No files were provided")
-        print(f"Usage: [python] {sys.argv[0]} <file1> <file2> ...")
+    parser = argparse.ArgumentParser()
+
+    parser.add_argument('filenames', nargs='+', metavar='FILE',
+                        help='sensor data file to process')
+    parser.add_argument('-a', '--all-dates', action='store_true',
+                        help='plot all dates (otherwise only latest sequence)')
+    parser.add_argument('-b', '--boxplot', action='store_true',
+                        help='generate boxplots along with text stats')
+    parser.add_argument('-m', '--merge', metavar='FIELD',
+                        help='merge field from file1 to file2, and output to file3')
+    parser.add_argument('-o', '--filter-outliers', action='store_true',
+                        help='filter out outliers from the plots')
+    parser.add_argument('--filter-multiplier', type=float, default=1.5, metavar='MULTIPLIER',
+                        help='multiplier for IQR outlier filtering (default: 1.5)')
+    parser.add_argument('-r', '--reset-config', action='store_true',
+                        help='reset configuration file to default')
+    parser.add_argument('-s', '--start-date', metavar='DATE',
+                        help='date at which to start the plot (YYYY-MM-DD)')
+    parser.add_argument('-S', '--stop-date', metavar='DATE',
+                        help='date at which to stop the plot (YYYY-MM-DD)')
+    parser.add_argument('-t', '--title',
+                        help='set the plot title')
+    parser.add_argument('-v', '--version', action='version', 
+                        version=f'%(prog)s {__version__}')
+
+    args = parser.parse_args()
+
+    try:
+        load_config(args.reset_config)
+    except FileNotFoundError as e:
+        print(f'Error: Failed to load config: {e}')
+        return
+
+    if args.merge:
+        field = args.merge
+        num_files = len(args.filenames)
+
+        if num_files != 3:
+            print('Error: Argument -m/--merge requires three file arguments')
+            return
+
+        file_format, df1, num_valid_rows1, num_invalid_rows = read_data(args.filenames[0])
+        file_format, df2, num_valid_rows2, num_invalid_rows = read_data(args.filenames[1])
+
+        if num_valid_rows1 <= 0 or num_valid_rows2 <= 0:
+            print('Error: At least one of the input files is unsupported')
+            return
+
+        temp_df = df1[['co2']]
+        df2 = pd.concat([df2, temp_df]).sort_index()
+        df2.to_csv(args.filenames[2], index=True)
+
     else:
-        for filename in sys.argv[1:]:
-            logger.info(f"Processing {filename}")
+        filenames = []
+
+        if sys.platform == "win32":
+            # On Windows, expand glob patterns (e.g. *.csv)
+            for pattern in args.filenames:
+                filenames.extend(glob.glob(pattern))
+        else:
+            # On Linux, use filenames as-is (no glob expansion needed)
+            filenames = args.filenames
+
+        for filename in filenames:
+            print(f'Processing {filename}')
             try:
-                df, valid, invalid = read_csv_data(filename)
-                if invalid > 0:
-                    logger.info(f"{invalid} invalid row(s) ignored")
-                df = delete_old_data(df)
-                generate_plot(df, filename)
+                file_format, df, num_valid_rows, num_invalid_rows = read_data(filename)
+
+                if num_valid_rows > 0:
+                    logger.debug(f'{num_valid_rows} valid row(s) read')
+                else:
+                    print('Error: Unsupported file format')
+                    return
+
+                if num_invalid_rows > 0:
+                    percent_ignored = round(num_invalid_rows / (num_valid_rows + num_invalid_rows) * 100)
+                    print(f'{num_invalid_rows} invalid row(s) ignored ({percent_ignored}%)')
+
+                if not args.all_dates:
+                    df = delete_old_data(df, args.start_date, args.stop_date)
+
+                generate_stats(df, filename, args.boxplot)
+
+                if file_format == 'plotair':
+                    generate_plot(df, filename, args.title, suffix='cht',
+                             series1='co2', series2='humidity', series3='temp',
+                             filter_outliers=args.filter_outliers,
+                             filter_multiplier=args.filter_multiplier)
+                elif file_format == 'visiblair_d':
+                    generate_plot(df, filename, args.title, suffix='cht',
+                             series1='co2', series2='humidity', series3='temp',
+                             filter_outliers=args.filter_outliers,
+                             filter_multiplier=args.filter_multiplier)
+                elif file_format == 'visiblair_e':
+                    generate_plot(df, filename, args.title, suffix='cht',
+                             series1='co2', series2='humidity', series3='temp',
+                             filter_outliers=args.filter_outliers,
+                             filter_multiplier=args.filter_multiplier)
+                    generate_plot(df, filename, args.title, suffix='pm',
+                             series1=None, series2='pm2.5', series3='pm10',
+                             filter_outliers=args.filter_outliers,
+                             filter_multiplier=args.filter_multiplier)
+                elif file_format == 'graywolf_ds':
+                    generate_plot(df, filename, args.title, suffix='ht',
+                             series1=None, series2='humidity', series3='temp',
+                             filter_outliers=args.filter_outliers,
+                             filter_multiplier=args.filter_multiplier)
+                    generate_plot(df, filename, args.title, suffix='vcf',
+                             series1='tvoc', series2='form', series3='co',
+                             filter_outliers=args.filter_outliers,
+                             filter_multiplier=args.filter_multiplier)
             except Exception as e:
-                logger.exception(f"Unexpected error: {e}")
+                print(f'Error: Unexpected error: {e}')
+
+
+def detect_file_format(filename):
+    file_format = None
+    visiblair_d_num_col = (5, 6)  # Most rows have 5 columns but some have 6
+    visiblair_e_num_col = (21, 21)
+    graywolf_ds_num_col = (7, 7)
+
+    # Some files begin with the '\ufeff' character (Byte Order Mark / BOM).
+    # This breaks the first field detection. Use 'utf-8-sig' instead of 'utf-8'
+    # to automatically handle BOM.
+    with open(filename, 'r', newline='', encoding='utf-8-sig') as file:
+        reader = csv.reader(file)
+        first_line = next(reader)
+        num_fields = len(first_line)
+
+        if first_line[0] == 'date':
+            file_format = 'plotair'
+        elif visiblair_d_num_col[0] <= num_fields <= visiblair_d_num_col[1]:
+            file_format = 'visiblair_d'
+        elif (visiblair_e_num_col[0] <= num_fields <= visiblair_e_num_col[1] and
+              first_line[1] == 'Timestamp'):
+            file_format = 'visiblair_e'
+        elif (graywolf_ds_num_col[0] <= num_fields <= graywolf_ds_num_col[1] and
+              first_line[0] == 'Date Time'):
+            file_format = 'graywolf_ds'
+        
+    logger.debug(f'File format: {file_format}')
+    
+    return file_format
 
 
-def read_csv_data(filename):
-    valid_rows = []
+def read_data(filename):
+    file_format = detect_file_format(filename)
+    df = pd.DataFrame()
+    num_valid_rows = 0
+    num_invalid_rows = 0
+
+    if file_format == 'plotair':
+        df, num_valid_rows, num_invalid_rows = read_data_plotair(filename)
+    elif file_format == 'visiblair_d':
+        df, num_valid_rows, num_invalid_rows = read_data_visiblair_d(filename)
+    elif file_format == 'visiblair_e':
+        df, num_valid_rows, num_invalid_rows = read_data_visiblair_e(filename)
+    elif file_format == 'graywolf_ds':
+        df, num_valid_rows, num_invalid_rows = read_data_graywolf_ds(filename)
+
+    df = df.sort_index()  # Sort in case some dates are not in order
+
+    return file_format, df, num_valid_rows, num_invalid_rows
+
+
+def read_data_plotair(filename):
     num_valid_rows = 0
     num_invalid_rows = 0
 
+    # Read the CSV file into a DataFrame
+    df = pd.read_csv(filename)
+
+    # Convert the 'date' column to pandas datetime objects
+    df['date'] = pd.to_datetime(df['date'], format='%Y-%m-%d %H:%M:%S')
+
+    df = df.set_index('date')
+    num_valid_rows = len(df)
+
+    return df, num_valid_rows, num_invalid_rows
+
+
+def read_data_visiblair_d(filename):
+    df = pd.DataFrame()
+    num_valid_rows = 0
+    num_invalid_rows = 0
+    valid_rows = []
+
     # Read the file line by line instead of using pandas read_csv function.
     # This is less concise but allows for more control over data validation.
     with open(filename, 'r') as f:
@@ -92,9 +241,9 @@ def read_csv_data(filename):
             line = line.strip()
             fields = line.split(',')
             
-            if len(fields) < MIN_CSV_COLUMNS or len(fields) > MAX_CSV_COLUMNS:
+            if not (5 <= len(fields) <= 6):
                 # Skip lines with an invalid number of columns
-                logger.debug(f"Skipping line (number of columns): {line}")
+                #logger.debug(f'Skipping line (number of columns): {line}')
                 num_invalid_rows += 1
                 continue
                 
@@ -102,131 +251,445 @@ def read_csv_data(filename):
                 # Convert each field to its target data type
                 parsed_row = {
                     'date': pd.to_datetime(fields[0], format='%Y-%m-%d %H:%M:%S'),
-                    'co2': np.uint16(fields[1]),           # 0 to 10,000 ppm
-                    'temperature': np.float32(fields[2]),  # -40 to 70 °C
-                    'humidity': np.uint8(fields[3])        # 0 to 100% RH
+                    'co2': np.uint16(fields[1]),     # 0 to 10,000 ppm
+                    'temp': np.float32(fields[2]),   # -40 to 70 °C
+                    'humidity': np.uint8(fields[3])  # 0 to 100% RH
                 }
                 # If conversion succeeds, add the parsed row to the list
-                num_valid_rows += 1
                 valid_rows.append(parsed_row)
                 
             except (ValueError, TypeError) as e:
                 # Skip lines with conversion errors
-                logger.debug(f"Skipping line (conversion error): {line}")
+                #logger.debug(f'Skipping line (conversion error): {line}')
                 num_invalid_rows += 1
                 continue
 
         # Create the DataFrame from the valid rows
         df = pd.DataFrame(valid_rows)
         df = df.set_index('date')
-        df = df.sort_index()  # Sort in case some dates are not in order
+        num_valid_rows = len(df)
 
     return df, num_valid_rows, num_invalid_rows
 
 
-def delete_old_data(df):
-    """
-    Iterate backwards through the samples to find the first time gap larger
-    than the sampling interval. Then return only the latest data sequence.
-    """
-    sampling_interval = None
-    next_date = df.index[-1]
-
-    for date in reversed(list(df.index)):
-        current_date = date
-
-        if current_date != next_date:
-            if sampling_interval is None:
-                sampling_interval = next_date - current_date
-            else:
-                current_interval = next_date - current_date
-
-                if (current_interval / sampling_interval) > MAX_MISSING_SAMPLES:
-                    # This sample is from older sequence, keep only more recent
-                    df = df[df.index >= next_date]
-                    break
-        
-        next_date = current_date
-        
+def read_data_visiblair_e(filename):
+    num_valid_rows = 0
+    num_invalid_rows = 0
+
+    # Read the CSV file into a DataFrame
+    df = pd.read_csv(filename)
+
+    # Rename the columns
+    df.columns = ['uuid', 'date', 'co2', 'humidity', 'temp', 'pm0.1',
+                  'pm0.3', 'pm0.5', 'pm1', 'pm2.5', 'pm5', 'pm10', 'pressure',
+                  'voc_index', 'firmware', 'model', 'pcb', 'display_rate',
+                  'is_charging', 'is_ac_in', 'batt_voltage']
+
+    # Convert the 'date' column to pandas datetime objects
+    df['date'] = pd.to_datetime(df['date'], format='%Y-%m-%d %H:%M:%S')
+
+    df = df.set_index('date')
+    num_valid_rows = len(df)
+
+    return df, num_valid_rows, num_invalid_rows
+
+
+def read_data_graywolf_ds(filename):
+    num_valid_rows = 0
+    num_invalid_rows = 0
+
+    # Read the CSV file into a DataFrame
+    df = pd.read_csv(filename)
+
+    # Rename the columns
+    df.columns = ['date', 'tvoc', 'co', 'form', 'humidity', 'temp', 'filename']
+
+    # Convert the 'date' column to pandas datetime objects
+    df['date'] = pd.to_datetime(df['date'], format='%d-%b-%y %I:%M:%S %p')
+
+    # Convert 'form' column to string, replace '< LOD' with '0', and then convert to integer
+    df['form'] = df['form'].astype(str).str.replace('< LOD', '10').astype(int)
+
+    df = df.set_index('date')
+    num_valid_rows = len(df)
+
+    return df, num_valid_rows, num_invalid_rows
+
+
+def delete_old_data(df, start_date = None, stop_date = None):
+    if not start_date and not stop_date:
+        # Iterate backwards through the samples to find the first time gap larger
+        # than the sampling interval. Then return only the latest data sequence.
+        sampling_interval = None
+        next_date = df.index[-1]
+
+        for date in reversed(list(df.index)):
+            current_date = date
+
+            if current_date != next_date:
+                if sampling_interval is None:
+                    sampling_interval = next_date - current_date
+                else:
+                    current_interval = next_date - current_date
+
+                    if (current_interval / sampling_interval) > CONFIG['data']['max_missing_samples']:
+                        # This sample is from older sequence, keep only more recent
+                        df = df[df.index >= next_date]
+                        break
+
+            next_date = current_date
+
+    else:
+        # Keep only the data range to be plotted (use pandas dates types)
+        if start_date:
+            sd = pd.Timestamp(start_date)
+            df = df[df.index >= sd]
+        if stop_date:
+            sd = pd.Timestamp(stop_date)
+            df = df[df.index <= sd]
+
     return df
     
 
-def generate_plot(df, filename):
+class DataSeries:
+    def __init__(self, name=''):
+        # y_range could be replaced by y_min and y_max
+        self.name = name
+        self.label = CONFIG['labels'].get(self.name)
+        self.color = CONFIG['colors'].get(self.name)
+        self.y_range = CONFIG['axis_ranges'].get(self.name)  # min/max tuple, e.g. (0, 100)
+        self.limit = CONFIG['limits'].get(self.name)  # single value or min/max tuple
+        self.limit_label = CONFIG['labels'].get(self.name + '_limit')
+        self.linestyle = CONFIG['plot'].get(self.name + '_line_style')
+
+
+def generate_plot(df, filename, title, suffix='',
+                  series1=None, series2=None, series3=None,
+                  filter_outliers=False, filter_multiplier=None):
     # The dates must be in a non-index column
     df = df.reset_index()
-
+    
+    # Get each series configuration
+    ds1 = DataSeries(name=series1) if series1 else None
+    ds2 = DataSeries(name=series2) if series2 else None
+    ds3 = DataSeries(name=series3) if series3 else None
+    
     # Set a theme and scale all fonts
-    sns.set_theme(style='whitegrid', font_scale=PLOT_FONT_SCALE)
+    sns.set_theme(style='whitegrid', font_scale=CONFIG['plot']['font_scale'])
+
+    ff = CONFIG['plot']['font_family']
+    if ff != '': plt.rcParams['font.family'] = ff
 
     # Set up the matplotlib figure and axes
-    fig, ax1 = plt.subplots(figsize=(PLOT_WIDTH, PLOT_HEIGHT))
+    fig, ax1 = plt.subplots(figsize=CONFIG['plot']['size'])
     ax2 = ax1.twinx()  # Secondary y axis
 
-    # Plot the data series
-    sns.lineplot(data=df, x='date', y='co2', ax=ax1, color=CO2_COLOR,
-                 label=CO2_LABEL, legend=False)
-    sns.lineplot(data=df, x='date', y='humidity', ax=ax2, color=HUMIDITY_COLOR,
-                 label=HUMIDITY_LABEL, legend=False)
-    sns.lineplot(data=df, x='date', y='temperature', ax=ax2, color=TEMP_COLOR,
-                 label=TEMP_LABEL, legend=False)
+    # TODO: add functions for repetitive code
+
+    # Plot series #1 main line
+    if ds1:
+        if ds1.linestyle:
+            linestyle = ds1.linestyle
+        else:
+            linestyle = CONFIG['plot']['default_line_style']
+
+        if filter_outliers:
+            df1 = remove_outliers_iqr(df, ds1.name, multiplier=filter_multiplier)
+        else:
+            df1 = df[df[ds1.name] != 0]  # Only filter out zero values
+
+        sns.lineplot(data=df1, x='date', y=ds1.name, ax=ax1, color=ds1.color,
+                     label=ds1.label, legend=False, linestyle=linestyle)
+
+        # Display series #1 limit line or zone
+        if ds1.limit and not isinstance(ds1.limit, list):
+            # Plot the limit line
+            line = ax1.axhline(y=ds1.limit, color=ds1.color, label=ds1.limit_label,
+                               linestyle=CONFIG['plot']['limit_line_style'])
+            line.set_alpha(CONFIG['plot']['limit_line_opacity'])
+
+        if ds1.limit and isinstance(ds1.limit, list):
+            # Set the background color of the limit zone
+            hmin, hmax = ds1.limit
+            ax1.axhspan(ymin=hmin, ymax=hmax, facecolor=ds1.color,
+                        alpha=CONFIG['plot']['limit_zone_opacity'])
+
+    # Plot series #2 main line
+    if ds2.linestyle:
+        linestyle = ds2.linestyle
+    else:
+        linestyle = CONFIG['plot']['default_line_style']
+
+    if filter_outliers:
+        df2 = remove_outliers_iqr(df, ds2.name, multiplier=filter_multiplier)
+    else:
+        df2 = df[df[ds2.name] != 0]  # Only filter out zero values
+
+    sns.lineplot(data=df2, x='date', y=ds2.name, ax=ax2, color=ds2.color,
+                 label=ds2.label, legend=False, linestyle=linestyle)
+
+    # Display series #2 limit line or zone
+    if ds2.limit and not isinstance(ds2.limit, list):
+        # Plot the limit line
+        line = ax2.axhline(y=ds2.limit, color=ds2.color, label=ds2.limit_label,
+                           linestyle=CONFIG['plot']['limit_line_style'])
+        line.set_alpha(CONFIG['plot']['limit_line_opacity'])
+
+    if ds2.limit and isinstance(ds2.limit, list):
+        # Set the background color of the limit zone
+        hmin, hmax = ds2.limit
+        ax2.axhspan(ymin=hmin, ymax=hmax, facecolor=ds2.color,
+                    alpha=CONFIG['plot']['limit_zone_opacity'])
+
+    # Plot series #3 main line
+    if ds3.linestyle:
+        linestyle = ds3.linestyle
+    else:
+        linestyle = CONFIG['plot']['default_line_style']
+
+    # TODO: Do we still want to scale the CO data series?
+    #co_scale = 10
+    #df['co_scaled'] = df['co'] * co_scale
+
+    if filter_outliers:
+        df3 = remove_outliers_iqr(df, ds3.name, multiplier=filter_multiplier)
+    else:
+        df3 = df[df[ds3.name] != 0]  # Only filter out zero values
+
+    sns.lineplot(data=df3, x='date', y=ds3.name, ax=ax2, color=ds3.color,
+                 label=ds3.label, legend=False, linestyle=linestyle)
+
+    # Plot series #3 limit line
+    if ds3.limit and not isinstance(ds3.limit, list):
+        # Plot the limit line
+        line = ax2.axhline(y=ds3.limit, color=ds3.color, label=ds3.limit_label,
+                           linestyle=CONFIG['plot']['limit_line_style'])
+        line.set_alpha(CONFIG['plot']['limit_line_opacity'])
+
+    if ds3.limit and isinstance(ds3.limit, list):
+        # Set the background color of the limit zone
+        hmin, hmax = ds3.limit
+        ax2.axhspan(ymin=hmin, ymax=hmax, facecolor=ds3.color,
+                    alpha=CONFIG['plot']['limit_zone_opacity'])
 
     # Set the ranges for both y axes
-    ax1.set_ylim(Y1_AXIS_MIN_VALUE, Y1_AXIS_MAX_VALUE)  # df['co2'].max() * 1.05
-    ax2.set_ylim(Y2_AXIS_MIN_VALUE, Y2_AXIS_MAX_VALUE)
+    if ds1:
+        y1min, y1max = ds1.y_range
+        ax1.set_ylim(y1min, y1max)
+
+    y2min, y2max = ds2.y_range
+    y3min, y3max = ds3.y_range
+
+    if y2min != y3min or y2max != y3max:
+        print(f'Warning: Axis ranges differ for {series2} and {series3}, using largest range')
+
+    ax2.set_ylim(min(y2min, y3min), max(y2max, y3max))
 
     # Add a grid for the x axis and the y axes
     # This is already done if using the whitegrid theme
-    #ax1.grid(axis='x', alpha=0.7)  
-    #ax1.grid(axis='y', alpha=0.7)
-    ax2.grid(axis='y', alpha=0.7, linestyle='dashed')
-
-    # Set the background color of the humidity comfort zone
-    ax2.axhspan(ymin=HUMIDITY_ZONE_MIN, ymax=HUMIDITY_ZONE_MAX,
-                facecolor=HUMIDITY_COLOR, alpha=HUMIDITY_ZONE_ALPHA)
+    #ax1.grid(axis='x', alpha=CONFIG['plot']['grid_opacity'])
+    #ax1.grid(axis='y', alpha=CONFIG['plot']['grid_opacity'])
+    ax2.grid(axis='y', alpha=CONFIG['plot']['grid2_opacity'], linestyle=CONFIG['plot']['grid2_line_style'])
 
     # Customize the plot title, labels and ticks
-    ax1.set_title(get_plot_title(filename))
-    ax1.tick_params(axis='x', rotation=X_AXIS_ROTATION)
-    ax1.tick_params(axis='y', labelcolor=CO2_COLOR)
+    ax1.set_title(get_plot_title(title, filename))
+    ax1.tick_params(axis='x', rotation=CONFIG['plot']['date_rotation'])
+    if ds1:
+        ax1.tick_params(axis='y', labelcolor=ds1.color)
+        ax1.set_ylabel(ds1.label, color=ds1.color)
     ax1.set_xlabel('')
-    ax1.set_ylabel(Y1_AXIS_LABEL, color=CO2_COLOR)
     ax2.set_ylabel('')  # We will manually place the 2 parts in different colors
 
     # Define the position for the center of the right y axis label
+    bottom_label = ds3.label + '  '
+    top_label = '  ' + ds2.label
     x = 1.07  # Slightly to the right of the axis
-    y = 0.5   # Vertically centered
+    y = get_label_center(bottom_label, top_label)   # Vertically centered
 
     # Place the first (bottom) part of the label
-    ax2.text(x, y, Y2_AXIS_LABEL_1, transform=ax2.transAxes,
-             color=TEMP_COLOR, rotation='vertical', ha='center', va='top')
+    ax2.text(x, y, bottom_label, transform=ax2.transAxes,
+             color=ds3.color, rotation='vertical',
+             ha='center', va='top')
 
     # Place the second (top) part of the label
-    ax2.text(x, y, Y2_AXIS_LABEL_2, transform=ax2.transAxes,
-            color=HUMIDITY_COLOR, rotation='vertical', ha='center', va='bottom')
+    ax2.text(x, y, top_label, transform=ax2.transAxes,
+            color=ds2.color, rotation='vertical',
+            ha='center', va='bottom')
 
     # Create a combined legend
     lines1, labels1 = ax1.get_legend_handles_labels()
     lines2, labels2 = ax2.get_legend_handles_labels()
-    ax1.legend(lines1 + lines2, labels1 + labels2, loc='upper left')
+    labels1 = remove_units_from_labels(labels1)
+    labels2 = remove_units_from_labels(labels2)
+    ax1.legend(lines1 + lines2, labels1 + labels2,
+               loc=CONFIG['plot']['legend_location'])
+
+    if not ds1:
+        # Remove the left y-axis elements from ax1
+        ax1.grid(axis='y', visible=False)
+        ax1.spines['left'].set_visible(False)
+        ax1.tick_params(axis='y', left=False, labelleft=False)
 
     # Adjust the plot margins to make room for the labels
     plt.tight_layout()
 
     # Save the plot as a PNG image
-    plt.savefig(get_png_filename(filename))
+    # TODO: auto build the plot suffix from the 1st char of each series?
+    plt.savefig(get_plot_filename(filename, f'-{suffix}'))
     plt.close()
 
 
-def get_plot_title(filename):
-    match = re.search(r'^(\d+\s*-\s*)?(.*)\.[a-zA-Z]+$', filename)
-    plot_title = match.group(2) if match else filename
-    plot_title = plot_title.capitalize()
+def remove_units_from_labels(labels):
+    return [re.sub(r' \([^)]*\)', '', label) for label in labels]
+
+
+def remove_outliers_iqr(df, column, multiplier=None):
+    """
+    Remove outliers using Interquartile Range (IQR) method
+    multiplier = 1.0: Tight bounds, more outliers removed
+    multiplier = 1.5: Standard bounds, moderate outliers removed  
+    multiplier = 2.0: Wide bounds, fewer outliers removed
+    """
+    if multiplier == None:
+        multiplier = 1.5  # Default value
+        
+    Q1 = df[column].quantile(0.25)
+    Q3 = df[column].quantile(0.75)
+    IQR = Q3 - Q1
+    lower_bound = Q1 - multiplier * IQR
+    upper_bound = Q3 + multiplier * IQR
+    
+    return df[(df[column] >= lower_bound) & (df[column] <= upper_bound)]
+
+
+# WARNING: Untested function
+def remove_outliers_zscore(df, column, threshold=3):
+    # from scipy import stats ?
+    z_scores = np.abs(stats.zscore(df[column]))
+    return df[z_scores < threshold]
+
+
+# WARNING: Untested function
+def remove_outliers_std(df, column, n_std=2):
+    mean = df[column].mean()
+    std = df[column].std()
+    lower_bound = mean - n_std * std
+    upper_bound = mean + n_std * std
+    
+    return df[(df[column] >= lower_bound) & (df[column] <= upper_bound)]
+
+
+# WARNING: Untested function
+def remove_outliers_percentile(df, column, lower_percentile=5, upper_percentile=95):
+    lower_bound = df[column].quantile(lower_percentile/100)
+    upper_bound = df[column].quantile(upper_percentile/100)
+    
+    return df[(df[column] >= lower_bound) & (df[column] <= upper_bound)]
+
+
+def get_label_center(bottom_label, top_label):
+    # Return a value between 0 and 1 to estimate where to center the label
+    # Divider optimized for 11x8.5 plot size, but not as good for 15x10
+    fs = CONFIG['plot']['font_scale']
+    divider = 72 * fs**2 - 316 * fs + 414  # Tested for fs between 0.8 and 2
+    center = 0.5 + ((len(bottom_label) - len(top_label)) / divider)
+    return center
+
+
+def generate_stats(df, filename, boxplot=False):
+    summary = df.describe()
+
+    with open(get_stats_filename(filename), 'w') as file:
+        file.write(summary.to_string())
+
+    if boxplot:
+        for column in summary.columns.tolist():
+            box = sns.boxplot(data=df, y=column)
+            plt.savefig(get_boxplot_filename(filename, f'-{column}'))
+            plt.close()
+
+
+def load_config(reset_config = False):
+    global CONFIG
+
+    app_name = 'plotair'
+    config_file = 'config.toml'
+
+    config_dir = get_config_dir(app_name)
+    user_config_file = config_dir / config_file
+    default_config_file = PROJECT_ROOT / app_name / config_file
+
+    if not user_config_file.exists() or reset_config:
+        if default_config_file.exists():
+            shutil.copy2(default_config_file, user_config_file)
+            logger.debug(f'Config initialized at {user_config_file}')
+        else:
+            raise FileNotFoundError(f'Default config missing at {default_config_file}')
+    else:
+        logger.debug(f'Found config file at {user_config_file}')
+
+    with open(user_config_file, 'rb') as f:
+        CONFIG = tomllib.load(f)
+
+
+def get_config_dir(app_name):
+    if sys.platform == "win32":
+        # Windows: Use %APPDATA% (%USERPROFILE%\AppData\Roaming)
+        config_dir = Path(os.environ.get("APPDATA", "")) / app_name
+    elif sys.platform == "darwin":
+        # macOS: Use ~/Library/Preferences
+        config_dir = Path.home() / "Library" / "Preferences" / app_name
+    else:
+        # Linux and other Unix-like: Use ~/.config or XDG_CONFIG_HOME if set
+        config_home = os.environ.get("XDG_CONFIG_HOME", "")
+        if config_home:
+            config_dir = Path(config_home) / app_name
+        else:
+            config_dir = Path.home() / ".config" / app_name
+    
+    # Create the directory if it doesn't exist
+    config_dir.mkdir(parents=True, exist_ok=True)
+    
+    return config_dir
+
+
+def get_plot_title(title, filename):
+    if title:
+        plot_title = title
+    else:
+        stem = Path(filename).stem
+        match = re.search(r'^(\d+\s*-\s*)?(.*)$', stem)
+        plot_title = match.group(2) if match else stem
+
+    # Capitalize only the first character
+    if plot_title: plot_title = plot_title[0].upper() + plot_title[1:]
+
     return plot_title
 
 
-def get_png_filename(filename):
-    root, ext = os.path.splitext(filename)
-    return f"{root}.png"
+def get_plot_filename(filename, suffix = ''):
+    p = Path(filename)
+    return f'{p.parent}/{p.stem}{suffix}.png'
+
+
+def get_boxplot_filename(filename, suffix = ''):
+    p = Path(filename)
+    return f'{p.parent}/{p.stem}-boxplot{suffix}.png'
+
+
+def get_stats_filename(filename):
+    p = Path(filename)
+    return f'{p.parent}/{p.stem}-stats.txt'
+
+
+def log_data_frame(df, description = ''):
+    """ This function is used only for debugging. """
+    logger.debug(f'DataFrame {description}\n{df}')
+    #logger.debug(f'DataFrame index data type: {df.index.dtype}')
+    #logger.debug(f'DataFrame index class: {type(df.index)}')
+    #logger.debug(f'DataFrame columns data types\n{df.dtypes}')
+    #logger.debug(f'DataFrame statistics\n{df.describe()}')  # Mean, min, max...
+    #sys.exit()
 
 
 if __name__ == '__main__':
@@ -235,6 +698,6 @@ if __name__ == '__main__':
                         format='%(levelname)s - %(message)s')
     
     # Configure this script's logger
-    logger.setLevel(logging.INFO)
+    logger.setLevel(logging.DEBUG)
 
     main()

plotair-0.2.1.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: plotair
+Version: 0.2.1
+Summary: Generate CO₂, humidity and temperature plots from VisiblAir sensor CSV files.
+Project-URL: Repository, https://github.com/monsieurlinux/plotair
+Author-email: Monsieur Linux <info@mlinux.ca>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,data-analysis,data-science,iot,monitoring,python,terminal,visualization
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: pandas<3.0.0,>=2.0.0
+Requires-Dist: seaborn<1.0.0,>=0.13.2
+Description-Content-Type: text/markdown
+
+![Air quality plot](https://github.com/monsieurlinux/plotair/raw/main/img/cuisine.png)
+
+# PlotAir
+
+[![PyPI][pypi-badge]][pypi-link]
+[![License][license-badge]][license-link]
+
+PlotAir is a Python script that processes one or more CSV files containing [VisiblAir][visiblair-link] sensor data. For each file, it reads the data into a [pandas][pandas-link] DataFrame, ignores incorrectly formatted lines, keeps only the most recent data sequence, and generates a [Seaborn][seaborn-link] plot saved as a PNG file with the same base name as the input CSV.
+
+## Dependencies
+
+PlotAir requires the following external libraries:
+
+* **[pandas][pandas-link]**: Used for data manipulation and analysis.
+* **[seaborn][seaborn-link]**: Used for creating plots.
+
+These libraries and their sub-dependencies will be installed automatically when you install PlotAir.
+
+## Installation
+
+It is recommended to install PlotAir within a [virtual environment][venv-link] to avoid conflicts with system packages. Some Linux distributions enforce this. You can use `pipx` to handle the virtual environment automatically, or create one manually and use `pip`.
+
+### Installation with `pipx`
+
+`pipx` installs PlotAir in an isolated environment and makes it available globally.
+
+**1. Install `pipx`:**
+
+*   **Linux (Debian / Ubuntu / Mint):**
+    
+    ```bash
+    sudo apt install pipx
+    pipx ensurepath
+    ```
+*   **Linux (Other) / macOS:**
+    
+    ```bash
+    python3 -m pip install --user pipx
+    python3 -m pipx ensurepath
+    ```
+*   **Windows:**
+    
+    ```bash
+    python -m pip install --user pipx
+    python -m pipx ensurepath
+    ```
+
+You may need to reopen your terminal for the PATH changes to take effect. If you encounter a problem, please refer to the official [pipx documentation][pipx-link].
+
+**2. Install PlotAir:**
+
+```bash
+pipx install plotair
+```
+
+### Installation with `pip`
+
+If you prefer to manage the virtual environment manually, you can create and activate it by following this [tutorial][venv-link]. Then install PlotAir:
+
+```bash
+pip install plotair
+```
+
+## Deployments
+
+View all releases on:
+
+- **[PyPI Releases][pypi-releases]**
+- **[GitHub Releases][github-releases]**
+
+## Usage
+
+### Basic Usage
+
+```bash
+plotair [arguments] FILE [FILE ...]
+```
+
+### Command-Line Arguments
+
+None for now.
+
+## Configuration
+
+When you run PlotAir for the first time, a `config.toml` file is automatically created. Its location depends on your operating system (typical paths are listed below):
+
+*   **Linux:** `~/.config/plotair`
+*   **macOS:** `~/Library/Preferences/plotair`
+*   **Windows:** `C:/Users/YourUsername/AppData/Roaming/plotair`
+
+You can edit this file to customize various settings. Common customizations include translating plot labels into different languages or modifying the line colors.
+
+## License
+
+Copyright (c) 2026 Monsieur Linux
+
+This project is licensed under the MIT License. See the LICENSE file for details.
+
+## Acknowledgements
+
+Thanks to the creators and contributors of the [pandas][pandas-link] and [seaborn][seaborn-link] libraries, and to the developer of the great [VisiblAir][visiblair-link] air quality monitors and CO₂ sensors. Thanks also to the founder of [Bâtiments vivants][batiments-link] for the idea of this script.
+
+[batiments-link]: https://batimentsvivants.ca/
+[github-releases]: https://github.com/monsieurlinux/plotair/releases
+[license-badge]: https://img.shields.io/pypi/l/plotair.svg
+[license-link]: https://github.com/monsieurlinux/plotair/blob/main/LICENSE
+[pandas-link]: https://github.com/pandas-dev/pandas
+[pipx-link]: https://github.com/pypa/pipx
+[pypi-badge]: https://img.shields.io/pypi/v/plotair.svg
+[pypi-link]: https://pypi.org/project/plotair/
+[pypi-releases]: https://pypi.org/project/plotair/#history
+[seaborn-link]: https://github.com/mwaskom/seaborn
+[venv-link]: https://docs.python.org/3/tutorial/venv.html
+[visiblair-link]: https://visiblair.com/

plotair-0.2.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+plotair/__init__.py,sha256=HfjVOrpTnmZ-xVFCYSVmX50EXaBQeJteUHG-PD6iQs8,22
+plotair/config.toml,sha256=gj3qGI-LFWiXVIqKmlwLvabGjgLCOyj2iH7XLjn1AsA,1661
+plotair/main.py,sha256=zU4dShx-D8ucIiFcuNBaM-JIsYNX-sDSXCNCh3MQd7w,26207
+plotair-0.2.1.dist-info/METADATA,sha256=wZURX8-d41UmgLdMK3kzMm68nVfM9AKjUUBLZ7xGzLU,4526
+plotair-0.2.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+plotair-0.2.1.dist-info/entry_points.txt,sha256=ekJAavHU_JAF9a66br_T4-Vni_OAyd7QX-tnVlsH8pY,46
+plotair-0.2.1.dist-info/licenses/LICENSE,sha256=Lb4o6Virnt4fVuYjZ_QO4qrvRUJqHe0MCkqVr_lncJo,1071
+plotair-0.2.1.dist-info/RECORD,,

plotair-0.1.1.dist-info/METADATA

@@ -1,94 +0,0 @@
-Metadata-Version: 2.4
-Name: plotair
-Version: 0.1.1
-Summary: Generate CO₂, humidity and temperature plots from VisiblAir sensor CSV files.
-Project-URL: Repository, https://github.com/monsieurlinux/plotair
-Author-email: Monsieur Linux <info@mlinux.ca>
-License-Expression: MIT
-License-File: LICENSE
-Keywords: cli,command-line,python,terminal,tui
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.9
-Requires-Dist: pandas<3.0.0,>=2.0.0
-Requires-Dist: seaborn>=0.13.2
-Description-Content-Type: text/markdown
-
-![Air quality plot](https://github.com/monsieurlinux/plotair/raw/main/img/cuisine.png)
-
-# PlotAir
-
-PlotAir is a Python script that processes one or more CSV files containing [VisiblAir](https://visiblair.com/) sensor data. For each file, it reads the data into a [pandas](https://github.com/pandas-dev/pandas) DataFrame, ignores incorrectly formatted lines, keeps only the most recent data sequence, and generates a [Seaborn](https://github.com/mwaskom/seaborn) plot saved as a PNG file with the same base name as the input CSV.
-
-## Dependencies
-
-PlotAir requires the following external libraries:
-
-* **[pandas](https://github.com/pandas-dev/pandas)**: Used for data manipulation and analysis.
-* **[seaborn](https://github.com/mwaskom/seaborn)**: Used for creating plots.
-
-These libraries and their sub-dependencies will be installed automatically when you install PlotAir.
-
-## Installation
-
-It is recommended to install PlotAir within a [virtual environment](https://docs.python.org/3/tutorial/venv.html) to avoid conflicts with system packages. Some Linux distributions enforce this. You can use `pipx` to handle the virtual environment automatically, or create one manually and use `pip`.
-
-### Installation with `pipx`
-
-`pipx` installs PlotAir in an isolated environment and makes it available globally.
-
-**1. Install `pipx`:**
-
-*   **Linux (Debian / Ubuntu / Mint):**
-    
-    ```bash
-    sudo apt update && sudo apt install pipx
-    ```
-*   **Linux (Other) / macOS:**
-    
-    ```bash
-    python3 -m pip install --user pipx
-    python3 -m pipx ensurepath
-    # Note: Close and restart your terminal after running ensurepath
-    ```
-*   **Windows:**
-    
-    ```bash
-    python -m pip install --user pipx
-    ```
-
-**2. Install PlotAir:**
-
-```bash
-pipx install plotair
-```
-
-### Installation with `pip`
-
-If you prefer to manage the virtual environment manually, you can create and activate it by following this [tutorial](https://docs.python.org/3/tutorial/venv.html). Then install PlotAir:
-
-```bash
-pip install plotair
-```
-
-## Usage
-
-### Basic Usage
-
-```bash
-plotair <file1> <file2> ...
-```
-
-### Command-Line Arguments
-
-None for now.
-
-## License
-
-Copyright (c) 2026 Monsieur Linux
-
-This project is licensed under the MIT License. See the LICENSE file for details.
-
-## Acknowledgements
-
-Thanks to the creators and contributors of the [pandas](https://github.com/pandas-dev/pandas) and [seaborn](https://github.com/mwaskom/seaborn) libraries, and to the developer of the great [VisiblAir](https://visiblair.com/) air quality monitors and CO₂ sensors. Thanks also to the founder of [Bâtiments vivants](https://batimentsvivants.ca/) for the idea of this script.

plotair-0.1.1.dist-info/RECORD

@@ -1,7 +0,0 @@
-plotair/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-plotair/main.py,sha256=_jrgIkSfo0P-9i6ZaozXqfkqrMzgUwDo84mtUB4guoI,8378
-plotair-0.1.1.dist-info/METADATA,sha256=STPe0wm4Ngqa6bv4yWjE_ooHtiaSEkBxw2cHjb1Etmo,3235
-plotair-0.1.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-plotair-0.1.1.dist-info/entry_points.txt,sha256=ekJAavHU_JAF9a66br_T4-Vni_OAyd7QX-tnVlsH8pY,46
-plotair-0.1.1.dist-info/licenses/LICENSE,sha256=Lb4o6Virnt4fVuYjZ_QO4qrvRUJqHe0MCkqVr_lncJo,1071
-plotair-0.1.1.dist-info/RECORD,,