AeroViz 0.1.21__py3-none-any.whl

AeroViz/dataProcess/core/__init__.py

@@ -0,0 +1,272 @@
+import functools
+import pickle as pkl
+import warnings
+from datetime import datetime as dtm
+from pathlib import Path
+
+from pandas import concat
+
+# Ensure all deprecation warnings are displayed
+warnings.filterwarnings('always', category=DeprecationWarning)
+warnings.filterwarnings('always', category=FutureWarning)
+
+
+class Writer:
+    """
+    Base class for data output management with various file format support.
+
+    This class provides functionality to save processed data in multiple formats,
+    including pickle, Excel, and CSV. It handles file permission issues gracefully.
+
+    Parameters
+    ----------
+    path_out : str or Path, optional
+        Directory path where output files will be saved
+    excel : bool, default=True
+        Whether to save outputs as Excel files
+    csv : bool, default=False
+        Whether to save outputs as CSV files
+    """
+
+    def __init__(self, path_out=None, excel=True, csv=False):
+        self.path_out = Path(path_out) if path_out is not None else path_out
+        self.excel = excel
+        self.csv = csv
+
+    @staticmethod
+    def pre_process(_out):
+        """
+        Prepare data for output by ensuring proper index naming.
+
+        Parameters
+        ----------
+        _out : DataFrame or dict of DataFrames
+            Data to be prepared for output
+
+        Returns
+        -------
+        DataFrame or dict of DataFrames
+            Processed data with properly named index
+        """
+        if isinstance(_out, dict):
+            for _ky, _df in _out.items():
+                _df.index.name = 'time'
+        else:
+            _out.index.name = 'time'
+
+        return _out
+
+    def save_out(self, _nam, _out):
+        """
+        Save processed data to disk in specified formats.
+
+        Handles various output formats (pickle, Excel, CSV) and manages file
+        permission errors by prompting the user to close open files.
+
+        Parameters
+        ----------
+        _nam : str
+            Base name for the output files
+        _out : DataFrame or dict of DataFrames
+            Data to be saved
+        """
+        _check = True
+        while _check:
+            try:
+                if self.path_out is not None:
+                    self.path_out.mkdir(exist_ok=True, parents=True)
+                    with (self.path_out / f'{_nam}.pkl').open('wb') as f:
+                        pkl.dump(_out, f, protocol=pkl.HIGHEST_PROTOCOL)
+
+                    if self.excel:
+                        from pandas import ExcelWriter
+                        with ExcelWriter(self.path_out / f'{_nam}.xlsx') as f:
+                            if type(_out) == dict:
+                                for _key, _val in _out.items():
+                                    _val.to_excel(f, sheet_name=f'{_key}')
+                            else:
+                                _out.to_excel(f, sheet_name=f'{_nam}')
+
+                    if self.csv:
+                        if isinstance(_out, dict):
+                            _path_out = self.path_out / _nam
+                            _path_out.mkdir(exist_ok=True, parents=True)
+
+                            for _key, _val in _out.items():
+                                _val.to_csv(_path_out / f'{_key}.csv')
+                        else:
+                            _out.to_csv(self.path_out / f'{_nam}.csv')
+
+                _check = False
+
+            except PermissionError as _err:
+                print('\n', _err)
+                input('\t\t\33[41m Please Close The File And Press "Enter" \33[0m\n')
+
+
+def run_process(*_ini_set: str):
+    """
+    Decorator for standardizing data processing functions.
+
+    This decorator wraps processing functions to provide consistent logging,
+    output formatting, and file saving behavior.
+
+    Parameters
+    ----------
+    *_ini_set : str
+        Two strings: process display name and output file name
+
+    Returns
+    -------
+    callable
+        Decorated function that handles the entire process flow
+
+    Examples
+    --------
+    @run_process('Process Description', 'output_filename')
+    def process_function(self, data):
+        # Process data
+        return self, processed_data
+    """
+
+    def _decorator(_prcs_fc):
+        def _wrap(*arg, **kwarg):
+            _fc_name, _nam = _ini_set
+
+            if kwarg.get('nam') is not None:
+                _nam = kwarg.pop('nam')
+
+            print(f"\n\t{dtm.now().strftime('%m/%d %X')} : Process \033[92m{_fc_name}\033[0m -> {_nam}")
+
+            _class, _out = _prcs_fc(*arg, **kwarg)
+            _out = _class.pre_process(_out)
+
+            _class.save_out(_nam, _out)
+
+            return _out
+
+        return _wrap
+
+    return _decorator
+
+
+def union_index(*_df_arg):
+    """
+    Reindex multiple DataFrames to a common union index.
+
+    Creates a unified index from all input DataFrames and reindexes each
+    DataFrame to this common index, handling None values appropriately.
+
+    Parameters
+    ----------
+    *_df_arg : DataFrame
+        One or more pandas DataFrames to reindex
+
+    Returns
+    -------
+    list
+        List of reindexed DataFrames in the same order as input
+    """
+    _idx = concat(_df_arg, axis=1).index
+
+    return [_df.reindex(_idx) if _df is not None else None for _df in _df_arg]
+
+
+def validate_inputs(df, required_columns, func_name, column_descriptions=None):
+    """
+    Validate that DataFrame contains all required columns.
+
+    Parameters
+    ----------
+    df : DataFrame
+        Input DataFrame to validate.
+    required_columns : list
+        List of required column names.
+    func_name : str
+        Name of the calling function (for error message).
+    column_descriptions : dict, optional
+        Dictionary mapping column names to descriptions.
+        Example: {'AS': 'Ammonium Sulfate 硫酸銨 (ug/m3)'}
+
+    Raises
+    ------
+    ValueError
+        If DataFrame is None/empty or any required columns are missing.
+
+    Examples
+    --------
+    >>> REQUIRED = ['AS', 'AN', 'OM']
+    >>> DESCRIPTIONS = {'AS': 'Ammonium Sulfate', 'AN': 'Ammonium Nitrate', 'OM': 'Organic Matter'}
+    >>> validate_inputs(df, REQUIRED, 'my_function', DESCRIPTIONS)
+    """
+    if df is None:
+        raise ValueError(
+            f"\n{func_name}() 輸入資料為 None！\n"
+            f"  需要欄位: {required_columns}"
+        )
+
+    if hasattr(df, 'empty') and df.empty:
+        raise ValueError(
+            f"\n{func_name}() 輸入資料為空！\n"
+            f"  需要欄位: {required_columns}"
+        )
+
+    existing_columns = set(df.columns)
+    required_set = set(required_columns)
+    missing = required_set - existing_columns
+
+    if missing:
+        error_msg = (
+            f"\n{func_name}() 缺少必要欄位！\n"
+            f"  需要欄位: {required_columns}\n"
+            f"  缺少欄位: {sorted(missing)}\n"
+            f"  現有欄位: {sorted(existing_columns)}"
+        )
+
+        if column_descriptions:
+            error_msg += "\n\n欄位說明:"
+            for col in required_columns:
+                if col in column_descriptions:
+                    error_msg += f"\n  {col:6s} - {column_descriptions[col]}"
+
+        raise ValueError(error_msg)
+
+
+def deprecated(message):
+    """
+    Decorator to mark functions as deprecated.
+
+    This decorator adds a warning message when a deprecated function is called,
+    informing users about the deprecation and suggesting alternatives.
+
+    Parameters
+    ----------
+    message : str
+        Message explaining why the function is deprecated and what to use instead
+
+    Returns
+    -------
+    callable
+        Decorator function that adds deprecation warnings
+
+    Examples
+    --------
+    @deprecated("Use new_function() instead.")
+    def old_function():
+        # Function implementation
+        pass
+    """
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            warnings.warn(
+                f"{func.__name__} is deprecated and will be removed in a future version. {message}",
+                category=DeprecationWarning,
+                stacklevel=2
+            )
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

