time planning evaluation feature

Author: clstaudt

notebooks/walkthrough/.demo_home/tuttle.db-journal

@@ -53,7 +53,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "app = tuttle.app.App()"
+    "app = tuttle.app.App(home_dir=\".demo_home\")"
    ]
   },
   {

notebooks/walkthrough/01-user-setup.ipynb

@@ -54,7 +54,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "app = tuttle.app.App()"
+    "app = tuttle.app.App(home_dir=\".demo_home\")"
    ]
   },
   {
@@ -124,7 +124,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "985d76df8ef041ef9972c10ec83daada",
+       "model_id": "3f3d378ae0a54c1ab6ef7688ec02d25c",
        "version_major": 2,
        "version_minor": 0
       },

notebooks/walkthrough/02-projects-setup.ipynb

@@ -5,13 +5,70 @@
    "id": "eb6a0974-df12-4247-b398-b4e3641b09f3",
    "metadata": {},
    "source": [
-    "# Planning Ahead\n"
+    "# Planning Ahead and Forecasting Revenue\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "be57da1d-f6b1-40db-be21-00aa84d464cc",
+   "metadata": {},
+   "source": [
+    "Planning your time is essential for a freelance business. Tuttle enables you to easily forecast your revenue based on the planning decisions that you make."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "dfd8549c-1e57-43fb-8c15-772f196a8473",
+   "metadata": {},
+   "source": [
+    "## Preamble"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "daf6add6-6e4c-49c0-9967-77b1925cf2ac",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pathlib import Path\n",
+    "import ipywidgets\n",
+    "from IPython import display\n",
+    "import datetime"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "1872b84b-46c8-47ab-8ff6-505d8e555327",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import tuttle"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "10f0f645-f758-4164-8e43-dbe63c147233",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "app = tuttle.app.App()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e5dc0958-2a7d-429c-b9f5-6fe17103864b",
+   "metadata": {},
+   "source": [
+    "## How to Plan Project Time"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "28fda6d1-a61d-4c19-b621-030790f7d149",
+   "id": "232f62f7-706d-47f4-b837-c677af8e332a",
    "metadata": {},
    "outputs": [],
    "source": []

notebooks/walkthrough/03-timetracking-invoicing.ipynb

@@ -3,19 +3,20 @@
 import os
 import sys
 
+import pandas
 import sqlmodel
 
-from . import model
+from . import model, timetracking, dataviz
 
 
 class App:
     """The main application class"""
 
-    def __init__(self, debug_mode=False, verbose=False, in_memory=False):
-        if debug_mode:
-            self.home = Path("./test_home")
-        else:
+    def __init__(self, home_dir=None, verbose=False, in_memory=False):
+        if home_dir is None:
             self.home = Path.home() / ".tuttle"
+        else:
+            self.home = Path(home_dir)
         if not os.path.exists(self.home):
             os.mkdir(self.home)
         if in_memory:
@@ -111,3 +112,52 @@ def get_project(
             return project
         else:
             raise ValueError("either project title or tag required")
+
+    def eval_time_planning(
+        self,
+        planning_source,
+        by="project",
+    ):
+        def duration_to_revenue(
+            row,
+        ):
+            if isinstance(row.name, tuple):
+                tag = row.name[0]
+            else:
+                tag = row.name
+            project = self.get_project(tag=tag)
+            units = row["duration"] / project.contract.unit.to_timedelta()
+            rate = project.contract.rate
+            revenue = units * float(rate)
+            return {
+                "units": units,
+                "revenue": revenue,
+                "currency": project.contract.currency,
+            }
+
+        planning_data = timetracking.get_time_planning_data(
+            planning_source,
+        )
+        if by == "project":
+            grouped_planning_data = (
+                planning_data.filter(["tag", "duration"]).groupby("tag").sum()
+            )
+        elif by == ("month", "project"):
+            grouped_planning_data = (
+                planning_data.filter(["tag", "duration"])
+                .groupby(["tag", pandas.Grouper(freq="1M")])
+                .sum()
+            )
+        else:
+            raise ValueError(f"unrecognized grouping parameter: {by}")
+        # postprocess planning data
+        expanded_data = grouped_planning_data.join(
+            grouped_planning_data.apply(
+                duration_to_revenue, axis=1, result_type="expand"
+            )
+        )
+        plot = dataviz.plot_eval_time_planning(
+            expanded_data,
+            by=by,
+        )
+        return plot

notebooks/walkthrough/04-planning-forecasting.ipynb

@@ -9,14 +9,14 @@
 # ALTAIR THEMES
 
 # Vega color schemes: https://vega.github.io/vega/docs/schemes/
-default_color_scheme = "category20c"
+default_color_scheme = "category20"
 
 
 def tuttle_dark():
     return {
         "config": {
             #'view': {'continuousHeight': 300, 'continuousWidth': 400},  # from the default theme
-            "range": {"category": {"scheme": "category20c"}}
+            "range": {"category": {"scheme": "category20"}}
         }
     }
 
@@ -33,7 +33,46 @@ def enable_theme(theme_name="tuttle_dark"):
         raise ValueError("unknown theme: {theme_name}")
 
 
-@deprecated("Use dataviz.enable_theme('default_dark') instead")
-def enable_dark_theme():
-    """Enable the built-in Altair dark theme"""
-    altair.renderers.set_embed_options(theme="dark")
+def plot_eval_time_planning(
+    planning_data,
+    by,
+):
+    if by == "project":
+        plot_data = (
+            planning_data.reset_index()
+            .filter(["tag", "revenue"])
+            .rename(columns={"tag": "project"})
+        )
+        plot = (
+            altair.Chart(plot_data)
+            .mark_bar()
+            .encode(
+                y="project:N",
+                x="revenue:Q",
+            )
+            .properties(width=600)
+        )
+    elif by == ("month", "project"):
+        plot_data = (
+            planning_data.reset_index()
+            .filter(["tag", "begin", "revenue"])
+            .rename(columns={"tag": "project", "begin": "month_end"})
+        )
+        plot = (
+            altair.Chart(plot_data)
+            .mark_bar()
+            .encode(
+                y=altair.Y(
+                    "yearmonth(month_end):O",
+                    axis=altair.Axis(title="month"),
+                ),
+                x=altair.X(
+                    "revenue:Q",
+                ),
+                color="project:N",
+            )
+            .properties(width=600)
+        )
+    else:
+        raise ValueError(f"unknown mode {by}")
+    return plot

tuttle/app.py

@@ -22,3 +22,5 @@
         "duration": Column(Timedelta),
     },
 )
+
+time_planning = time_tracking  # REVIEW: identical?

tuttle/dataviz.py

@@ -213,14 +213,21 @@ def progress(
     return total_time.loc[tag]["duration"] / budget
 
 
-def eval_time_allocation(
+@check_io(
+    out=schema.time_planning,
+)
+def get_time_planning_data(
     source,
-):
+    from_date: datetime.date = None,
+) -> DataFrame:
+    """Get time planning data from a source."""
+    if from_date is None:
+        from_date = datetime.date.today()
     if issubclass(type(source), Calendar):
         cal = source
-        timetracking_data = cal.to_data()
+        planning_data = cal.to_data()
     elif isinstance(source, pandas.DataFrame):
-        timetracking_data = source
-        schema.time_tracking.validate(timetracking_data)
-
-    return timetracking_data
+        planning_data = source
+        schema.time_tracking.validate(planning_data)
+    planning_data = planning_data[str(from_date) :]
+    return planning_data