firms-sdk 0.1.0__tar.gz

firms_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: firms-sdk
+Version: 0.1.0
+Summary: Basic SDK Client to retrive hotspots data from FIRMS API
+Author: Sebástian Andrés Narváez Salcedo
+Author-email: sebnarvaez19@gmail.com
+Requires-Python: >=3.14
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: pandas (>=3.0.0,<4.0.0)
+Requires-Dist: requests (>=2.32.5,<3.0.0)
+Description-Content-Type: text/markdown
+
+# FIRMS SDK
+
+Basic SDK Client to retrive hotspots data from FIRMS API.
+The client requires the MAP_KEY from NASA and the region of interest to be instanciated.
+
+```py
+from firms_sdk import FIRMSClient
+
+MAP_KEY = "******************************c7"
+REGION = "-75.2736908751,10.2543646415,-74.7146900698,11.1024970837"
+client = FIRMSClient(MAP_KEY, REGION)
+```
+

firms_sdk-0.1.0/README.md

@@ -0,0 +1,12 @@
+# FIRMS SDK
+
+Basic SDK Client to retrive hotspots data from FIRMS API.
+The client requires the MAP_KEY from NASA and the region of interest to be instanciated.
+
+```py
+from firms_sdk import FIRMSClient
+
+MAP_KEY = "******************************c7"
+REGION = "-75.2736908751,10.2543646415,-74.7146900698,11.1024970837"
+client = FIRMSClient(MAP_KEY, REGION)
+```

firms_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "firms-sdk"
+version = "0.1.0"
+description = "Basic SDK Client to retrive hotspots data from FIRMS API"
+authors = [
+    {name = "Sebástian Andrés Narváez Salcedo",email = "sebnarvaez19@gmail.com"}
+]
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "pandas (>=3.0.0,<4.0.0)",
+    "requests (>=2.32.5,<3.0.0)"
+]
+
+[tool.poetry]
+packages = [{include = "firms_sdk", from = "src"}]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

firms_sdk-0.1.0/src/firms_sdk/__init__.py

