nanoforecast 0.2.0__py3-none-any.whl

nanoforecast/__init__.py

@@ -0,0 +1,5 @@
+# NanoForecast: World's most deployable time series transformer
+__version__ = "0.2.0"
+
+from nanoforecast.model.core import NanoForecast, StreamingState
+from nanoforecast.config import NanoForecastConfig

nanoforecast/config.py

@@ -0,0 +1,44 @@
+from dataclasses import dataclass, field
+from typing import List
+
+@dataclass
+class NanoForecastConfig:
+    # Context and prediction windows
+    context_length: int = 512
+    prediction_length: int = 96
+    
+    # Architecture dimensions
+    d_model: int = 32
+    num_layers: int = 4
+    patch_size: int = 8
+    dropout: float = 0.1
+    expansion_factor: int = 2
+    
+    # Model capabilities
+    quantiles: List[float] = field(default_factory=lambda: [0.1, 0.25, 0.5, 0.75, 0.9])
+    num_frequencies: int = 10  # Learned embeddings for hourly, daily, weekly, etc.
+    num_channels: int = 16      # Maximum multivariate channels supported natively
+    covariate_dim: int = 4     # Dimensionality of exogenous covariates
+    
+    # Gating and features
+    use_gated_router: bool = True
+    
+    @classmethod
+    def nano_200k(cls) -> "NanoForecastConfig":
+        return cls(
+            d_model=32,
+            num_layers=4,
+            patch_size=8,
+            dropout=0.1,
+            expansion_factor=2
+        )
+        
+    @classmethod
+    def nano_500k(cls) -> "NanoForecastConfig":
+        return cls(
+            d_model=64,
+            num_layers=8,
+            patch_size=8,
+            dropout=0.1,
+            expansion_factor=2
+        )

nanoforecast/data/__init__.py

@@ -0,0 +1,2 @@
+from nanoforecast.data.generator import SyntheticTimeSeriesGenerator
+from nanoforecast.data.pipeline import TimeSeriesDataset, ResolutionBatchSampler, create_dataloader

nanoforecast/data/generator.py

