mobts 0.1.0__tar.gz

mobts-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IFPEN
+
+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.

mobts-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: mobts
+Version: 0.1.0
+Summary: Mobility time series package for preprocessing, imputing, and analyzing mobility count observation data
+Author: Ali SHATERI BENAM
+Project-URL: Documentation, https://mobidec.github.io/mobts/index.html
+Project-URL: Repository, https://github.com/Mobidec/mobts.git
+Project-URL: Issues, https://github.com/Mobidec/mobts/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: statsmodels
+Requires-Dist: scikit-learn
+Requires-Dist: matplotlib
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: sphinx; extra == "dev"
+Requires-Dist: sphinx_design; extra == "dev"
+Requires-Dist: furo; extra == "dev"
+Requires-Dist: sphinx_autopackagesummary; extra == "dev"
+Requires-Dist: sphinxcontrib-napoleon; extra == "dev"
+Requires-Dist: numpydoc; extra == "dev"
+Requires-Dist: myst_nb; extra == "dev"
+Dynamic: license-file
+
+# mobts
+
+> Python package for preprocessing and imputing urban mobility time series data.
+
+Designed for transport datasets such as bike counts, traffic loops, and station-based observations.
+
+---
+
+## What this package does
+
+- Clean time series data:
+ + Detects measurement errors
+ + Flags and removes them 
+
+- Imputes missing/invalid data based on a multi-tier method
+
+---
+
+## Installation
+
+```bash
+pip install mobts
+
+---
+
+## Example of running the code
+
+from mobts import preprocess
+from mobts import impute
+
+# Step 1: clean raw data
+pp = preprocess()
+df_clean = pp.run(df)
+
+# Step 2: impute missing values
+imp = impute()
+df_imputed = imp.run(df_clean)
+
+---
+
+### Functional examples
+
+Full step-by-step examples are available in:
+ - notebooks/demo_preprocessing_imputation.ipynb
+
+## License
+
+This project is licensed under the MIT License, which means it is freely usable for personal and commercial purposes. The MIT License is one of the most permissive open source licenses. It allows you to do almost anything with the source code, as long as you retain the original license notice and copyright information when redistributing the software or substantial portions of it. This license comes without any warranties, so the software is provided "as is." For more details, please refer to the included LICENSE file.

mobts-0.1.0/README.md

@@ -0,0 +1,48 @@
+# mobts
+
+> Python package for preprocessing and imputing urban mobility time series data.
+
+Designed for transport datasets such as bike counts, traffic loops, and station-based observations.
+
+---
+
+## What this package does
+
+- Clean time series data:
+ + Detects measurement errors
+ + Flags and removes them 
+
+- Imputes missing/invalid data based on a multi-tier method
+
+---
+
+## Installation
+
+```bash
+pip install mobts
+
+---
+
+## Example of running the code
+
+from mobts import preprocess
+from mobts import impute
+
+# Step 1: clean raw data
+pp = preprocess()
+df_clean = pp.run(df)
+
+# Step 2: impute missing values
+imp = impute()
+df_imputed = imp.run(df_clean)
+
+---
+
+### Functional examples
+
+Full step-by-step examples are available in:
+ - notebooks/demo_preprocessing_imputation.ipynb
+
+## License
+
+This project is licensed under the MIT License, which means it is freely usable for personal and commercial purposes. The MIT License is one of the most permissive open source licenses. It allows you to do almost anything with the source code, as long as you retain the original license notice and copyright information when redistributing the software or substantial portions of it. This license comes without any warranties, so the software is provided "as is." For more details, please refer to the included LICENSE file.

mobts-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "mobts"
+version = "0.1.0"
+description = "Mobility time series package for preprocessing, imputing, and analyzing mobility count observation data"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    { name = "Ali SHATERI BENAM" }
+]
+dependencies = [
+    "pandas",
+    "numpy",
+    "statsmodels",
+    "scikit-learn",
+    "matplotlib"
+]
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project.urls]
+Documentation = "https://mobidec.github.io/mobts/index.html"
+Repository = "https://github.com/Mobidec/mobts.git"
+Issues = "https://github.com/Mobidec/mobts/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "pre-commit",
+    "build",
+    "twine",
+    "ruff",
+    "sphinx",
+    "sphinx_design",
+    "furo",
+    "sphinx_autopackagesummary",
+    "sphinxcontrib-napoleon",
+    "numpydoc",
+    "myst_nb",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"mobts" = []
+
+[tool.setuptools]
+py-modules = []
+
+[tool.ruff]
+line-length = 140
+exclude = []
+
+[tool.ruff.lint]
+extend-select = [
+  "UP",
+  "E501",
+  "I",
+  "B",
+  "F",
+  "E",
+  "N",
+  "A",
+  "PL",
+  "D"
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ruff.format]
+quote-style = "single"
+indent-style = "space"
+docstring-code-format = true

