Metadata-Version: 2.4
Name: x13-seasonal-adjustment
Version: 0.1.3
Summary: Comprehensive X13-ARIMA-SEATS seasonal adjustment library for Python
Author-email: Gardash Abbasov <gardash.abbasov@gmail.com>
Maintainer-email: Gardash Abbasov <gardash.abbasov@gmail.com>
License: MIT License
        
        Copyright (c) 2024 Gardaş Habbasov
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/Gardash023/x13-seasonal-adjustment
Project-URL: Documentation, https://x13-seasonal-adjustment.readthedocs.io
Project-URL: Repository, https://github.com/Gardash023/x13-seasonal-adjustment
Project-URL: Bug Tracker, https://github.com/Gardash023/x13-seasonal-adjustment/issues
Keywords: time-series,seasonal-adjustment,x13,arima,econometrics,statistics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: statsmodels>=0.13.0
Requires-Dist: matplotlib>=3.3.0
Requires-Dist: scikit-learn>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Requires-Dist: mypy>=0.900; extra == "dev"
Requires-Dist: sphinx>=4.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
Requires-Dist: nbsphinx>=0.8; extra == "docs"
Requires-Dist: jupyter>=1.0; extra == "docs"
Dynamic: license-file

# X13 Seasonal Adjustment

[![PyPI version](https://badge.fury.io/py/x13-seasonal-adjustment.svg)](https://badge.fury.io/py/x13-seasonal-adjustment)
[![Python Version](https://img.shields.io/pypi/pyversions/x13-seasonal-adjustment.svg)](https://pypi.org/project/x13-seasonal-adjustment/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Documentation Status](https://readthedocs.org/projects/x13-seasonal-adjustment/badge/?version=latest)](https://x13-seasonal-adjustment.readthedocs.io/en/latest/?badge=latest)

A comprehensive Python implementation of the X13-ARIMA-SEATS seasonal adjustment algorithm. This library provides robust tools for detecting and removing seasonal effects from time series data.

## Features

- **Automatic Seasonality Detection**: Advanced statistical tests for seasonality identification
- **X13-ARIMA-SEATS Algorithm**: International standard seasonal adjustment methodology
- **High Performance**: Optimized computations using NumPy and SciPy
- **Visualization**: Comprehensive plotting capabilities with matplotlib
- **Flexible API**: Suitable for both simple and advanced use cases
- **Comprehensive Documentation**: Detailed documentation and examples
- **Full Test Coverage**: Reliable code with 95%+ test coverage

## Kurulum

```bash
pip install x13-seasonal-adjustment
```

Geliştirme versiyonu için:

```bash
pip install x13-seasonal-adjustment[dev]
```

## Hızlı Başlangıç

```python
import pandas as pd
from x13_seasonal_adjustment import X13SeasonalAdjustment

# Veri yükle
data = pd.read_csv('your_time_series.csv', index_col=0, parse_dates=True)

# X13 modeli oluştur
x13 = X13SeasonalAdjustment()

# Mevsimsellikten arındırma
result = x13.fit_transform(data['value'])

# Sonuçları görüntüle
print("Orijinal Seri:", result.original)
print("Mevsimsellikten Arındırılmış Seri:", result.seasonally_adjusted)
print("Mevsimsel Faktörler:", result.seasonal_factors)
print("Trend:", result.trend)

# Grafik çizimi
result.plot()
```

## Ana Bileşenler

### 1. X13SeasonalAdjustment (Ana Sınıf)
```python
from x13_seasonal_adjustment import X13SeasonalAdjustment

x13 = X13SeasonalAdjustment(
    freq='M',           # Veri frekansı (M=Aylık, Q=Çeyreklik)
    transform='auto',   # Logaritmik dönüşüm ('auto', 'log', 'none')
    outlier_detection=True,  # Aykırı değer tespiti
    trading_day=True,   # İş günü etkisi
    easter=True,        # Paskalya etkisi
    arima_order='auto'  # ARIMA model sırası
)
```

### 2. Mevsimsellik Testleri
```python
from x13_seasonal_adjustment.tests import SeasonalityTests

tests = SeasonalityTests()
result = tests.run_all_tests(data)
print(f"Mevsimsellik var mı? {result.has_seasonality}")
```

### 3. ARIMA Modelleme
```python
from x13_seasonal_adjustment.arima import AutoARIMA

arima = AutoARIMA()
model = arima.fit(data)
forecast = model.forecast(steps=12)
```

## Metodoloji

Bu kütüphane, ABD Sayım Bürosu'nun X13-ARIMA-SEATS programının metodolojisini takip eder:

1. **Ön İşleme**: Eksik değer doldurma, aykırı değer tespiti
2. **Model Seçimi**: Otomatik ARIMA model seçimi
3. **Mevsimsel Dekompozisyon**: X11 algoritması ile dekompozisyon
4. **Kalite Kontrolü**: M ve Q istatistikleri ile kalite değerlendirmesi

## Örnekler

### Temel Kullanım
```python
import numpy as np
import pandas as pd
from x13_seasonal_adjustment import X13SeasonalAdjustment

# Örnek veri oluştur
dates = pd.date_range('2020-01-01', periods=60, freq='M')
trend = np.linspace(100, 200, 60)
seasonal = 10 * np.sin(2 * np.pi * np.arange(60) / 12)
noise = np.random.normal(0, 5, 60)
data = pd.Series(trend + seasonal + noise, index=dates)

# Mevsimsellikten arındır
x13 = X13SeasonalAdjustment()
result = x13.fit_transform(data)

# Sonuçları analiz et
print(f"Mevsimsellik derecesi: {result.seasonality_strength:.3f}")
print(f"Trend gücü: {result.trend_strength:.3f}")
```

### İleri Seviye Kullanım
```python
from x13_seasonal_adjustment import X13SeasonalAdjustment
from x13_seasonal_adjustment.diagnostics import QualityDiagnostics

# Özelleştirilmiş model
x13 = X13SeasonalAdjustment(
    transform='log',
    outlier_detection=True,
    outlier_types=['AO', 'LS', 'TC'],  # Aykırı değer tipleri
    arima_order=(0, 1, 1),             # Manuel ARIMA sırası
    seasonal_arima_order=(0, 1, 1),    # Mevsimsel ARIMA sırası
)

result = x13.fit_transform(data)

# Kalite diagnostikleri
diagnostics = QualityDiagnostics()
quality_report = diagnostics.evaluate(result)
print(quality_report)
```

## API Referansı

### X13SeasonalAdjustment

**Parameters:**
- `freq` (str): Data frequency ('M', 'Q', 'A')
- `transform` (str): Transformation type ('auto', 'log', 'none')
- `outlier_detection` (bool): Enable outlier detection?
- `trading_day` (bool): Model trading day effects?
- `easter` (bool): Model Easter effects?
- `arima_order` (tuple or 'auto'): ARIMA model order

**Methods:**
- `fit(X)`: Train the model
- `transform(X)`: Apply seasonal adjustment
- `fit_transform(X)`: Train and transform
- `plot_decomposition()`: Plot decomposition chart

### SeasonalAdjustmentResult

**Properties:**
- `original`: Original series
- `seasonally_adjusted`: Seasonally adjusted series
- `seasonal_factors`: Seasonal factors
- `trend`: Trend component
- `irregular`: Irregular component
- `seasonality_strength`: Seasonality strength (0-1)
- `trend_strength`: Trend strength (0-1)

## Katkıda Bulunma

Bu projeye katkıda bulunmak istiyorsanız:

1. Repository'yi fork edin
2. Feature branch oluşturun (`git checkout -b feature/amazing-feature`)
3. Değişikliklerinizi commit edin (`git commit -m 'Add amazing feature'`)
4. Branch'inizi push edin (`git push origin feature/amazing-feature`)
5. Pull Request oluşturun

## Geliştirme Ortamı

```bash
# Repository'yi klonlayın
git clone https://github.com/gardashabbasov/x13-seasonal-adjustment.git
cd x13-seasonal-adjustment

# Geliştirme bağımlılıklarını yükleyin
pip install -e .[dev]

# Testleri çalıştırın
pytest

# Code style kontrolü
black src/ tests/
flake8 src/ tests/

# Type checking
mypy src/
```

## Lisans

Bu proje MIT lisansı altında lisanslanmıştır. Detaylar için [LICENSE](LICENSE) dosyasına bakın.

## Contact

- **Developer**: Gardash Abbasov
- **Email**: gardash.abbasov@gmail.com
- **GitHub**: [@Gardash023](https://github.com/Gardash023)

## Acknowledgments

- US Census Bureau's X13-ARIMA-SEATS program
- Statsmodels, NumPy, SciPy, Pandas communities
- International econometrics and statistics community

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for detailed version history.