@@ -0,0 +1,164 @@
+import numpy as np
+from typing import Dict, Tuple, List
+
+class SyntheticTimeSeriesGenerator:
+    """
+    High-speed, vectorized generator for realistic synthetic time series.
+    Generates various patterns: linear/exponential trends, multi-seasonal cycles,
+    outlier spikes, level shifts, and non-Gaussian noise.
+    """
+    def __init__(self, seed: int = 42):
+        self.rng = np.random.default_rng(seed)
+
+    def generate_single_series(
+        self, 
+        length: int, 
+        freq_id: int
+    ) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        Generates a single synthetic time series vector along with a covariate matrix.
+        Args:
+            length: Number of time steps to generate
+            freq_id: Integer mapping to a specific frequency (0-9)
+        Returns:
+            series: Array of shape [length]
+            covariates: Array of shape [cov_dim, length] (numeric indicators like holiday, time-of-day)
+        """
+        t = np.arange(length)
+        
+        # 1. Base Trend
+        trend_type = self.rng.choice(["linear", "exponential", "piecewise", "flat"])
+        if trend_type == "linear":
+            slope = self.rng.uniform(-0.05, 0.05)
+            trend = slope * t
+        elif trend_type == "exponential":
+            growth = self.rng.uniform(0.001, 0.005)
+            trend = 0.1 * np.exp(growth * t)
+        elif trend_type == "piecewise":
+            changepoint = length // 2
+            slope1 = self.rng.uniform(-0.05, 0.05)
+            slope2 = self.rng.uniform(-0.05, 0.05)
+            trend = np.zeros(length)
+            trend[:changepoint] = slope1 * t[:changepoint]
+            trend[changepoint:] = trend[changepoint-1] + slope2 * (t[changepoint:] - changepoint)
+        else:
+            trend = np.zeros(length)
+            
+        # Add random base level shift
+        trend += self.rng.uniform(-10.0, 10.0)
+
+        # 2. Seasonality (Frequency-dependent)
+        season = np.zeros(length)
+        if freq_id == 0:  # 5-minutely (period e.g., 288 steps/day)
+            periods = [288]
+        elif freq_id == 1:  # Hourly (period 24 steps/day, 168 steps/week)
+            periods = [24, 168]
+        elif freq_id == 2:  # Daily (period 7 steps/week)
+            periods = [7]
+        elif freq_id == 3:  # Weekly (period 52 steps/year)
+            periods = [52]
+        elif freq_id == 4:  # Monthly (period 12 steps/year)
+            periods = [12]
+        else:  # Other/Unknown
+            periods = [self.rng.choice([10, 20, 30])]
+
+        for period in periods:
+            amplitude = self.rng.uniform(0.5, 3.0)
+            phase = self.rng.uniform(0, 2 * np.pi)
+            season += amplitude * np.sin(2 * np.pi * t / period + phase)
+            
+            # Add harmonic
+            if self.rng.random() > 0.5:
+                season += (amplitude * 0.3) * np.sin(4 * np.pi * t / period + phase)
+
+        # 3. Level Shifts / Step Changes
+        shift = np.zeros(length)
+        if self.rng.random() > 0.7:
+            shift_idx = self.rng.integers(int(length * 0.2), int(length * 0.8))
+            shift_magnitude = self.rng.uniform(-5.0, 5.0)
+            shift[shift_idx:] = shift_magnitude
+
+        # 4. Combine Signal (Deterministic)
+        signal = trend + season + shift
+
+        # 5. Outliers / Anomalies
+        outliers = np.zeros(length)
+        if self.rng.random() > 0.8:
+            num_outliers = self.rng.integers(1, 4)
+            for _ in range(num_outliers):
+                idx = self.rng.integers(0, length)
+                outliers[idx] = self.rng.choice([-1.0, 1.0]) * self.rng.uniform(5.0, 15.0)
+
+        # 6. Noise
+        noise_type = self.rng.choice(["gaussian", "student-t", "heteroscedastic"])
+        if noise_type == "gaussian":
+            noise = self.rng.normal(0, 0.5, size=length)
+        elif noise_type == "student-t":
+            noise = self.rng.standard_t(df=3, size=length) * 0.3
+        else:  # Variance increases over time
+            scale = 0.1 + 0.9 * (t / length)
+            noise = self.rng.normal(0, scale)
+
+        # Final Time Series
+        series = signal + outliers + noise
+        
+        # Scale to random physical range
+        series_scale = np.exp(self.rng.uniform(-2.0, 5.0))
+        series = series * series_scale
+        
+        # 7. Covariates (Generate 4 channels of exogenous signals)
+        # Cov 0: Sine wave capturing cyclic time-of-day/week
+        # Cov 1: Binary holiday/promotion indicator (random spikes)
+        # Cov 2: Binary weekend indicator
+        # Cov 3: Linear step indicator
+        covariates = np.zeros((4, length))
+        
+        # Periodic covariate
+        covariates[0, :] = np.sin(2 * np.pi * t / 24)
+        
+        # Binary event indicator (promotions/holidays)
+        event_indices = self.rng.choice(length, size=int(length * 0.05), replace=False)
+        covariates[1, event_indices] = 1.0
+        
+        # Weekend indicator (for daily-ish series)
+        if freq_id in [1, 2]:
+            weekend_mask = (t % 7 >= 5).astype(float)
+            covariates[2, :] = weekend_mask
+            
+        # Generic trend covariate
+        covariates[3, :] = t / length
+        
+        return series.astype(np.float32), covariates.astype(np.float32)
+
+    def generate_dataset(
+        self, 
+        num_series: int, 
+        context_len: int, 
+        prediction_len: int
+    ) -> List[Dict]:
+        """
+        Generates a list of dictionaries representing a dataset.
+        """
+        dataset = []
+        total_len = context_len + prediction_len
+        
+        for i in range(num_series):
+            # Select random frequency
+            freq_id = int(self.rng.integers(0, 5))
+            series, covariates = self.generate_single_series(total_len, freq_id)
+            
+            context_target = series[:context_len]
+            prediction_target = series[context_len:]
+            
+            context_covariates = covariates[:, :context_len]
+            prediction_covariates = covariates[:, context_len:]
+            
+            dataset.append({
+                "context": context_target,
+                "prediction": prediction_target,
+                "freq_id": freq_id,
+                "context_covariates": context_covariates,
+                "prediction_covariates": prediction_covariates
+            })
+            
+        return dataset

nanoforecast/data/pipeline.py

@@ -0,0 +1,168 @@
+import numpy as np
+import torch
+from torch.utils.data import Dataset, Sampler
+from typing import List, Dict, Tuple, Optional
+
+class TimeSeriesDataset(Dataset):
+    """
+    PyTorch Dataset wrapping time series records.
+    Provides option for real-time data augmentations.
+    """
+    def __init__(
+        self, 
+        records: List[Dict], 
+        augment: bool = False,
+        augment_prob: float = 0.5
+    ):
+        self.records = records
+        self.augment = augment
+        self.augment_prob = augment_prob
+
+    def __len__(self) -> int:
+        return len(self.records)
+
+    def __getitem__(self, idx: int) -> Dict[str, torch.Tensor]:
+        rec = self.records[idx]
+        
+        # Extract features
+        # Add channel dimension: [C, L] -> here C=1 (univariate targets)
+        x = torch.tensor(rec["context"], dtype=torch.float32).unsqueeze(0)
+        y = torch.tensor(rec["prediction"], dtype=torch.float32).unsqueeze(0)
+        
+        freq_id = torch.tensor(rec["freq_id"], dtype=torch.long)
+        
+        # Handle covariates
+        covariates = torch.tensor(rec["context_covariates"], dtype=torch.float32)
+        
+        # Apply data augmentation if requested
+        if self.augment and np.random.rand() < self.augment_prob:
+            x, covariates = self._apply_augmentations(x, covariates)
+            
+        return {
+            "x": x,
+            "y": y,
+            "freq_id": freq_id,
+            "covariates": covariates
+        }
+
+    def _apply_augmentations(
+        self, 
+        x: torch.Tensor, 
+        covariates: torch.Tensor
+    ) -> Tuple[torch.Tensor, torch.Tensor]:
+        """
+        Applies random scale adjustments, shifting, and jitter noise.
+        """
+        # Random scale multiplier: multiply target by [0.5, 2.0]
+        scale = np.random.uniform(0.5, 2.0)
+        x = x * scale
+        
+        # Random shifting offset: add constant offset to target
+        shift = np.random.uniform(-2.0, 2.0)
+        x = x + shift
+        
+        # Add random noise jitter
+        if np.random.rand() > 0.5:
+            noise = torch.randn_like(x) * 0.05
+            x = x + noise
+            
+        # Randomly mask 5-15% of values (simulate missing values)
+        if np.random.rand() > 0.7:
+            seq_len = x.shape[-1]
+            mask_len = int(np.random.uniform(0.05, 0.15) * seq_len)
+            mask_start = np.random.randint(0, seq_len - mask_len)
+            x[..., mask_start:mask_start+mask_len] = 0.0
+            
+        return x, covariates
+
+
+class ResolutionBatchSampler(Sampler):
+    """
+    Resolution-Aware Batch Sampler.
+    Groups indices by their frequency ID and yields batches containing
+    series of ONLY one frequency. This allows the model to learn frequency-specific
+    priors cleanly within a batch.
+
+    By default `drop_last=False` and `min_batch_size=1`, so partial remainder
+    batches are emitted rather than dropped silently. Set `drop_last=True` to
+    recover the original strict behaviour.
+    """
+    def __init__(
+        self,
+        freq_ids: List[int],
+        batch_size: int,
+        shuffle: bool = True,
+        drop_last: bool = False,
+        min_batch_size: int = 1,
+    ):
+        self.batch_size = batch_size
+        self.shuffle = shuffle
+        self.drop_last = drop_last
+        self.min_batch_size = max(1, min_batch_size)
+
+        self.freq_to_indices = {}
+        for idx, freq_id in enumerate(freq_ids):
+            self.freq_to_indices.setdefault(freq_id, []).append(idx)
+
+    def __iter__(self):
+        batches = []
+        for indices in self.freq_to_indices.values():
+            indices_copy = list(indices)
+            if self.shuffle:
+                np.random.shuffle(indices_copy)
+
+            for i in range(0, len(indices_copy), self.batch_size):
+                batch = indices_copy[i:i + self.batch_size]
+                if len(batch) < self.min_batch_size:
+                    continue
+                if self.drop_last and len(batch) != self.batch_size:
+                    continue
+                batches.append(batch)
+
+        if self.shuffle:
+            np.random.shuffle(batches)
+
+        return iter(batches)
+
+    def __len__(self) -> int:
+        total = 0
+        for indices in self.freq_to_indices.values():
+            n = len(indices)
+            if self.drop_last:
+                total += n // self.batch_size
+            else:
+                # ceil(n / batch_size) with min_batch_size filtering
+                full, rem = divmod(n, self.batch_size)
+                total += full + (1 if rem >= self.min_batch_size else 0)
+        return total
+
+
+def create_dataloader(
+    records: List[Dict],
+    batch_size: int,
+    augment: bool = False,
+    shuffle: bool = True,
+    drop_last: bool = False,
+    min_batch_size: int = 1,
+) -> torch.utils.data.DataLoader:
+    """
+    Helper function to wrap dataset in a DataLoader using ResolutionBatchSampler.
+    """
+    dataset = TimeSeriesDataset(records, augment=augment)
+    freq_ids = [rec["freq_id"] for rec in records]
+
+    sampler = ResolutionBatchSampler(
+        freq_ids,
+        batch_size,
+        shuffle=shuffle,
+        drop_last=drop_last,
+        min_batch_size=min_batch_size,
+    )
+
+    loader = torch.utils.data.DataLoader(
+        dataset,
+        batch_sampler=sampler,
+        num_workers=0,
+        pin_memory=True
+    )
+    return loader

nanoforecast/data/real_datasets.py

@@ -0,0 +1,213 @@
+"""Real time series dataset loaders for NanoForecast pretraining.
+
+Loads canonical Monash / Informer / Autoformer benchmark datasets from
+public mirrors. Supports univariate slicing so the same loader can feed
+both the univariate NanoForecast core and the multivariate cases.
+
+Datasets supported:
+  - ETTh1, ETTh2, ETTm1 (hourly / 15-min oil temperature, 7 features)
+  - exchange_rate (daily FX, 8 channels)
+  - electricity (hourly household consumption, 321 channels)
+  - traffic (hourly road occupancy, 862 channels)
+"""
+from __future__ import annotations
+
+import gzip
+import io
+import os
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Tuple
+
+import numpy as np
+import pandas as pd
+import requests
+
+CACHE_DIR = os.path.expanduser("~/.cache/nanoforecast/datasets")
+os.makedirs(CACHE_DIR, exist_ok=True)
+
+# freq_id convention from synthetic generator:
+#   0 -> 5-min, 1 -> hourly, 2 -> daily, 3 -> weekly, 4 -> monthly, 5+ -> other
+FREQ_MAP = {
+    "ETTh1": 1,
+    "ETTh2": 1,
+    "ETTm1": 0,  # 15-min intervals
+    "exchange_rate": 2,  # daily
+    "electricity": 1,  # hourly
+    "traffic": 1,  # hourly
+}
+
+DATASET_URLS: Dict[str, str] = {
+    "ETTh1": "https://raw.githubusercontent.com/zhouhaoyi/ETDataset/main/ETT-small/ETTh1.csv",
+    "ETTh2": "https://raw.githubusercontent.com/zhouhaoyi/ETDataset/main/ETT-small/ETTh2.csv",
+    "ETTm1": "https://raw.githubusercontent.com/zhouhaoyi/ETDataset/main/ETT-small/ETTm1.csv",
+    "exchange_rate": "https://raw.githubusercontent.com/laiguokun/multivariate-time-series-data/master/exchange_rate/exchange_rate.txt.gz",
+    "electricity": "https://raw.githubusercontent.com/laiguokun/multivariate-time-series-data/master/electricity/electricity.txt.gz",
+    "traffic": "https://raw.githubusercontent.com/laiguokun/multivariate-time-series-data/master/traffic/traffic.txt.gz",
+}
+
+
+@dataclass
+class WindowSpec:
+    """Sliding-window specification for turning long series into pretraining records."""
+    context_len: int = 256
+    prediction_len: int = 48
+    stride: int = 64
+
+
+def _cache_path(dataset: str, suffix: str = "") -> str:
+    safe = dataset.replace("/", "_")
+    return os.path.join(CACHE_DIR, safe + suffix)
+
+
+def _is_gzip(path: str) -> bool:
+    with open(path, "rb") as fh:
+        return fh.read(2) == b"\x1f\x8b"
+
+
+def _download(dataset: str, url: str) -> str:
+    path = _cache_path(dataset, suffix=".gz" if url.endswith(".gz") else "")
+    if os.path.exists(path):
+        if os.path.getsize(path) > 0:
+            return path
+        print(f"[datasets] removing empty cache for {dataset} ...")
+        os.remove(path)
+    print(f"[datasets] downloading {dataset} from {url} ...")
+    resp = requests.get(url, stream=True, timeout=300)
+    resp.raise_for_status()
+    with open(path, "wb") as fh:
+        for chunk in resp.iter_content(chunk_size=1 << 20):
+            if chunk:
+                fh.write(chunk)
+    if os.path.getsize(path) == 0:
+        raise RuntimeError(f"Downloaded file for {dataset} is empty: {url}")
+    return path
+
+
+def _clear_cache(dataset: str) -> None:
+    for suffix in ["", ".gz"]:
+        p = _cache_path(dataset, suffix=suffix)
+        if os.path.exists(p):
+            os.remove(p)
+
+def _load_dataframe(dataset: str) -> pd.DataFrame:
+    url = DATASET_URLS[dataset]
+    for attempt in range(2):
+        path = _download(dataset, url)
+        try:
+            if _is_gzip(path):
+                with gzip.open(path, "rb") as fh:
+                    data = fh.read()
+                arr = np.loadtxt(io.BytesIO(data), delimiter=",", dtype=np.float32)
+                return pd.DataFrame(arr)
+            return pd.read_csv(path)
+        except (pd.errors.EmptyDataError, OSError, ValueError) as e:
+            if attempt == 0:
+                print(f"[datasets] corrupt cache for {dataset}, re-downloading ... ({e})")
+                _clear_cache(dataset)
+                continue
+            raise
+
+
+def list_datasets() -> List[str]:
+    return list(DATASET_URLS.keys())
+
+
+def load_univariate_series(
+    dataset: str,
+    channels: Optional[List[int]] = None,
+    max_channels: int = 4,
+) -> Tuple[List[np.ndarray], int]:
+    """Load selected channels of a dataset as a list of 1-D float32 arrays.
+
+    Args:
+        dataset: one of the keys in DATASET_URLS.
+        channels: explicit channel indices (0-based, excluding the date column for ETT*).
+            If None, picks up to ``max_channels`` channels spaced evenly across the file.
+        max_channels: used when ``channels`` is None.
+
+    Returns:
+        series_list: list of 1-D float32 arrays, one per selected channel.
+        freq_id: integer frequency identifier.
+    """
+    df = _load_dataframe(dataset)
+    if dataset.startswith("ETT"):
+        # First column is the date; remaining columns are features.
+        values = df.iloc[:, 1:].to_numpy(dtype=np.float32)
+    else:
+        # Comma-separated dense matrix files (one row per timestep).
+        values = df.to_numpy(dtype=np.float32)
+
+    n_channels = values.shape[1]
+    if channels is None:
+        if n_channels <= max_channels:
+            channels = list(range(n_channels))
+        else:
+            channels = np.linspace(0, n_channels - 1, max_channels).round().astype(int).tolist()
+            channels = sorted(set(channels))
+
+    series_list = [values[:, c].astype(np.float32) for c in channels]
+    return series_list, FREQ_MAP[dataset]
+
+
+def build_pretraining_records(
+    dataset: str,
+    spec: WindowSpec,
+    channels: Optional[List[int]] = None,
+    max_channels: int = 4,
+) -> List[Dict]:
+    """Build NanoForecast-format pretraining records from a dataset.
+
+    Each record is a dict with: context, prediction, freq_id,
+    context_covariates (zeros, dim=4 to match the model config).
+    """
+    series_list, freq_id = load_univariate_series(dataset, channels, max_channels)
+
+    L_in = spec.context_len + spec.prediction_len
+    records: List[Dict] = []
+    for s in series_list:
+        s = np.asarray(s, dtype=np.float32)
+        n = s.shape[0]
+        if n < L_in:
+            continue
+        for start in range(0, n - L_in + 1, spec.stride):
+            window = s[start:start + L_in]
+            records.append({
+                "context": window[:spec.context_len],
+                "prediction": window[spec.context_len:spec.context_len + spec.prediction_len],
+                "freq_id": freq_id,
+                "context_covariates": np.zeros((4, spec.context_len), dtype=np.float32),
+                "source": dataset,
+            })
+    return records
+
+
+def build_mixed_pretraining_corpus(
+    spec: WindowSpec,
+    datasets: Optional[List[str]] = None,
+    max_channels_per_dataset: int = 4,
+) -> List[Dict]:
+    """Build a mixed pretraining corpus across multiple datasets."""
+    if datasets is None:
+        datasets = ["ETTh1", "exchange_rate"]  # small + reliable default
+    all_records: List[Dict] = []
+    for ds in datasets:
+        recs = build_pretraining_records(ds, spec, max_channels=max_channels_per_dataset)
+        print(f"[datasets] {ds}: {len(recs)} windows")
+        all_records.extend(recs)
+    print(f"[datasets] total: {len(all_records)} windows")
+    return all_records
+
+
+def time_based_split(
+    records: List[Dict],
+    val_fraction: float = 0.2,
+) -> Tuple[List[Dict], List[Dict]]:
+    """Time-based train/val split: hold out the last ``val_fraction`` of records.
+
+    This avoids look-ahead leakage in pretraining.
+    """
+    if not records:
+        return [], []
+    n = len(records)
+    cut = int(n * (1.0 - val_fraction))
+    return records[:cut], records[cut:]

nanoforecast/evaluation/__init__.py

@@ -0,0 +1 @@
+from nanoforecast.evaluation.benchmark import TimeSeriesEvaluator