clearer feedback (exception) when there is no data (#11)

Author: Lennart

notebooks/process_analysis.ipynb

@@ -23,18 +23,27 @@
   },
   {
    "cell_type": "raw",
+   "metadata": {
+    "collapsed": false
+   },
    "source": [
     "# Status Transitions graph\n",
     "\n",
-    "Display a directed graph of status transitions of the issues data from an issue tracker (e.g., Jira).\n",
+    "Display a directed graph of status transitions of the issues data from an issue tracker.\n",
     "\n",
     "This graph can give an overview like a value stream map and highlights potential waste like delays and rework.\n",
     "\n",
-    "> **_NOTE:_**  Requires [graphviz](https://graphviz.org/download/) to be installed locally."
-   ],
-   "metadata": {
-    "collapsed": false
-   }
+    "> **_NOTE:_** Requires [graphviz](https://graphviz.org/download/) to be installed locally.\n",
+    "\n",
+    "## How to interpret the graph:\n",
+    "- Each node represents a status of an issue.\n",
+    "- The color of the node represents the category of the status (e.g., To Do, In Progress, Done).\n",
+    "- Each edge represents a transition from one status to another.\n",
+    "- The number of times that transition has occurred is shown on the edge, and the thickness of the edge is proportional to the number of transitions.\n",
+    "\n",
+    "Issue tracker tested: JIRA.\n",
+    "Other DevLake plugins might not provide the necessary data to generate the graph. An error will be shown if the data is not available."
+   ]
   },
   {
    "cell_type": "code",
@@ -52,22 +61,26 @@
     "from playground.process_analysis.status_transition_graph_vistualizer import StatusTransitionGraphVisualizer, StatisticLabelConfig\n",
     "from playground.process_analysis.utils.status_transition_data_generator import generate_random_status_changes\n",
     "\n",
+    "# Connection to the devlake database\n",
+    "DB_URL = \"mysql://merico:merico@127.0.0.1:3306/lake\"\n",
+    "# Specify the filter for the issues to be included in the graph\n",
+    "ISSUE_FILTER = IssueFilter(\n",
+    "    # Example usage:\n",
+    "    # issue_type = \"Story\",\n",
+    "    # from_date = pd.Timestamp(datetime.strptime(\"2020-01-01\", \"%Y-%m-%d\"))\n",
+    ")\n",
+    "# For demo purposes, the following flag can be set to true to generate some random data\n",
+    "USE_DEMO_DATA = False\n",
     "\n",
-    "DB_URL = \"mysql://root:admin@127.0.0.1:3306/lake\"\n",
     "\n",
     "if not StatusTransitionGraphVisualizer.is_dot_executable_available():\n",
     "    print(\"dot executable not found, please install graphviz\")\n",
     "\n",
-    "issue_filter = IssueFilter(\n",
-    "    # Example usage:\n",
-    "    # issue_type = \"Story\",\n",
-    "    # from_date = pd.Timestamp(datetime.strptime(\"2000-01-01\", \"%Y-%m-%d\"))\n",
-    ") \n",
-    "process_graph = StatusTransitionGraph.from_database(create_db_engine(DB_URL), issue_filter=issue_filter)\n",
-    "\n",
-    "# For demo purpose, enable the following lines to generate some random data\n",
-    "# data_frame = generate_random_status_changes(5000)\n",
-    "# process_graph = StatusTransitionGraph.from_data_frame(data_frame, issue_filter=issue_filter)\n",
+    "if not USE_DEMO_DATA:\n",
+    "    process_graph = StatusTransitionGraph.from_database(create_db_engine(DB_URL), issue_filter=ISSUE_FILTER)\n",
+    "else:\n",
+    "    data_frame = generate_random_status_changes(5000)\n",
+    "    process_graph = StatusTransitionGraph.from_data_frame(data_frame, issue_filter=ISSUE_FILTER)\n",
     "\n",
     "svg = StatusTransitionGraphVisualizer().visualize(process_graph, threshold=0.99, label_statistic = StatisticLabelConfig.MEDIAN)\n",
     "display(svg)"
@@ -116,7 +129,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.1"
+   "version": "3.12.2"
   }
  },
  "nbformat": 4,

playground/process_analysis/status_transition_graph.py

@@ -98,10 +98,11 @@ def from_data_frame(cls, df: pd.DataFrame, issue_filter: IssueFilter | None = No
         Note: The DataFrame must have a column for each field in the StatusChange class.
         """
 
-        process_graph: StatusTransitionGraph = cls()
-
         if df.empty:
-            return process_graph
+            raise ValueError("Provided DataFrame is empty" +
+                            "no status transitions in the 'issue_changelogs' table were found.")
+
+        process_graph: StatusTransitionGraph = cls()
 
         df = df.copy().sort_values(by=["issue_key", "changed_date"], ascending=True)
 

tests/process_analysis/test_status_transition_graph.py

@@ -13,6 +13,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import pytest
 from datetime import datetime
 
 import pandas as pd
@@ -22,10 +23,9 @@
 
 
 def test_empty_status_transition_graph():
-    result = StatusTransitionGraph.from_data_frame(pd.DataFrame([]))
-    assert result.total_transition_count == 0
-    assert result.graph.number_of_nodes() == 0
-    assert result.graph.number_of_edges() == 0
+    with pytest.raises(ValueError) as exception_info:
+        StatusTransitionGraph.from_data_frame(pd.DataFrame([]))
+    assert 'Provided DataFrame is empty' in str(exception_info.value)
 
 
 def test_create_status_transition_graph_from_data_frame():
@@ -51,7 +51,7 @@ def test_create_status_transition_graph_from_data_frame():
 
 
 def test_convert_of_empty_status_transition_graph_to_graphiz_dot():
-    result = StatusTransitionGraph.from_data_frame(pd.DataFrame([]))
+    result = StatusTransitionGraph()
     dot = StatusTransitionGraphVisualizer().visualize(result)
 
     assert dot.source.replace("\t", "") == """strict digraph "Status Transitions" {