atmoswing-api 0.1.0__py3-none-any.whl

app/main.py

@@ -0,0 +1,23 @@
+import logging
+from fastapi import FastAPI
+from app.routes import meta, forecasts, aggregations
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s -%(levelname)s - %(message)s",
+    handlers=[
+        logging.StreamHandler()
+    ]
+)
+
+app = FastAPI(
+    title="AtmoSwing Web Forecast API",
+    description="API to provide forecasts generated by AtmoSwing.",
+    version="1.0.0",
+)
+
+# Include the routes
+app.include_router(meta.router, prefix="/meta", tags=["Metadata"])
+app.include_router(forecasts.router, prefix="/forecasts", tags=["Data from a single forecast"])
+app.include_router(aggregations.router, prefix="/aggregations", tags=["Aggregated forecast data"])

app/models/forecast.py

@@ -0,0 +1,120 @@
+from pydantic import BaseModel, field_validator
+from typing import List
+from datetime import datetime
+
+
+class ReferenceValues(BaseModel):
+    axis: List[float]
+    values: List[float]
+
+    @field_validator("axis")
+    def round_axis(cls, v: List[float]) -> List[float]:
+        return [round(float(value), 2) for value in v]
+
+    @field_validator("values")
+    def round_values(cls, v: List[float]) -> List[float]:
+        return [round(float(value), 2) for value in v]
+
+
+class Analog(BaseModel):
+    date: datetime
+    value: float
+    criteria: float
+    rank: int
+
+    @field_validator("value")
+    def round_value(cls, v: float) -> float:
+        return round(float(v), 2)
+
+    @field_validator("criteria")
+    def round_criteria(cls, v: float) -> float:
+        return round(float(v), 3)
+
+
+class Analogs(BaseModel):
+    analogs: List[Analog]
+
+
+class AnalogValues(BaseModel):
+    values: List[float]
+
+    @field_validator("values")
+    def round_values(cls, v: List[float]) -> List[float]:
+        return [round(float(value), 2) for value in v]
+
+
+class AnalogValuesPercentiles(BaseModel):
+    percentiles: List[int]
+    values: List[float]
+
+    @field_validator("values")
+    def round_values(cls, v: List[float]) -> List[float]:
+        return [round(float(value), 2) for value in v]
+
+
+class AnalogDates(BaseModel):
+    dates: List[datetime]
+
+
+class AnalogCriteria(BaseModel):
+    criteria: List[float]
+
+    @field_validator("criteria")
+    def round_criteria(cls, v: List[float]) -> List[float]:
+        return [round(float(value), 3) for value in v]
+
+
+class SeriesAnalogValues(BaseModel):
+    series_values: List[List[float]]
+
+    @field_validator("series_values")
+    def round_series(cls, v: List[List[float]]) -> List[List[float]]:
+        return [[round(float(value), 2) for value in series] for series in v]
+
+
+class SeriesAnalogValuesPercentile(BaseModel):
+    percentile: int
+    series_values: List[float]
+
+    @field_validator("series_values")
+    def round_series(cls, v: List[float]) -> List[float]:
+        return [round(float(value), 2) for value in v]
+
+
+class SeriesAnalogValuesPercentiles(BaseModel):
+    forecast_date: datetime
+    target_dates: List[datetime]
+    series_percentiles: List[SeriesAnalogValuesPercentile]
+
+
+class SeriesAnalogValuesPercentilesHistory(BaseModel):
+    past_forecasts: List[SeriesAnalogValuesPercentiles]
+
+
+class EntitiesAnalogValuesPercentile(BaseModel):
+    entity_ids: List[int]
+    values: List[float]
+
+    @field_validator("values")
+    def round_values(cls, v: List[float]) -> List[float]:
+        return [round(float(value), 2) for value in v]
+
+
+class SeriesSynthesisPerMethod(BaseModel):
+    method_id: str
+    target_dates: List[datetime]
+    values: List[float]
+
+    @field_validator("values")
+    def round_values(cls, v: List[float]) -> List[float]:
+        return [round(float(value), 2) for value in v]
+
+
+class SeriesSynthesisTotal(BaseModel):
+    time_step: int
+    target_dates: List[datetime]
+    values: List[float]
+
+    @field_validator("values")
+    def round_values(cls, v: List[float]) -> List[float]:
+        return [round(float(value), 2) for value in v]