mobts-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mobts-0.1.0/src/mobts/__init__.py

@@ -0,0 +1,4 @@
+from .main import hello_world
+
+from .preprocessing import run_preprocess_stage_1, apply_threshold, preprocess
+from .imputation import impute

mobts-0.1.0/src/mobts/configs/config_common.py

@@ -0,0 +1,29 @@
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class ColumnsConfig:
+    """
+    Canonical column names used in the pipeline after standardization.
+    """
+
+    counter: str = 'name'
+    timestamp: str = 'timestamp'
+    count: str = 'count'
+
+    weekday: str = 'weekday'
+    week_num: str = 'week_num'
+    how: str = 'how'
+    hour: str = 'hour'
+    date: str = 'date'
+
+
+@dataclass
+class SparsityConfig:
+    """
+    For removing counters with not enough valid counts
+    """
+
+    drop_sparse_counters: bool = True
+    sparse_threshold: float = 0.5

mobts-0.1.0/src/mobts/configs/config_imputation.py

@@ -0,0 +1,64 @@
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class STLConfig:
+    """
+    Config used in STL imputation
+    """
+
+    # STL seasonal period (for daily)
+    stl_season_daily = 7
+    stl_season_hourly = 168
+
+    # clipping
+    clip_lower = 0
+
+    # rollinng median
+    rolling_median_window: int = 2
+    rolling_median_min_valid: int = 1
+
+    # STL robust
+    stl_robust = False
+
+
+@dataclass
+class DonorsConfig:
+    """
+    Configs for Donor-based imputation
+    """
+
+    top_k_donor = 25
+    max_donor_rate = 0.5
+
+    # scaled median
+    sm_min_overlap_day = 60
+    sm_min_overlap_hour = sm_min_overlap_day * 24
+    sm_min_neighbors = 20
+
+    # regression
+    min_mutual_days = 60
+    min_mutual_hours = min_mutual_days * 24
+    min_pred_days = 30
+    min_pred_hours = min_pred_days * 24
+    min_pred_coverage = 0.9
+
+
+@dataclass
+class OutputConfig:
+    """
+    Configs for output columns and final selection
+    """
+
+    # calculated column names
+    col_intp = 'count_intp'
+    col_stl_imputed = 'count_stl_imputed'
+    col_sm_imputed: str = 'count_sm_imputed'
+    col_reg_imputed: str = 'count_reg_imputed'
+    col_final: str = 'count_imputed'
+    col_method_used: str = 'imputation_method'
+
+    stl_method: str = 'STL'
+    sm_method: str = 'M7'
+    reg_method: str = 'M8'

mobts-0.1.0/src/mobts/configs/config_preprocessing.py

@@ -0,0 +1,70 @@
+from dataclasses import dataclass, field
+from typing import Optional
+from .config_common import ColumnsConfig, SparsityConfig
+
+
+@dataclass
+class PreprocessConfig:
+    """
+    Parameters for low-count/zero-run cleaning and operational window trimming.
+    if avail_min_valid days out of avail_window is not present, the whole window will be set as non-operational.
+    """
+
+    low_rel_daily: float = 0.01  # threshold as fraction of station median
+    low_abs_daily: float = 5  # absolute floor threshold to be considered low count noise
+    low_run_min_daily: int = 2  # consecutive low count days to be set to NaN
+
+    zero_rate_max: float = 0.05  # threshold to consider 0s normal
+
+    night_hours = [1, 2, 3, 4, 5, 6]
+
+    zero_run_min: int = 6
+    island_max_len: int = 6
+    surround_min_len: int = 12
+
+
+@dataclass
+class STLConfig:
+    """
+    Parameters for STL decomposition outlier scoring.
+    """
+
+    period: int = 28  # seasonal period in days, set to 4 weeks
+    robust: bool = False  # set to False to avoid heavy computation
+
+
+@dataclass
+class OutlierConfig:
+    """
+    Parameters for thresholding STL outlier scores.
+    """
+
+    threshold_daily: float = 20  # threshold to be tuned via plotting
+    threshold_hourly: float = 45  # threshold to be tuned via plotting
+
+
+@dataclass
+class PlotConfig:
+    """
+    Parameters for plotting the detected outliers.
+    """
+
+    ncols: int = 3
+    figsize_width: float = 15
+    min_fig_height: float = 10
+    height_per_row: float = 3
+    linewidth_d: float = 0.5
+    linewidth_h: float = 0.3
+    marker_size: float = 10
+    x_label_rotation: int = 30
+    max_stations: Optional[int] = None
+
+
+@dataclass
+class PipelineConfig:
+    cols: ColumnsConfig = field(default_factory=ColumnsConfig)
+    sparse: SparsityConfig = field(default_factory=SparsityConfig)
+    preprocess: PreprocessConfig = field(default_factory=PreprocessConfig)
+    stl: STLConfig = field(default_factory=STLConfig)
+    outliers: OutlierConfig = field(default_factory=OutlierConfig)
+    plot: PlotConfig = field(default_factory=PlotConfig)

