0
# Pandas Integration
1

2
Specialized functions for working with pandas Series and DataFrame objects, providing simplified APIs for basic continuous metrics without dimensional operations.
3

4
## Capabilities
5

6
### Pandas Continuous Scores
7

8
Simplified versions of continuous metrics optimized for pandas data structures. These functions provide basic error metrics without the dimensional reduction capabilities available in the full xarray-based API.
9

10
```python { .api }
11
from scores.pandas.continuous import mse, rmse, mae
12
from scores.pandas.typing import PandasType
13
```
14

15
#### Mean Squared Error (MSE) for Pandas
16

17
Calculates MSE for pandas Series data with angular data support.
18

19
```python { .api }
20
def mse(
21
    fcst: PandasType,
22
    obs: PandasType,
23
    *,
24
    is_angular: bool = False,
25
) -> PandasType:
26
    """
27
    Calculate Mean Squared Error for pandas data.
28

29
    Args:
30
        fcst: Forecast data in pandas Series
31
        obs: Observation data in pandas Series
32
        is_angular: Handle circular/angular data (e.g. wind direction)
33

34
    Returns:
35
        pandas.Series with single MSE value
36

37
    Notes:
38
        - Dimensional reduction not supported for pandas
39
        - Use xarray API (scores.continuous.mse) for advanced operations
40
        - Angular data should be in degrees, not radians
41
    """
42
```
43

44
#### Root Mean Squared Error (RMSE) for Pandas
45

46
Calculates RMSE for pandas Series data.
47

48
```python { .api }
49
def rmse(
50
    fcst: PandasType,
51
    obs: PandasType,
52
    *,
53
    is_angular: bool = False,
54
) -> PandasType:
55
    """
56
    Calculate Root Mean Squared Error for pandas data.
57

58
    Args:
59
        fcst: Forecast data in pandas Series
60
        obs: Observation data in pandas Series
61
        is_angular: Handle circular/angular data
62

63
    Returns:
64
        pandas.Series with single RMSE value
65
    """
66
```
67

68
#### Mean Absolute Error (MAE) for Pandas
69

70
Calculates MAE for pandas Series data.
71

72
```python { .api }
73
def mae(
74
    fcst: PandasType,
75
    obs: PandasType,
76
    *,
77
    is_angular: bool = False,
78
) -> PandasType:
79
    """
80
    Calculate Mean Absolute Error for pandas data.
81

82
    Args:
83
        fcst: Forecast data in pandas Series
84
        obs: Observation data in pandas Series
85
        is_angular: Handle circular/angular data
86

87
    Returns:
88
        pandas.Series with single MAE value
89
    """
90
```
91

92
## Types
93

94
```python { .api }
95
from typing import Type
96
import pandas as pd
97

98
PandasType = Type[pd.Series]
99
```
100

101
## Usage Examples
102

103
```python
104
import pandas as pd
105
from scores.pandas.continuous import mse, rmse, mae
106

107
# Create sample pandas data
108
forecast_series = pd.Series([1.0, 2.0, 3.0, 4.0, 5.0])
109
observed_series = pd.Series([1.1, 1.9, 3.1, 3.9, 5.1])
110

111
# Calculate basic metrics
112
mse_result = mse(forecast_series, observed_series)
113
rmse_result = rmse(forecast_series, observed_series)
114
mae_result = mae(forecast_series, observed_series)
115

116
print(f"MSE: {mse_result.values[0]}")
117
print(f"RMSE: {rmse_result.values[0]}")
118
print(f"MAE: {mae_result.values[0]}")
119

120
# For angular data (e.g. wind direction in degrees)
121
wind_forecast = pd.Series([10, 350, 5, 180])
122
wind_observed = pd.Series([15, 355, 0, 175])
123

124
angular_mse = mse(wind_forecast, wind_observed, is_angular=True)
125
print(f"Angular MSE: {angular_mse.values[0]}")
126
```
127

128
## Limitations
129

130
The pandas API provides simplified functionality compared to the full xarray-based scores API:
131

132
- **No dimensional operations**: No `reduce_dims` or `preserve_dims` parameters
133
- **No weighting**: No `weights` parameter support
134
- **Limited metrics**: Only basic continuous metrics (MSE, RMSE, MAE) available
135
- **Single output**: All dimensions automatically reduced to single scalar value
136

137
For advanced functionality including dimensional operations, weighting, and the full range of metrics, convert pandas data to xarray and use the main scores API:
138

139
```python
140
import xarray as xr
141
import pandas as pd
142
from scores.continuous import mse as xarray_mse
143

144
# Convert pandas to xarray for advanced operations
145
forecast_da = xr.DataArray(forecast_series)
146
observed_da = xr.DataArray(observed_series)
147

148
# Now can use full xarray functionality
149
advanced_mse = xarray_mse(forecast_da, observed_da, weights=weights)
150
```