app/models/meta.py

@@ -0,0 +1,23 @@
+from pydantic import BaseModel
+from typing import List
+from typing import Optional
+
+class Method(BaseModel):
+    id: str
+    name: str
+
+class Configuration(BaseModel):
+    id: str
+    name: str
+
+class MethodConfig(BaseModel):
+    id: str
+    name: str
+    configurations: List[Configuration]
+
+class Entity(BaseModel):
+    id: int
+    name: str
+    x: float
+    y: float
+    official_id: Optional[str] = None

app/routes/aggregations.py

@@ -0,0 +1,89 @@
+import logging
+from typing import List
+from functools import lru_cache
+from fastapi import APIRouter, HTTPException, Depends, Query
+from typing_extensions import Annotated
+
+import config
+from app.models.forecast import *
+from app.services.aggregations import *
+
+router = APIRouter()
+debug = False
+
+
+@lru_cache
+def get_settings():
+    return config.Settings()
+
+
+# Helper function to handle requests and catch exceptions
+async def _handle_request(func, settings: config.Settings, region: str, **kwargs):
+    try:
+        result = await func(settings.data_dir, region, **kwargs)
+        if debug:
+            logging.info(f"Result from {func.__name__}: {result}")
+        if result is None:
+            raise ValueError("The result is None")
+        return result
+    except FileNotFoundError:
+        logging.error(f"Files not found for region: {region}")
+        raise HTTPException(status_code=404, detail="Region or forecast not found")
+    except Exception as e:
+        logging.error(f"An unexpected error occurred: {e}")
+        raise HTTPException(status_code=500, detail="Internal Server Error")
+
+
+@router.get("/{region}/{forecast_date}/{method}/{lead_time}/analog-values-percentile/{percentile}",
+            summary="Analog values for a given region, forecast_date, method, "
+                    "lead time, and percentile, aggregated by selecting the "
+                    "relevant configuration per entity",
+            response_model=EntitiesAnalogValuesPercentile)
+async def entities_analog_values_percentile(
+        region: str,
+        forecast_date: str,
+        method: str,
+        lead_time: int|str,
+        percentile: int,
+        settings: Annotated[config.Settings, Depends(get_settings)]):
+    """
+    Get the analog dates for a given region, forecast_date, method, configuration, and lead_time.
+    """
+    return await _handle_request(get_entities_analog_values_percentile, settings,
+                                 region, forecast_date=forecast_date, method=method,
+                                 lead_time=lead_time, percentile=percentile)
+
+
+@router.get("/{region}/{forecast_date}/series-synthesis-per-method/{percentile}",
+            summary="Largest values for a given region, forecast_date, method, "
+                    "and percentile, aggregated by selecting the largest values for "
+                    "the relevant configurations per entity",
+            response_model=List[SeriesSynthesisPerMethod])
+async def series_synthesis_per_method(
+        region: str,
+        forecast_date: str,
+        percentile: int,
+        settings: Annotated[config.Settings, Depends(get_settings)]):
+    """
+    Get the largest analog values for a given region, forecast_date, and percentile.
+    """
+    return await _handle_request(get_series_synthesis_per_method, settings,
+                                 region, forecast_date=forecast_date,
+                                 percentile=percentile)
+
+
+@router.get("/{region}/{forecast_date}/series-synthesis-total/{percentile}",
+            summary="Largest values for a given region, forecast_date, "
+                    "and percentile, aggregated by time steps",
+            response_model=List[SeriesSynthesisTotal])
+async def series_synthesis_total(
+        region: str,
+        forecast_date: str,
+        percentile: int,
+        settings: Annotated[config.Settings, Depends(get_settings)]):
+    """
+    Get the largest analog values for a given region, forecast_date, and percentile.
+    """
+    return await _handle_request(get_series_synthesis_total, settings,
+                                 region, forecast_date=forecast_date,
+                                 percentile=percentile)

app/routes/forecasts.py