@@ -0,0 +1,137 @@
+from datetime import datetime
+from urllib.error import HTTPError, URLError
+
+from pandas import DataFrame, Series, concat, read_csv
+from requests import get
+from requests.exceptions import RequestException
+
+from src.firms_sdk.utils import SensorType, format_table, datetime_and_ranges_in_year
+from src.firms_sdk.exceptions import FetchException, check_sensor, check_day_range
+
+
+class Utils:
+    """Utilities for data fetching."""
+
+    def __init__(self):
+        self.datetime_and_ranges_in_year = datetime_and_ranges_in_year
+
+
+class FIRMSClient:
+    """FIRMS Client generator to fetch hotspots data from all sensors."""
+
+    def __init__(self, map_key: str, region: str = "world", region_name: str | None = None):
+        self.base_url = "https://firms.modaps.eosdis.nasa.gov/"
+        self.map_key = map_key
+        self.region = region
+        self.instance_date = datetime.now()
+        self.region_name = region_name
+        self.utils = Utils()
+
+    def __str__(self):
+        return f"FIRMS Client initiated at {self.instance_date}\
+              \nRegion: {self.region_name + " - " if self.region_name else ""}[{self.region}]"
+
+    def __repr__(self):
+        return self.__str__()
+
+    @property
+    def status(self) -> Series:
+        """Fetch MAP KEY status info.
+
+        Raises:
+            FetchException: unable to reach server for data.
+
+        Returns:
+            Series: transactions limit, transactions done, and refreshing time info
+        """
+        try:
+            response = get(self.base_url + "mapserver/mapkey_status/?MAP_KEY=" + self.map_key, timeout=3600)
+            data = response.json()
+            s = Series(data)
+            s.name = "Status"
+            return s
+        except RequestException as e:
+            raise FetchException(e.args)
+
+    @property
+    def data_available(self) -> DataFrame:
+        """Available sensors to fetch data.
+
+        Raises:
+            FetchException: unable to reach server for data.
+
+        Returns:
+            DataFrame: Sensors data.
+        """
+        try:
+            f_url = self.base_url + "api/data_availability/csv/" + self.map_key + "/all"
+            return read_csv(f_url)
+        except (HTTPError, URLError) as e:
+            raise FetchException(e.args)
+
+    def get_data(self, sensor: SensorType, day_range: int, date_init: datetime) -> DataFrame:
+        """Fetch hotspots from sensor in the specified date range.
+
+        Args:
+            sensor (SensorType): Sensor of interest.
+            day_range (int): Number of days in advance to search (between 1-5).
+            date_init (datetime): date of interest.
+
+        Raises:
+            FetchException: Data not available.
+
+        Returns:
+            DataFrame: hotspots dataframe.
+        """
+        check_day_range(day_range)
+        check_sensor(sensor)
+        f_url = f"{self.base_url}api/area/csv/{self.map_key}/{sensor}/{self.region}/{day_range}/{date_init.strftime("%Y-%m-%d")}"
+        try:
+            df = read_csv(f_url, parse_dates=["acq_date"])
+            d, hh, mm = df["acq_date"], df["acq_time"] // 100, df["acq_time"] % 100
+            dt_vector = [datetime(d.year, d.month, d.day, hour, minute) for d, hour, minute in zip(d, hh, mm)]
+            df = df.drop(columns=["acq_date", "acq_time"])
+            df["datetime"] = dt_vector
+            return format_table(df)
+        except (HTTPError, URLError) as e:
+            raise FetchException(e.args)
+
+    def get_sp_data(self, day_range: int, date_init: datetime) -> DataFrame:
+        """Fetch validate hotspots from FIRMS.
+
+        Args:
+            day_range (int): Number of days in advance to search (between 1-5).
+            date_init (datetime): date of interest.
+
+        Returns:
+            DataFrame: hotspots dataframe.
+        """
+        sensors: list[SensorType] = ["MODIS_SP", "VIIRS_NOAA20_SP", "VIIRS_SNPP_SP"]
+        dfs = [self.get_data(sensor, day_range, date_init) for sensor in sensors]
+        return concat(dfs, ignore_index=True)
+
+    def get_nrt_data(self, day_range: int, date_init: datetime) -> DataFrame:
+        """Fetch near-real-time hotspots from FIRMS (no validated by NASA).
+
+        Args:
+            day_range (int): Number of days in advance to search (between 1-5).
+            date_init (datetime): date of interest.
+
+        Returns:
+            DataFrame: hotspots dataframe.
+        """
+        sensors: list[SensorType] = ["MODIS_NRT", "VIIRS_NOAA20_NRT", "VIIRS_NOAA21_NRT", "VIIRS_SNPP_NRT"]
+        dfs = [self.get_data(sensor, day_range, date_init) for sensor in sensors]
+        return format_table(concat(dfs, ignore_index=True))
+
+    def get_all_data(self, day_range: int, date_init: datetime) -> DataFrame:
+        """Fetch near-real-time and validated hotspots data.
+
+        Args:
+            day_range (int): Number of days in advance to search (between 1-5).
+            date_init (datetime): date of interest.
+
+        Returns:
+            DataFrame: hotspots dataframe.
+        """
+        return format_table(concat([self.get_sp_data(day_range, date_init), self.get_nrt_data(day_range, date_init)], ignore_index=True))

firms_sdk-0.1.0/src/firms_sdk/exceptions.py