AeroViz/mcp_server.py

@@ -0,0 +1,352 @@
+"""
+AeroViz MCP Server
+
+Provides AI assistants with access to aerosol data processing capabilities.
+
+Installation:
+    pip install mcp
+
+Usage in Claude Code settings (~/.claude/settings.json):
+{
+  "mcpServers": {
+    "aeroviz": {
+      "command": "python",
+      "args": ["/path/to/AeroViz/AeroViz/mcp_server.py"],
+      "env": {
+        "PYTHONPATH": "/path/to/AeroViz"
+      }
+    }
+  }
+}
+"""
+
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+
+# MCP imports
+try:
+    from mcp.server import Server
+    from mcp.server.stdio import stdio_server
+    from mcp.types import Tool, TextContent
+except ImportError:
+    print("MCP not installed. Run: pip install mcp", file=sys.stderr)
+    sys.exit(1)
+
+# Create server instance
+server = Server("aeroviz")
+
+# Supported instruments metadata
+SUPPORTED_INSTRUMENTS = {
+    "AE33": {"description": "Aethalometer - Black carbon at 7 wavelengths", "freq": "1min"},
+    "AE43": {"description": "Aethalometer - Black carbon at 7 wavelengths", "freq": "1min"},
+    "BC1054": {"description": "Black carbon monitor", "freq": "1min"},
+    "MA350": {"description": "MicroAeth - Portable black carbon", "freq": "1min"},
+    "SMPS": {"description": "Scanning Mobility Particle Sizer - Size distribution 10-1000nm", "freq": "6min"},
+    "APS": {"description": "Aerodynamic Particle Sizer - Size distribution 0.5-20μm", "freq": "6min"},
+    "GRIMM": {"description": "Optical particle counter", "freq": "6min"},
+    "TEOM": {"description": "Tapered Element Oscillating Microbalance - PM mass", "freq": "6min"},
+    "BAM1020": {"description": "Beta Attenuation Monitor - PM mass", "freq": "1h"},
+    "NEPH": {"description": "Nephelometer - Scattering coefficients", "freq": "5min"},
+    "Aurora": {"description": "Aurora nephelometer - Scattering at 3 wavelengths", "freq": "1min"},
+    "OCEC": {"description": "OC/EC analyzer - Organic/Elemental carbon", "freq": "1h"},
+    "Xact": {"description": "XRF analyzer - Heavy metals (Fe, Zn, Pb, etc.)", "freq": "1h"},
+    "IGAC": {"description": "Ion chromatograph - Water-soluble ions", "freq": "1h"},
+    "VOC": {"description": "VOC analyzer - Volatile organic compounds", "freq": "1h"},
+    "Q-ACSM": {"description": "Aerosol Chemical Speciation Monitor", "freq": "30min"},
+    "EPA": {"description": "EPA air quality data", "freq": "1h"},
+    "Minion": {"description": "Minion sensor", "freq": "1h"},
+}
+
+
+@server.list_tools()
+async def list_tools():
+    """List available AeroViz tools."""
+    return [
+        Tool(
+            name="list_instruments",
+            description="List all supported aerosol instruments in AeroViz",
+            inputSchema={
+                "type": "object",
+                "properties": {},
+                "required": []
+            }
+        ),
+        Tool(
+            name="read_instrument_data",
+            description="Read and process aerosol instrument data with automatic QC",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "instrument": {
+                        "type": "string",
+                        "description": "Instrument name (e.g., AE33, SMPS, APS, TEOM)",
+                        "enum": list(SUPPORTED_INSTRUMENTS.keys())
+                    },
+                    "path": {
+                        "type": "string",
+                        "description": "Directory path containing raw data files"
+                    },
+                    "start": {
+                        "type": "string",
+                        "description": "Start date in ISO format (e.g., 2024-01-01)"
+                    },
+                    "end": {
+                        "type": "string",
+                        "description": "End date in ISO format (e.g., 2024-12-31)"
+                    },
+                    "mean_freq": {
+                        "type": "string",
+                        "description": "Averaging frequency (default: 1h)",
+                        "default": "1h"
+                    },
+                    "qc": {
+                        "type": "boolean",
+                        "description": "Apply quality control (default: true)",
+                        "default": True
+                    },
+                    "reset": {
+                        "type": "boolean",
+                        "description": "Force reprocess from raw files (default: false)",
+                        "default": False
+                    }
+                },
+                "required": ["instrument", "path", "start", "end"]
+            }
+        ),
+        Tool(
+            name="get_data_summary",
+            description="Get summary statistics of processed aerosol data",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "instrument": {
+                        "type": "string",
+                        "description": "Instrument name",
+                        "enum": list(SUPPORTED_INSTRUMENTS.keys())
+                    },
+                    "path": {
+                        "type": "string",
+                        "description": "Directory path containing raw data files"
+                    },
+                    "start": {
+                        "type": "string",
+                        "description": "Start date in ISO format"
+                    },
+                    "end": {
+                        "type": "string",
+                        "description": "End date in ISO format"
+                    }
+                },
+                "required": ["instrument", "path", "start", "end"]
+            }
+        ),
+        Tool(
+            name="get_instrument_info",
+            description="Get detailed information about a specific instrument",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "instrument": {
+                        "type": "string",
+                        "description": "Instrument name",
+                        "enum": list(SUPPORTED_INSTRUMENTS.keys())
+                    }
+                },
+                "required": ["instrument"]
+            }
+        ),
+        Tool(
+            name="calculate_optical_properties",
+            description="Calculate optical properties (AAE, SAE, SSA, etc.) from aerosol data",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "absorption_data": {
+                        "type": "string",
+                        "description": "JSON string of absorption coefficient data"
+                    },
+                    "scattering_data": {
+                        "type": "string",
+                        "description": "JSON string of scattering coefficient data (optional)"
+                    }
+                },
+                "required": ["absorption_data"]
+            }
+        )
+    ]
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict):
+    """Handle tool calls."""
+
+    if name == "list_instruments":
+        result = []
+        for inst, info in SUPPORTED_INSTRUMENTS.items():
+            result.append(f"- **{inst}**: {info['description']} (freq: {info['freq']})")
+        return [TextContent(
+            type="text",
+            text="# Supported Instruments in AeroViz\n\n" + "\n".join(result)
+        )]
+
+    elif name == "get_instrument_info":
+        instrument = arguments.get("instrument")
+        if instrument not in SUPPORTED_INSTRUMENTS:
+            return [TextContent(type="text", text=f"Unknown instrument: {instrument}")]
+
+        info = SUPPORTED_INSTRUMENTS[instrument]
+
+        # Get additional info from meta config
+        from AeroViz.rawDataReader.config.supported_instruments import meta
+        meta_info = meta.get(instrument, {})
+
+        result = f"""# {instrument}
+
+**Description**: {info['description']}
+**Native Frequency**: {info['freq']}
+**File Patterns**: {', '.join(meta_info.get('pattern', ['Unknown']))}
+
+## Usage Example
+```python
+from AeroViz import RawDataReader
+
+df = RawDataReader(
+    instrument='{instrument}',
+    path='/path/to/data',
+    start='2024-01-01',
+    end='2024-12-31',
+    mean_freq='1h',
+    qc=True
+)
+```
+"""
+        # Add MDL info if available
+        if 'MDL' in meta_info:
+            result += "\n## Minimum Detection Limits (MDL)\n"
+            for elem, mdl in list(meta_info['MDL'].items())[:10]:
+                if mdl is not None:
+                    result += f"- {elem}: {mdl} ng/m³\n"
+            if len(meta_info['MDL']) > 10:
+                result += f"- ... and {len(meta_info['MDL']) - 10} more elements\n"
+
+        return [TextContent(type="text", text=result)]
+
+    elif name == "read_instrument_data":
+        try:
+            from AeroViz import RawDataReader
+
+            instrument = arguments["instrument"]
+            path = arguments["path"]
+            start = arguments["start"]
+            end = arguments["end"]
+            mean_freq = arguments.get("mean_freq", "1h")
+            qc = arguments.get("qc", True)
+            reset = arguments.get("reset", False)
+
+            # Validate path
+            if not Path(path).exists():
+                return [TextContent(type="text", text=f"Error: Path does not exist: {path}")]
+
+            df = RawDataReader(
+                instrument=instrument,
+                path=path,
+                start=start,
+                end=end,
+                mean_freq=mean_freq,
+                qc=qc,
+                reset=reset
+            )
+
+            # Return summary + first/last rows
+            result = f"""# {instrument} Data Loaded Successfully
+
+**Time Range**: {df.index.min()} to {df.index.max()}
+**Rows**: {len(df):,}
+**Columns**: {', '.join(df.columns[:10])}{'...' if len(df.columns) > 10 else ''}
+
+## Summary Statistics
+```
+{df.describe().to_string()}
+```
+
+## First 5 Rows
+```
+{df.head().to_string()}
+```
+
+## Last 5 Rows
+```
+{df.tail().to_string()}
+```
+"""
+            return [TextContent(type="text", text=result)]
+
+        except Exception as e:
+            return [TextContent(type="text", text=f"Error reading data: {str(e)}")]
+
+    elif name == "get_data_summary":
+        try:
+            from AeroViz import RawDataReader
+
+            df = RawDataReader(
+                instrument=arguments["instrument"],
+                path=arguments["path"],
+                start=arguments["start"],
+                end=arguments["end"],
+                mean_freq="1h",
+                qc=True
+            )
+
+            # Calculate comprehensive summary
+            summary = {
+                "time_range": {
+                    "start": str(df.index.min()),
+                    "end": str(df.index.max()),
+                    "total_hours": len(df)
+                },
+                "data_completeness": {
+                    col: f"{(df[col].notna().sum() / len(df) * 100):.1f}%"
+                    for col in df.columns[:10]
+                },
+                "statistics": df.describe().to_dict()
+            }
+
+            return [TextContent(type="text", text=f"```json\n{json.dumps(summary, indent=2, default=str)}\n```")]
+
+        except Exception as e:
+            return [TextContent(type="text", text=f"Error: {str(e)}")]
+
+    elif name == "calculate_optical_properties":
+        try:
+            from AeroViz.dataProcess.Optical import Optical
+            import pandas as pd
+
+            abs_data = json.loads(arguments["absorption_data"])
+            df = pd.DataFrame(abs_data)
+
+            result = "# Optical Properties Calculation\n\n"
+            result += "Use AeroViz.dataProcess.Optical for:\n"
+            result += "- AAE (Absorption Ångström Exponent)\n"
+            result += "- SAE (Scattering Ångström Exponent)\n"
+            result += "- SSA (Single Scattering Albedo)\n"
+            result += "- Mass absorption/scattering coefficients\n"
+
+            return [TextContent(type="text", text=result)]
+
+        except Exception as e:
+            return [TextContent(type="text", text=f"Error: {str(e)}")]
+
+    return [TextContent(type="text", text=f"Unknown tool: {name}")]
+
+
+async def main():
+    """Run the MCP server."""
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+
+if __name__ == "__main__":
+    import asyncio
+    asyncio.run(main())

AeroViz/plot/__init__.py

@@ -0,0 +1,13 @@
+from . import distribution
+from . import meteorology
+from . import optical
+from .bar import bar
+from .box import box
+from .pie import pie, donuts
+from .radar import radar
+from .regression import linear_regression, multiple_linear_regression
+from .scatter import scatter
+from .templates import *
+from .timeseries import timeseries, timeseries_template, timeseries_stacked
+from .utils import *
+from .violin import violin