@@ -0,0 +1,251 @@
+import logging
+from typing import List
+from functools import lru_cache
+from fastapi import APIRouter, HTTPException, Depends, Query
+from typing_extensions import Annotated
+
+import config
+from app.models.forecast import *
+from app.services.forecasts import *
+
+router = APIRouter()
+debug = False
+
+
+@lru_cache
+def get_settings():
+    return config.Settings()
+
+
+# Helper function to handle requests and catch exceptions
+async def _handle_request(func, settings: config.Settings, region: str, **kwargs):
+    try:
+        result = await func(settings.data_dir, region, **kwargs)
+        if debug:
+            logging.info(f"Result from {func.__name__}: {result}")
+        if result is None:
+            raise ValueError("The result is None")
+        return result
+    except FileNotFoundError:
+        logging.error(f"Files not found for region: {region}")
+        raise HTTPException(status_code=404, detail="Region or forecast not found")
+    except Exception as e:
+        logging.error(f"An unexpected error occurred: {e}")
+        raise HTTPException(status_code=500, detail="Internal Server Error")
+
+
+@router.get("/{region}/{forecast_date}/{method}/{configuration}/{lead_time}/analog-dates",
+            summary="Analog dates for a given forecast and target date",
+            response_model=AnalogDates)
+async def analog_dates(
+        region: str,
+        forecast_date: str,
+        method: str,
+        configuration: str,
+        lead_time: int|str,
+        settings: Annotated[config.Settings, Depends(get_settings)]):
+    """
+    Get the analog dates for a given region, forecast date, method, configuration, and lead time.
+    """
+    return await _handle_request(get_analog_dates, settings, region,
+                                 forecast_date=forecast_date, method=method,
+                                 configuration=configuration, lead_time=lead_time)
+
+
+@router.get("/{region}/{forecast_date}/{method}/{configuration}/{lead_time}/analogy-criteria",
+            summary="Analog criteria for a given forecast and target date",
+            response_model=AnalogCriteria)
+async def analog_criteria(
+        region: str,
+        forecast_date: str,
+        method: str,
+        configuration: str,
+        lead_time: int|str,
+        settings: Annotated[config.Settings, Depends(get_settings)]):
+    """
+    Get the analog criteria for a given region, forecast date, method, configuration, and lead time.
+    """
+    return await _handle_request(get_analog_criteria, settings, region,
+                                 forecast_date=forecast_date, method=method,
+                                 configuration=configuration, lead_time=lead_time)
+
+
+@router.get("/{region}/{forecast_date}/{method}/{configuration}/{lead_time}/entities-values-percentile/{percentile}",
+            summary="Values for all entities for a given quantile, forecast and target date",
+            response_model=EntitiesAnalogValuesPercentile)
+async def entities_analog_values_percentile(
+        region: str,
+        forecast_date: str,
+        method: str,
+        configuration: str,
+        lead_time: int|str,
+        percentile: int,
+        settings: Annotated[config.Settings, Depends(get_settings)]):
+    """
+    Get the precipitation values for a given region, forecast date, method, configuration, lead time, and percentile.
+    """
+    return await _handle_request(get_entities_analog_values_percentile, settings, region,
+                                 forecast_date=forecast_date, method=method,
+                                 configuration=configuration, lead_time=lead_time,
+                                 percentile=percentile)
+
+
+@router.get("/{region}/{forecast_date}/{method}/{configuration}/{entity}/reference-values",
+            summary="Reference values (e.g. for different return periods) for a given entity",
+            response_model=ReferenceValues)
+async def reference_values(
+        region: str,
+        forecast_date: str,
+        method: str,
+        configuration: str,
+        entity: int,
+        settings: Annotated[config.Settings, Depends(get_settings)]):
+    """
+    Get the reference values for a given region, forecast date, method, configuration, and entity.
+    """
+    return await _handle_request(get_reference_values, settings, region,
+                                 forecast_date=forecast_date, method=method,
+                                 configuration=configuration, entity=entity)
+
+
+@router.get("/{region}/{forecast_date}/{method}/{configuration}/{entity}/series-values-best-analogs",
+    summary="Analog values of the best analogs for a given entity (time series)",
+    response_model=SeriesAnalogValues)
+async def series_analog_values_best(
+        region: str,
+        forecast_date: str,
+        method: str,
+        configuration: str,
+        entity: int,
+        settings: Annotated[config.Settings, Depends(get_settings)],
+        number: int = 10):
+    """
+    Get the precipitation values for the best analogs and for a given region, forecast date, method, configuration, and entity.
+    """
+    return await _handle_request(get_series_analog_values_best, settings, region,
+                                 forecast_date=forecast_date, method=method,
+                                 configuration=configuration, entity=entity,
+                                 number=number)
+
+
+@router.get("/{region}/{forecast_date}/{method}/{configuration}/{entity}/series-values-percentiles",
+    summary="Values for one entity for a given quantile, forecast and target date",
+    response_model=SeriesAnalogValuesPercentiles)
+async def series_analog_values_percentiles(
+        region: str,
+        forecast_date: str,
+        method: str,
+        configuration: str,
+        entity: int,
+        settings: Annotated[config.Settings, Depends(get_settings)],
+        percentiles: List[int] = Query([20, 60, 90])):
+    """
+    Get the precipitation values for the provided percentiles and for a given region, forecast date, method, configuration, and entity.
+    """
+    return await _handle_request(get_series_analog_values_percentiles, settings, region,
+                                 forecast_date=forecast_date, method=method,
+                                 configuration=configuration, entity=entity,
+                                 percentiles=percentiles)
+
+
+@router.get("/{region}/{forecast_date}/{method}/{configuration}/{entity}/series-values-percentiles-history",
+    summary="Values for one entity for a given quantile, forecast and target date",
+    response_model=SeriesAnalogValuesPercentilesHistory)
+async def series_analog_values_percentiles_history(
+        region: str,
+        forecast_date: str,
+        method: str,
+        configuration: str,
+        entity: int,
+        settings: Annotated[config.Settings, Depends(get_settings)],
+        percentiles: List[int] = Query([20, 60, 90]),
+        number: int = 5):
+    """
+    Get the precipitation values for the provided percentiles and for a given region, forecast date, method, configuration, and entity.
+    """
+    return await _handle_request(get_series_analog_values_percentiles_history, settings,
+                                 region, forecast_date=forecast_date, method=method,
+                                 configuration=configuration, entity=entity,
+                                 percentiles=percentiles, number=number)
+
+
+@router.get("/{region}/{forecast_date}/{method}/{configuration}/{entity}/{lead_time}/analogs",
+            summary="Details of the analogs (rank, date, criteria, value) for a given forecast and entity",
+            response_model=Analogs)
+async def analogs(
+        region: str,
+        forecast_date: str,
+        method: str,
+        configuration: str,
+        entity: int,
+        lead_time: int|str,
+        settings: Annotated[config.Settings, Depends(get_settings)]):
+    """
+    Get the analogs for a given region, forecast date, method, configuration, entity, and lead time.
+    """
+    return await _handle_request(get_analogs, settings, region,
+                                 forecast_date=forecast_date, method=method,
+                                 configuration=configuration, entity=entity,
+                                 lead_time=lead_time)
+
+
+@router.get("/{region}/{forecast_date}/{method}/{configuration}/{entity}/{lead_time}/analog-values",
+    summary="Analog values for a given entity and target date",
+    response_model=AnalogValues)
+async def analog_values(
+        region: str,
+        forecast_date: str,
+        method: str,
+        configuration: str,
+        entity: int,
+        lead_time: int|str,
+        settings: Annotated[config.Settings, Depends(get_settings)]):
+    """
+    Get the precipitation values for a given region, forecast date, method, configuration, entity, lead time.
+    """
+    return await _handle_request(get_analog_values, settings, region,
+                                 forecast_date=forecast_date, method=method,
+                                 configuration=configuration, entity=entity,
+                                 lead_time=lead_time)
+
+
+@router.get("/{region}/{forecast_date}/{method}/{configuration}/{entity}/{lead_time}/analog-values-percentiles",
+            summary="Values for one entity for a given quantile, forecast and target date",
+            response_model=AnalogValuesPercentiles)
+async def analog_values_percentiles(
+        region: str,
+        forecast_date: str,
+        method: str,
+        configuration: str,
+        entity: int,
+        lead_time: int|str,
+        settings: Annotated[config.Settings, Depends(get_settings)],
+        percentiles: List[int] = Query([20, 60, 90])):
+    """
+    Get the precipitation values for a given region, forecast date, method, configuration, entity, lead time, and percentile.
+    """
+    return await _handle_request(get_analog_values_percentiles, settings, region,
+                                 forecast_date=forecast_date, method=method,
+                                 configuration=configuration, entity=entity,
+                                 lead_time=lead_time, percentiles=percentiles)
+
+
+@router.get("/{region}/{forecast_date}/{method}/{configuration}/{entity}/{lead_time}/analog-values-best",
+            summary="Values for one entity for a given quantile, forecast and target date",
+            response_model=AnalogValues)
+async def analog_values_best(
+        region: str,
+        forecast_date: str,
+        method: str,
+        configuration: str,
+        entity: int,
+        lead_time: int|str,
+        settings: Annotated[config.Settings, Depends(get_settings)],
+        number: int = 10):
+    """
+    Get the precipitation values for the best analogs and for a given region, forecast date, method, configuration, entity, and lead time.
+    """
+    return await _handle_request(get_analog_values_best, settings, region,
+                                 forecast_date=forecast_date, method=method,
+                                 configuration=configuration, entity=entity,
+                                 lead_time=lead_time, number=number)