@@ -0,0 +1,69 @@
+from typing import Any
+
+from src.firms_sdk.utils import SensorType
+
+
+class FetchException(Exception):
+    """Fetch Exception message."""
+
+    def __init__(self, *args):
+        super().__init__(*args)
+
+
+class SensorException(FetchException):
+    """No valid sensor error message."""
+
+    def __init__(self, value: Any):
+        message = f"Sensor must be one between: \
+            'MODIS_NRT', 'MODIS_SP', 'VIIRS_NOAA20_NRT', 'VIIRS_NOAA20_SP', 'VIIRS_NOAA21_NRT', 'VIIRS_SNPP_NRT', 'VIIRS_SNPP_SP' \
+            , not {value}"
+        super().__init__(message)
+
+
+class DayRangeException(FetchException):
+    """No valid day range."""
+
+    def __init__(self, value: Any):
+        message = f"Day range must be a value between 1 or 5 days in advance, not {value}"
+        super().__init__(message)
+
+
+def check_sensor(sensor: SensorType):
+    """Validate sensor input.
+
+    Args:
+        sensor (SensorType): sensor to validate.
+
+    Raises:
+        TypeError: Sensor is not string.
+        SensorException: Sensor is not one of available.
+    """
+    available_sensors = [
+        "MODIS_NRT",
+        "MODIS_SP",
+        "VIIRS_NOAA20_NRT",
+        "VIIRS_NOAA20_SP",
+        "VIIRS_NOAA21_NRT",
+        "VIIRS_SNPP_NRT",
+        "VIIRS_SNPP_SP",
+    ]
+    if not isinstance(sensor, str):
+        raise TypeError(f"Sensor must be string type, not {type(sensor)}")
+    if sensor not in available_sensors:
+        raise SensorException(sensor)
+
+
+def check_day_range(day_range: int):
+    """Validate day_range input.
+
+    Args:
+        day_range (int): day range to validate.
+
+    Raises:
+        TypeError: Day range is not int.
+        DayRangeException: Day range is not between 1-5 range.
+    """
+    if not isinstance(day_range, int):
+        raise TypeError(f"Day range must be integer, not {type(day_range)}")
+    if day_range <= 0 or day_range > 5:
+        raise DayRangeException(day_range)

firms_sdk-0.1.0/src/firms_sdk/utils.py

@@ -0,0 +1,75 @@
+from datetime import datetime, timedelta
+from typing import Literal
+import numpy as np
+from pandas import DataFrame, StringDtype
+
+SensorType = Literal[
+    "MODIS_NRT",
+    "MODIS_SP",
+    "VIIRS_NOAA20_NRT",
+    "VIIRS_NOAA20_SP",
+    "VIIRS_NOAA21_NRT",
+    "VIIRS_SNPP_NRT",
+    "VIIRS_SNPP_SP",
+    "all",
+]
+
+
+def format_table(df: DataFrame) -> DataFrame:
+    """Format FIRMS table for all available options.
+
+    Args:
+        df (DataFrame): base dataframe.
+
+    Returns:
+        (DataFrame): dataframe processed.
+    """
+    type_map = {
+        "latitude": np.dtype("float64"),
+        "longitude": np.dtype("float64"),
+        "datetime": np.dtype("datetime64[us]"),
+        "scan": np.dtype("float64"),
+        "track": np.dtype("float64"),
+        "satellite": StringDtype(),
+        "instrument": StringDtype(),
+        "type": np.dtype("int64"),
+        "version": np.dtype("float64"),
+        "confidence": StringDtype(),
+        "brightness": np.dtype("float64"),
+        "bright_t31": np.dtype("float64"),
+        "bright_ti4": np.dtype("float64"),
+        "bright_ti5": np.dtype("float64"),
+    }
+    for key, value in type_map.items():
+        try:
+            df[key] = df[key].astype(value)
+        except KeyError:
+            df[key] = None
+            df[key] = df[key].astype(value)
+    return df[type_map.keys()]
+
+
+def datetime_and_ranges_in_year(year: int) -> list[tuple[datetime, int]]:
+    """Get datetime and day_ranges pairs list for the specified year.
+
+    Args:
+        year (int): year of interest.
+
+    Returns:
+        list[tuple[datetime, int]]: list of datetime-day_range pairs.
+    """
+    first_date = datetime(year, 1, 1)
+    final_date = datetime(year, 12, 31)
+    dates = [(first_date, 5)]
+    while True:
+        current_date = dates[len(dates) - 1][0]
+        current_day_range = dates[len(dates) - 1][1]
+        if current_date + timedelta(days=current_day_range) >= final_date:
+            break
+        next_date = current_date + timedelta(days=current_day_range)
+        to_final_date = final_date - next_date
+        if to_final_date.days > 5:
+            dates.append((next_date, 5))
+        else:
+            dates.append((next_date, to_final_date.days))
+    return dates