mobts-0.1.0/src/mobts/divider/__init__.py

@@ -0,0 +1,29 @@
+#!python3
+# -*- coding: utf-8 -*-
+"""
+Module for division operations and custom exceptions.
+
+This module provides functions and exceptions related to division operations.
+It imports the `divide` function and the `CantDivideByZeroError` exception from
+other modules and makes them available for use in this module.
+
+Functions
+---------
+divide(a, b)
+    Divide two numbers, raising a custom exception if the divisor is zero.
+
+Exceptions
+----------
+CantDivideByZeroError
+    Raised when an attempt is made to divide by zero.
+
+Imports
+--------
+- divide: Function for performing division operations.
+- CantDivideByZeroError: Exception raised for division by zero errors.
+"""
+
+from .divider import divide
+from .divider_error import CantDivideByZeroError
+
+__all__ = ['divide', 'CantDivideByZeroError']

mobts-0.1.0/src/mobts/divider/divider.py

@@ -0,0 +1,55 @@
+#!python3
+# -*- coding: utf-8 -*-
+"""
+Module for division operations with custom exceptions.
+
+This module provides a function for performing division
+and raises a custom exception when attempting to divide by zero.
+
+Functions
+---------
+divide(a, b)
+    Divide two numbers, raising a custom exception if the divisor is zero.
+
+Exceptions
+----------
+CantDivideByZeroError
+    Raised when an attempt is made to divide by zero.
+"""
+
+from .divider_error import CantDivideByZeroError
+
+
+def divide(a, b):
+    """
+    Divide two numbers, raising a custom exception if the divisor is zero.
+
+    Parameters
+    ----------
+    a : float
+        The dividend.
+    b : float
+        The divisor.
+
+    Returns
+    -------
+    float
+        The result of the division.
+
+    Raises
+    ------
+    CantDivideByZeroError
+        If the divisor (b) is zero.
+
+    Examples
+    --------
+    >>> divide(10, 2)
+    5.0
+    >>> divide(10, 0)
+    Traceback (most recent call last):
+        ...
+    CantDivideByZeroError
+    """
+    if b == 0:
+        raise CantDivideByZeroError()
+    return a / b

mobts-0.1.0/src/mobts/divider/divider_error.py

@@ -0,0 +1,61 @@
+#!python3
+# -*- coding: utf-8 -*-
+"""
+Module for custom exceptions related to calculator operations.
+
+This module defines custom exceptions used in calculator operations,
+including a base exception class and a specific exception for division by zero errors.
+
+Classes
+-------
+CalculatorError
+    Base class for exceptions in calculator operations.
+CantDivideByZeroError
+    Exception raised when an attempt is made to divide by zero.
+
+Exceptions
+----------
+CalculatorError
+    Base class for exceptions in the calculator domain.
+CantDivideByZeroError
+    Raised specifically for division by zero errors.
+"""
+
+
+class CalculatorError(Exception):
+    """
+    Base class for exceptions in calculator operations.
+
+    This class is intended to be used as a base class for other calculator-related
+    exceptions. It inherits from the built-in Exception class and allows for custom
+    exception handling in the calculator domain.
+
+    Parameters
+    ----------
+    args : tuple
+        Variable length argument list passed to the base Exception class.
+    """
+
+    def __init__(self, *args):
+        super().__init__(args)
+
+
+class CantDivideByZeroError(CalculatorError):
+    """
+    Exception raised when an attempt is made to divide by zero.
+
+    This exception is a specific subclass of CalculatorError and is intended to be
+    used when a division by zero error occurs. It provides a custom error message
+    indicating that division by zero is not allowed.
+
+    Parameters
+    ----------
+    None
+
+    Notes
+    -----
+    The default message for this exception is "tu ne peux pas diviser par zéro".
+    """
+
+    def __init__(self):
+        super().__init__('tu ne peux pas diviser par zéro')

mobts-0.1.0/src/mobts/imputation/__init__.py

@@ -0,0 +1,2 @@
+from .pipeline import impute
+from .donors import impute_scaled_median, impute_regression