URL pathlike for consistent paths.data_dir API (#1797)

* url pathlike implementation

* remove previous way in docstrings

* remove previous way in docs

Author: williambdean

README.md

@@ -85,9 +85,10 @@ from pymc_marketing.mmm import (
     LogisticSaturation,
     MMM,
 )
+from pymc_marketing.paths import data_dir
 
-data_url = "https://raw.githubusercontent.com/pymc-labs/pymc-marketing/main/data/mmm_example.csv"
-data = pd.read_csv(data_url, parse_dates=["date_week"])
+file_path = data_dir / "mmm_example.csv"
+data = pd.read_csv(file_path, parse_dates=["date_week"])
 
 mmm = MMM(
     adstock=GeometricAdstock(l_max=8),
@@ -168,9 +169,10 @@ import matplotlib.pyplot as plt
 import pandas as pd
 import seaborn as sns
 from pymc_marketing import clv
+from pymc_marketing.paths import data_dir
 
-data_url = "https://raw.githubusercontent.com/pymc-labs/pymc-marketing/main/data/clv_quickstart.csv"
-data = pd.read_csv(data_url)
+file_path = data_dir / "clv_quickstart.csv"
+data = pd.read_csv(data_path)
 data["customer_id"] = data.index
 
 beta_geo_model = clv.BetaGeoModel(data=data)

docs/source/getting_started/quickstart/clv/index.md

@@ -7,9 +7,10 @@ import matplotlib.pyplot as plt
 import pandas as pd
 import seaborn as sns
 from pymc_marketing import clv
+from pymc_marketing.paths import data_dir
 
-data_url = "https://raw.githubusercontent.com/pymc-labs/pymc-marketing/main/data/clv_quickstart.csv"
-data = pd.read_csv(data_url)
+file_path = data_dir / "clv_quickstart.csv"
+data = pd.read_csv(file_path)
 data["customer_id"] = data.index
 
 beta_geo_model = clv.BetaGeoModel(data=data)

docs/source/getting_started/quickstart/mmm/index.md

@@ -8,9 +8,10 @@ from pymc_marketing.mmm import (
     LogisticSaturation,
     MMM,
 )
+from pymc_marketing.paths import data_dir
 
-data_url = "https://raw.githubusercontent.com/pymc-labs/pymc-marketing/main/data/mmm_example.csv"
-data = pd.read_csv(data_url, parse_dates=["date_week"])
+file_path = data_dir / "mmm_example.csv"
+data = pd.read_csv(file_path, parse_dates=["date_week"])
 
 mmm = MMM(
     adstock=GeometricAdstock(l_max=8),

pymc_marketing/mlflow.py

@@ -77,14 +77,15 @@
         LogisticSaturation,
         MMM,
     )
+    from pymc_marketing.paths import data_dir
     import pymc_marketing.mlflow
 
     pymc_marketing.mlflow.autolog(log_mmm=True)
 
     # Usual PyMC-Marketing model code
 
-    data_url = "https://raw.githubusercontent.com/pymc-labs/pymc-marketing/main/data/mmm_example.csv"
-    data = pd.read_csv(data_url, parse_dates=["date_week"])
+    file_path = data_dir / "mmm_example.csv"
+    data = pd.read_csv(file_path, parse_dates=["date_week"])
 
     X = data.drop("y", axis=1)
     y = data["y"]
@@ -122,15 +123,16 @@
     import mlflow
 
     from pymc_marketing.clv import BetaGeoModel
+    from pymc_marketing.paths import data_dir
 
     import pymc_marketing.mlflow
 
     pymc_marketing.mlflow.autolog(log_clv=True)
 
     mlflow.set_experiment("CLV Experiment")
 
-    data_url = "https://raw.githubusercontent.com/pymc-labs/pymc-marketing/main/data/clv_quickstart.csv"
-    data = pd.read_csv(data_url)
+    file_path = data_dir / "clv_quickstart.csv"
+    data = pd.read_csv(file_path)
     data["customer_id"] = data.index
 
     model = BetaGeoModel(data=data)
@@ -832,15 +834,16 @@ def log_mmm(
             LogisticSaturation,
             MMM,
         )
+        from pymc_marketing.paths import data_dir
         import pymc_marketing.mlflow
         from pymc_marketing.mlflow import log_mmm
 
         pymc_marketing.mlflow.autolog(log_mmm=True)
 
         # Usual PyMC-Marketing model code
 
-        data_url = "https://raw.githubusercontent.com/pymc-labs/pymc-marketing/main/data/mmm_example.csv"
-        data = pd.read_csv(data_url, parse_dates=["date_week"])
+        file_path = data_dir / "mmm_example.csv"
+        data = pd.read_csv(file_path, parse_dates=["date_week"])
 
         X = data.drop("y", axis=1)
         y = data["y"]
@@ -1117,14 +1120,15 @@ def autolog(
             LogisticSaturation,
             MMM,
         )
+        from pymc_marketing.paths import data_dir
         import pymc_marketing.mlflow
 
         pymc_marketing.mlflow.autolog(log_mmm=True)
 
         # Usual PyMC-Marketing model code
 
-        data_url = "https://raw.githubusercontent.com/pymc-labs/pymc-marketing/main/data/mmm_example.csv"
-        data = pd.read_csv(data_url, parse_dates=["date_week"])
+        file_path = data_dir / "mmm_example.csv"
+        data = pd.read_csv(file_path, parse_dates=["date_week"])
 
         X = data.drop("y", axis=1)
         y = data["y"]
@@ -1163,15 +1167,16 @@ def autolog(
         import mlflow
 
         from pymc_marketing.clv import BetaGeoModel
+        from pymc_marketing.paths import data_dir
 
         import pymc_marketing.mlflow
 
         pymc_marketing.mlflow.autolog(log_clv=True)
 
         mlflow.set_experiment("CLV Experiment")
 
-        data_url = "https://raw.githubusercontent.com/pymc-labs/pymc-marketing/main/data/clv_quickstart.csv"
-        data = pd.read_csv(data_url)
+        file_path = data_dir / "clv_quickstart.csv"
+        data = pd.read_csv(file_path)
         data["customer_id"] = data.index
 
         model = BetaGeoModel(data=data)

pymc_marketing/mmm/evaluation.py

@@ -195,11 +195,12 @@ def compute_summary_metrics(
             LogisticSaturation,
             MMM,
         )
+        from pymc_marketing.paths import data_dir
         from pymc_marketing.mmm.evaluation import compute_summary_metrics
 
         # Usual PyMC-Marketing demo model code
-        data_url = "https://raw.githubusercontent.com/pymc-labs/pymc-marketing/main/data/mmm_example.csv"
-        data = pd.read_csv(data_url, parse_dates=["date_week"])
+        file_path = data_dir / "mmm_example.csv"
+        data = pd.read_csv(file_path, parse_dates=["date_week"])
 
         X = data.drop("y", axis=1)
         y = data["y"]

pymc_marketing/mmm/mmm.py

@@ -940,9 +940,10 @@ class MMM(
             LogisticSaturation
             MMM,
         )
+        from pymc_marketing.paths import data_dir
 
-        data_url = "https://raw.githubusercontent.com/pymc-labs/pymc-marketing/main/data/mmm_example.csv"
-        data = pd.read_csv(data_url, parse_dates=["date_week"])
+        file_path = data_dir / "mmm_example.csv"
+        data = pd.read_csv(file_path, parse_dates=["date_week"])
 
         mmm = MMM(
             date_column="date_week",

pymc_marketing/paths.py

@@ -11,9 +11,80 @@
 #   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 #   See the License for the specific language governing permissions and
 #   limitations under the License.
-"""Paths for the project."""
+"""Paths for the project.
+
+The `data_dir` will be the local directory where the data files are stored in forked
+repositories. If the directory does not exist, it will create a URLPath object pointing
+to the data directory on the main branch of the pymc-labs/pymc-marketing repository.
+
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from os import PathLike
 
 from pyprojroot import here
 
 root = here()
 data_dir = root / "data"
+
+
+URL = "https://raw.githubusercontent.com/pymc-labs/pymc-marketing/{branch}/data"
+
+
+@dataclass
+class URLPath(PathLike):
+    """A class representing a URL path which can be used like a file path.
+
+    Parameters
+    ----------
+    url : str
+        The URL to the data directory or file.
+
+    """
+
+    url: str
+
+    def __fspath__(self) -> str:
+        """Return the URL as a string when the object is used as a file path."""
+        return self.url
+
+    def __truediv__(self, other: str) -> URLPath:
+        """Combine the URL with another path component."""
+        return URLPath(f"{self.url}/{other}")
+
+
+def create_data_url(branch: str) -> URLPath:
+    """Create a URLPath object for the data directory on a specific branch.
+
+    Parameters
+    ----------
+    branch : str
+        The branch name to create the URL for.
+
+    Returns
+    -------
+    URLPath
+        An object representing the URL path to the data directory on the specified branch.
+
+    Examples
+    --------
+    Read MMM data from the main branch:
+
+    .. code-block:: python
+
+        import pandas as pd
+
+        from pymc_marketing.paths import create_data_url
+
+        data_dir = create_data_url("main")
+        file = data_dir / "mmm_example.csv"
+        df = pd.read_csv(file)
+
+    """
+    return URLPath(URL.format(branch=branch))
+
+
+if not data_dir.exists():
+    data_dir = create_data_url("main")

tests/test_paths.py

@@ -11,8 +11,10 @@
 #   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 #   See the License for the specific language governing permissions and
 #   limitations under the License.
+from os import fspath
 from pathlib import Path
 
+import pytest
 from pyprojroot import here
 
 from pymc_marketing import paths
@@ -37,3 +39,28 @@ def test_paths_are_absolute() -> None:
     """Test that all defined paths are absolute."""
     assert paths.root.is_absolute()
     assert paths.data_dir.is_absolute()
+
+
+@pytest.fixture(scope="module")
+def data_url() -> paths.URLPath:
+    return paths.create_data_url("main")
+
+
+def test_create_data_url(data_url) -> None:
+    assert (
+        data_url.url
+        == "https://raw.githubusercontent.com/pymc-labs/pymc-marketing/main/data"
+    )
+
+
+def test_url_path_fspath(data_url) -> None:
+    """Test the __fspath__ method of URLPath."""
+    assert fspath(data_url) == data_url.url
+
+
+def test_url_path_truediv(data_url) -> None:
+    """Test the __truediv__ method of URLPath."""
+    new_path = data_url / "new_file.csv"
+    expected_url = "https://raw.githubusercontent.com/pymc-labs/pymc-marketing/main/data/new_file.csv"
+    assert new_path.url == expected_url
+    assert isinstance(new_path, paths.URLPath)