app/routes/meta.py

@@ -0,0 +1,85 @@
+import logging
+from functools import lru_cache
+from fastapi import APIRouter, HTTPException, Depends
+from typing_extensions import Annotated
+from typing import List
+
+import config
+from app.services.meta import get_last_forecast_date_from_files, \
+    get_method_list, get_method_configs_list, get_entities_list
+from app.models.meta import Entity, Method, MethodConfig
+
+router = APIRouter()
+
+
+@lru_cache
+def get_settings():
+    return config.Settings()
+
+
+# Helper function to handle requests and catch exceptions
+async def _handle_request(func, settings: config.Settings, region: str, **kwargs):
+    try:
+        return await func(settings.data_dir, region, **kwargs)
+    except FileNotFoundError:
+        logging.error(f"Files not found for region: {region}")
+        raise HTTPException(status_code=404, detail="Region or forecast not found")
+    except Exception as e:
+        logging.error(f"An unexpected error occurred: {e}")
+        raise HTTPException(status_code=500, detail="Internal Server Error")
+
+
+@router.get("/{region}/last-forecast-date",
+            summary="Last available forecast date")
+async def get_last_forecast_date(
+        region: str,
+        settings: Annotated[config.Settings, Depends(get_settings)]):
+    """
+    Get the last available forecast date for a given region.
+    """
+    return await _handle_request(get_last_forecast_date_from_files, settings, region)
+
+
+@router.get("/{region}/{forecast_date}/methods",
+            summary="List of available methods",
+            response_model=List[Method])
+async def list_methods(
+        region: str,
+        forecast_date: str,
+        settings: Annotated[config.Settings, Depends(get_settings)]):
+    """
+    Get the list of available methods for a given region.
+    """
+    return await _handle_request(get_method_list, settings, region,
+                                 forecast_date=forecast_date)
+
+
+@router.get("/{region}/{forecast_date}/methods-and-configs",
+            summary="List of available methods and configurations",
+            response_model=List[MethodConfig])
+async def list_methods_and_configs(
+        region: str,
+        forecast_date: str,
+        settings: Annotated[config.Settings, Depends(get_settings)]):
+    """
+    Get the list of available methods and configs for a given region.
+    """
+    return await _handle_request(get_method_configs_list, settings, region,
+                                 forecast_date=forecast_date)
+
+
+@router.get("/{region}/{forecast_date}/{method}/{configuration}/entities",
+            summary="List of available entities",
+            response_model=List[Entity])
+async def list_entities(
+        region: str,
+        forecast_date: str,
+        method: str,
+        configuration: str,
+        settings: Annotated[config.Settings, Depends(get_settings)]):
+    """
+    Get the list of available entities for a given region, forecast_date, method, and configuration.
+    """
+    return await _handle_request(get_entities_list, settings, region,
+                                 forecast_date=forecast_date, method=method,
+                                 configuration=configuration)