d3blocks 2.1.0__tar.gz → 2.2.0__tar.gz

{d3blocks-2.1.0 → d3blocks-2.2.0}/MANIFEST.in

@@ -14,5 +14,6 @@ include d3blocks/circlepacking/d3js/*
 include d3blocks/maps/d3js/*
 include d3blocks/elasticgraph/d3js/*
 include d3blocks/radialgraph/d3js/*
+include d3blocks/flowgraph/d3js/*
 include d3blocks/*
 recursive-include d3blocks/skills *

{d3blocks-2.1.0/d3blocks.egg-info → d3blocks-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: d3blocks
-Version: 2.1.0
+Version: 2.2.0
 Summary: Python package d3blocks.
 Author-email: Erdogan Taskesen <erdogant@gmail.com>
 License-Expression: GPL-3.0-or-later
@@ -42,7 +42,7 @@ Dynamic: license-file
 [![Medium](https://img.shields.io/badge/Medium-Blog-black)](https://d3blocks.github.io/d3blocks/pages/html/Documentation.html#medium-blog)
 ![GitHub Repo stars](https://img.shields.io/github/stars/d3blocks/d3blocks)
 ![GitHub repo size](https://img.shields.io/github/repo-size/d3blocks/d3blocks)
-[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://d3blocks.github.io/d3blocks/pages/html/Documentation.html#colab-notebook)
+[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://github.com/d3blocks/d3blocks/blob/main/notebooks/d3blocks.ipynb)
 [![Donate](https://img.shields.io/badge/Support%20this%20project-grey.svg?logo=github%20sponsors)](https://d3blocks.github.io/d3blocks/pages/html/Documentation.html#)
 
 ### 
@@ -117,6 +117,7 @@ The [documentation pages](https://d3blocks.github.io/d3blocks/) contains detaile
 |  14 | [Tree](https://d3blocks.github.io/d3blocks/pages/html/Tree.html)                   | ``` d3.tree()  ```           | [D3Blocks](https://erdogant.medium.com) |
 |  15 | [Maps](https://d3blocks.github.io/d3blocks/pages/html/Maps.html)                   | ``` d3.maps()  ```           | [D3Blocks](https://erdogant.medium.com) |
 |  16 | [Circlepacking](https://d3blocks.github.io/d3blocks/pages/html/Circlepacking.html) | ``` d3.circlepacking()  ```  | [D3Blocks](https://erdogant.medium.com) |
+|  17 | [Flowgraph](https://d3blocks.github.io/d3blocks/pages/html/Flowgraph.html)         | ``` d3.flowgraph()  ```      | [D3Blocks](https://erdogant.medium.com) |
 
 -------------------------------------------------------------------------
 
@@ -148,7 +149,7 @@ When HTMLs are generated, it automatically include ethical ads as a small way to
 This entire project with maintenance is done thoughtfully and only in my free time. Ads can be disabled via an input parameter, and you can also support the project with a coffee donation instead.
 
 ### Star history
-[![Star History Chart](https://star-history.dera.page/svg?repos=d3blocks/d3blocks&type=Date)](https://star-history.dera.page/#d3blocks/d3blocks&Date)
+[![Star History Chart](https://star-history.dera.page/svg?repos=d3blocks/d3blocks)](https://star-history.dera.page/d3blocks/d3blocks)
 
 ### References
 * [bl.ocks](https://bl.ocks.org/)

{d3blocks-2.1.0 → d3blocks-2.2.0}/README.md

@@ -11,7 +11,7 @@
 [![Medium](https://img.shields.io/badge/Medium-Blog-black)](https://d3blocks.github.io/d3blocks/pages/html/Documentation.html#medium-blog)
 ![GitHub Repo stars](https://img.shields.io/github/stars/d3blocks/d3blocks)
 ![GitHub repo size](https://img.shields.io/github/repo-size/d3blocks/d3blocks)
-[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://d3blocks.github.io/d3blocks/pages/html/Documentation.html#colab-notebook)
+[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://github.com/d3blocks/d3blocks/blob/main/notebooks/d3blocks.ipynb)
 [![Donate](https://img.shields.io/badge/Support%20this%20project-grey.svg?logo=github%20sponsors)](https://d3blocks.github.io/d3blocks/pages/html/Documentation.html#)
 
 ### 
@@ -86,6 +86,7 @@ The [documentation pages](https://d3blocks.github.io/d3blocks/) contains detaile
 |  14 | [Tree](https://d3blocks.github.io/d3blocks/pages/html/Tree.html)                   | ``` d3.tree()  ```           | [D3Blocks](https://erdogant.medium.com) |
 |  15 | [Maps](https://d3blocks.github.io/d3blocks/pages/html/Maps.html)                   | ``` d3.maps()  ```           | [D3Blocks](https://erdogant.medium.com) |
 |  16 | [Circlepacking](https://d3blocks.github.io/d3blocks/pages/html/Circlepacking.html) | ``` d3.circlepacking()  ```  | [D3Blocks](https://erdogant.medium.com) |
+|  17 | [Flowgraph](https://d3blocks.github.io/d3blocks/pages/html/Flowgraph.html)         | ``` d3.flowgraph()  ```      | [D3Blocks](https://erdogant.medium.com) |
 
 -------------------------------------------------------------------------
 
@@ -117,7 +118,7 @@ When HTMLs are generated, it automatically include ethical ads as a small way to
 This entire project with maintenance is done thoughtfully and only in my free time. Ads can be disabled via an input parameter, and you can also support the project with a coffee donation instead.
 
 ### Star history
-[![Star History Chart](https://star-history.dera.page/svg?repos=d3blocks/d3blocks&type=Date)](https://star-history.dera.page/#d3blocks/d3blocks&Date)
+[![Star History Chart](https://star-history.dera.page/svg?repos=d3blocks/d3blocks)](https://star-history.dera.page/d3blocks/d3blocks)
 
 ### References
 * [bl.ocks](https://bl.ocks.org/)

{d3blocks-2.1.0 → d3blocks-2.2.0}/d3blocks/__init__.py

@@ -10,7 +10,7 @@ from d3blocks.utils import (
 
 __author__ = 'Erdogan Taskesen'
 __email__ = 'erdogant@gmail.com'
-__version__ = '2.1.0'
+__version__ = '2.2.0'
 
 # Setup root logger
 import logging

{d3blocks-2.1.0 → d3blocks-2.2.0}/d3blocks/d3blocks.py

@@ -30,6 +30,7 @@ try:
     import d3blocks.circlepacking.Circlepacking as Circlepacking
     import d3blocks.tree.Tree as Tree
     import d3blocks.radialgraph.Radialgraph as Radialgraph
+    import d3blocks.flowgraph.Flowgraph as Flowgraph
     import d3blocks.maps.Maps as Maps
     import d3blocks.utils as utils
 except:
@@ -49,6 +50,7 @@ except:
     import circlepacking.Circlepacking as Circlepacking
     import tree.Tree as Tree
     import radialgraph.Radialgraph as Radialgraph
+    import flowgraph.Flowgraph as Flowgraph
     import maps.Maps as Maps
     import utils
     # #####################################################
@@ -536,11 +538,13 @@ class D3Blocks():
         size: list/array of with same size as (x,y).
             Size of the samples.
         color : list/array of hex colors with same size as (x,y)
+
                 * '#ffffff' : All dots are get the same hex color.
                 * None: The same color as for c is applied.
                 * ['#000000', '#ffffff',...]: list/array of hex colors with same size as (x,y)
         stroke: list/array of hex colors with same size as (x,y)
             Edgecolor of dotsize in hex colors.
+
                 * '#000000' : All dots are get the same hex color.
                 * ['#000000', '#ffffff',...]: list/array of hex colors with same size as (x,y)
         c_gradient : String, (default: 'opaque')
@@ -2674,6 +2678,7 @@ class D3Blocks():
         ----------
         df : pd.DataFrame()
             Input data containing the following columns:
+
                 * 'source', 'target', 'weight'
         hierarchy : list
             Expand or substract the hierarchical structure. No information is lossed. The eight branches are shown by default.
@@ -3075,6 +3080,220 @@ class D3Blocks():
         if return_html:
             return html
 
+    def flowgraph(self,
+                  df,
+                  nodes=None,
+                  groups: dict = None,
+                  direction: str = None,
+                  layout: str = 'dagre',
+                  shape: str = 'process',
+                  color: str = 'group',
+                  cmap: str = 'Set2',
+                  edge_color: str = '#8c8c8c',
+                  nodesep: int = 40,
+                  ranksep: int = 70,
+                  edgesep: int = 20,
+                  ranker: str = 'network-simplex',
+                  curve: str = 'smooth',
+                  animate: bool = False,
+                  draggable: bool = True,
+                  show_edge_labels: bool = True,
+                  show_groups: bool = True,
+                  font: dict = {'size': 13},
+                  title: str = 'Flowgraph - D3blocks',
+                  filepath: str = 'flowgraph.html',
+                  figsize=[None, None],
+                  showfig: bool = True,
+                  overwrite: bool = True,
+                  notebook: bool = False,
+                  save_button: bool = True,
+                  show_side_panel: bool = True,
+                  show_top_panel: bool = True,
+                  dark_mode: bool = True,
+                  color_background=None,
+                  return_html: bool = False,
+                  reset_properties: bool = True):
+        """Flowgraph block: process flows and architecture diagrams.
+
+        Nodes are arranged in ranks along the flow direction with a layered
+        layout, drawn as flowchart shapes and optionally nested in groups such as
+        swimlanes, services or network boundaries. The input is either an edge
+        list or a Mermaid flowchart.
+
+        Parameters
+        ----------
+        df : pd.DataFrame, str or path-like
+            * DataFrame with the edges. Required columns: 'source', 'target'.
+              Optional columns: 'label' (edge text), 'weight' (line width),
+              'variant', 'style' ('solid', 'dashed', 'dotted'), 'color' and 'animation'.
+            * str: a Mermaid flowchart, e.g. 'flowchart LR; A[Start] --> B{Valid?}',
+              or Markdown text containing a ```mermaid block.
+            * Path to a Markdown file (.md, .markdown) with a ```mermaid block, so the
+              same diagram renders on GitHub, or to a .mmd / .mermaid file.
+              From Markdown, the first flowchart block is used.
+            Node shapes, edge labels, dotted/thick links and (nested) subgraphs are
+            converted; `nodes`, `groups` and `direction` override what it defines.
+        nodes : pd.DataFrame or dict, (default: None)
+            Per-node attributes keyed by node name (a 'name' column or the index):
+                * 'label': display text; use '\\n' for line breaks.
+                * 'shape': 'process', 'decision', 'terminal', 'io', 'subprocess',
+                  'database', 'queue', 'document', 'external' or 'circle'.
+                * 'group': group (swimlane / boundary) the node belongs to.
+                * 'color': node colour; overrides `color`.
+                * 'tooltip': extra text or HTML shown on hover below the label.
+        groups : dict, (default: None)
+            Group settings: {group: {'label': str, 'parent': str, 'color': hex}}.
+            Use 'parent' to nest groups (e.g. a subnet inside a VPC). The short form
+            {group: parent} is also accepted.
+        direction : str, (default: None)
+            Flow direction: 'LR', 'TB' (or 'TD'), 'RL' or 'BT'. None: the direction
+            of the Mermaid header, otherwise 'LR'.
+        layout : str, (default: 'dagre')
+            * 'dagre': layered layout with smooth edges; small output (~0.5 MB).
+            * 'elk': ELK layered layout with orthogonal edge routing and native
+              nested groups; tidier for architecture diagrams, adds ~1.5 MB to the HTML.
+        shape : str, (default: 'process')
+            Default shape for nodes without one.
+        color : str, (default: 'group')
+            * 'group': colour nodes by group.
+            * 'shape': colour nodes by shape.
+            * '#RRGGBB': one colour for all nodes.
+        cmap : str, (default: 'Set2')
+            Colormap for group / shape colouring.
+        edge_color : str, (default: '#8c8c8c')
+            Default edge colour.
+        nodesep : int, (default: 40)
+            Pixels between nodes in the same rank.
+        ranksep : int, (default: 70)
+            Pixels between ranks.
+        edgesep : int, (default: 20)
+            Pixels between parallel edges.
+        ranker : str, (default: 'network-simplex')
+            dagre ranking algorithm: 'network-simplex', 'tight-tree' or 'longest-path'.
+        curve : str, (default: 'smooth')
+            Edge shape: 'smooth' (curved, or rounded corners with ELK) or 'straight'.
+        animate : bool, (default: False)
+            Animate pulses along the edges to show the direction of flow.
+        draggable : bool, (default: True)
+            Nodes can be dragged; connected edges and groups follow.
+        show_edge_labels : bool, (default: True)
+            Draw edge labels.
+        show_groups : bool, (default: True)
+            Draw groups as containers (and keep their members together).
+        font : dict, (default: {'size': 13})
+            Font properties.
+        title : str, (default: 'Flowgraph - D3blocks')
+            Title of the figure.
+        filepath : str, (default: 'flowgraph.html')
+            File path to save the output. None: return HTML only.
+        figsize : list, (default: [None, None])
+            [width, height] in pixels. None: full window.
+        showfig : bool, (default: True)
+            Open the chart in the browser.
+        overwrite : bool, (default: True)
+            Overwrite an existing file.
+        notebook : bool, (default: False)
+            Display inline in a Jupyter notebook, isolated in an iframe sized by
+            `figsize` (default: full width x 650 px). The returned HTML is then
+            that iframe.
+        save_button : bool, (default: True)
+            Show the SVG/PNG save buttons.
+        show_side_panel : bool, (default: True)
+            Show the left side panels (Export / Save, Layout, Legend).
+        show_top_panel : bool, (default: True)
+            Show the top bar (logo, search, fit, theme).
+        dark_mode : bool, (default: True)
+            Start in the dark theme.
+        color_background : list of str, str, or None, (default: None)
+            Backgrounds for center / top / side panels as ``[dark_hex, light_hex]``.
+            Named themes: ``'streamlit'``, ``'darkblue'``. None → ``['#222222', '#ffffff']``.
+        return_html : bool, (default: False)
+            Return the HTML string.
+        reset_properties : bool, (default: True)
+            Recompute node and edge properties from the input.
+
+        Returns
+        -------
+        d3.node_properties : DataFrame of dictionary
+             Node properties; edit and call d3.show() to update.
+        d3.edge_properties : DataFrame
+             Edge properties; edit and call d3.show() to update.
+        d3.config : dictionary
+             Configuration. d3.config['groups'] holds the group settings (merged with
+             Mermaid subgraphs); edit and call d3.show(). Labels, nesting and colours
+             are resolved from it on every draw.
+
+        Examples
+        --------
+        >>> # Edge list with shapes and edge labels
+        >>> import pandas as pd
+        >>> from d3blocks import D3Blocks
+        >>> d3 = D3Blocks(frame=False)
+        >>> df = pd.DataFrame({'source': ['Start', 'Valid?', 'Valid?', 'Fix'],
+        ...                    'target': ['Valid?', 'Done', 'Fix', 'Valid?'],
+        ...                    'label': ['', 'yes', 'no', 'retry']})
+        >>> nodes = {'Start': {'shape': 'terminal'}, 'Valid?': {'shape': 'decision'},
+        ...          'Done': {'shape': 'terminal'}}
+        >>> d3.flowgraph(df, nodes=nodes, direction='TB')
+        >>> # Change a node and redraw
+        >>> d3.node_properties['Fix']['color'] = '#e15759'
+        >>> d3.show()
+        >>>
+        >>> # Mermaid diagram kept in a Markdown file (renders on GitHub too)
+        >>> d3.flowgraph('docs/process.md')
+        >>>
+        >>> # Mermaid flowchart with a subgraph, laid out with ELK
+        >>> d3.flowgraph('''
+        ... flowchart LR
+        ...   subgraph api [API]
+        ...     gw[Gateway] --> svc[Orders]
+        ...   end
+        ...   svc --> db[(Postgres)]
+        ...   svc -.->|events| q[[Worker]]
+        ... ''', layout='elk')
+
+        References
+        ----------
+        * dagre: https://github.com/dagrejs/dagre
+        * ELK: https://eclipse.dev/elk/
+        * https://d3blocks.github.io/d3blocks/pages/html/Flowgraph.html
+
+        """
+        # Mermaid input (text, Markdown or file): convert to edges, nodes, groups and direction.
+        if Flowgraph.is_mermaid_source(df):
+            df, m_nodes, m_groups, m_direction = Flowgraph.from_mermaid(df, logger=logger)
+            nodes = Flowgraph.merge_node_attributes(m_nodes, nodes)
+            groups = Flowgraph.merge_group_attributes(m_groups, groups)
+            direction = direction or m_direction
+        direction = direction or 'LR'
+        # Cleaning
+        self._clean(clean_config=reset_properties, logger=logger)
+        # Store chart
+        self.chart = set_chart_func('Flowgraph', logger)
+        # Store properties
+        self.config = self.chart.set_config(
+            config=self.config, font=font, title=title, filepath=filepath, figsize=figsize,
+            showfig=showfig, overwrite=overwrite, notebook=notebook, direction=direction,
+            layout=layout, nodesep=nodesep, ranksep=ranksep, edgesep=edgesep, ranker=ranker,
+            curve=curve, animate=animate, draggable=draggable,
+            show_edge_labels=show_edge_labels, show_groups=show_groups, groups=groups, cmap=cmap,
+            color_background=color_background, dark_mode=dark_mode, save_button=save_button,
+            show_side_panel=show_side_panel, show_top_panel=show_top_panel,
+            reset_properties=reset_properties, logger=logger,
+        )
+        # Set default node properties
+        if self.config['reset_properties'] or (not hasattr(self, 'node_properties')):
+            self.set_node_properties(df, nodes=nodes, shape=shape, color=color, cmap=cmap, logger=logger)
+        # Set edge properties
+        self.set_edge_properties(df, edge_color=edge_color, logger=logger)
+
+        # Create the plot
+        html = self.show()
+
+        # Return
+        if return_html:
+            return html
+
     def treemap(self,
                 df: pd.DataFrame,
                 margin = {"top": 40, "right": 10, "bottom": 10, "left": 10},
@@ -3490,6 +3709,7 @@ class D3Blocks():
             Marker defaults (see previous docs). Used when building node properties.
         countries : dict or None
             Explicit country styling::
+
                 {'World': {'color': '#D3D3D3', 'opacity': 0.6, 'line': 'none', 'linewidth': 1},
                  'Netherlands': {'color': '#000FFF', 'opacity': 0.8}}
             Ignored when ``country_names`` is provided.
@@ -4199,7 +4419,7 @@ def set_chart_func(chart=None, logger=None):
     if chart is not None:
         if logger is not None: logger.info('Initializing [%s]' %(chart))
         chart = str.capitalize(chart)
-        if np.isin(chart, ['RadialGraph', 'Maps', 'Chord', 'Sankey', 'Timeseries', 'Violin', 'Movingbubbles', 'Scatter', 'Heatmap', 'Matrix', 'Treemap', 'Tree', 'Circlepacking', 'Radialgraph']):
+        if np.isin(chart, ['RadialGraph', 'Maps', 'Chord', 'Sankey', 'Timeseries', 'Violin', 'Movingbubbles', 'Scatter', 'Heatmap', 'Matrix', 'Treemap', 'Tree', 'Circlepacking', 'Radialgraph', 'Flowgraph']):
             chart=eval(chart)
         else:
             if logger is not None: logger.info('%s is not yet implemented in such manner.' %(chart))

{d3blocks-2.1.0 → d3blocks-2.2.0}/d3blocks/examples.py

@@ -37,7 +37,7 @@ df = d3.import_example('energy')
 # Create network graph
 html = d3.elasticgraph(
           df,
-          show_side_panel=False,
+          show_side_panel=True,
           show_top_panel=False,
           dark_mode=True,
           color_background='streamlit',
@@ -126,7 +126,7 @@ d3.chord(df,
 from d3blocks import D3Blocks
 d3 = D3Blocks()
 df = d3.import_example('surfspots')
-d3.maps(df, filepath=r'c:/temp/test/', show_controls=True, dark_mode=False)
+d3.maps(df, filepath=r'c:/temp/test/', show_side_panel=True, dark_mode=False)
 
 # %%
 # timeseries
@@ -188,7 +188,7 @@ d3.violin(x=df['labx'].values,
           filepath=r'c:\temp\violine.html',
           figsize=[None, None],
           df=df,
-          show_controls=False,
+          show_side_panel=True,
           dark_mode=False
           )
 
@@ -266,8 +266,8 @@ df["weight"] = np.random.randint(1, 101, size=len(df))
 html = d3.d3graph(df,
            show_side_panel=True,
            show_top_panel=True,
-           show_slider=True,
-           show_density=True,
+           # show_slider=True,
+           # show_density=True,
            color_background='streamlit',
            return_html=True,
            showfig=True,
@@ -421,7 +421,7 @@ d3.d3graph(df,
            dark_mode=True,
            show_density=True,
            show_slider=True,
-           show_controls=True,
+           show_side_panel=True,
            )
 
 adjmat = d3.vec2adjmat(df['source'], df['target'], df['weight'])
@@ -625,7 +625,7 @@ d3.show(filepath=r'c:\temp\tree.html', margin = {"top": 20, "right": 80, "bottom
         link_length=120,
         font={'size':20},
         dark_mode=True,
-        show_controls=True,
+        show_side_panel=True,
         )
 
 
@@ -832,7 +832,7 @@ html = d3.treemap(df, filepath=r'c:\temp\treemap1.html')
 
 # Tree
 df = d3.import_example(data='energy')
-html = d3.tree(df)
+html = d3.treemap(df)
 html = d3.tree(df, save_button=False)
 html = d3.tree(df, save_button=True)
 html = d3.tree(df, return_html=True, filepath=None)
@@ -1051,7 +1051,7 @@ d3 = D3Blocks()
 df = d3.import_example('energy')
 
 html = d3.circlepacking(df, filepath='c://temp//circlepacking.html', font={'size': 16}, zoom='click', figsize=[900, 1900])
-# html = d3.treemap(df, filepath='c://temp//treemap.html', show_controls=True, dark_mode=True, value='count')
+# html = d3.treemap(df, filepath='c://temp//treemap.html', show_side_panel=True, dark_mode=True, value='count')
 # html = d3.tree(df, filepath='c://temp//tree.html')
 # html = d3.sankey(df)
 # html = d3.chord(df)
@@ -1089,7 +1089,7 @@ d3 = D3Blocks()
 df = d3.import_example(data='energy')
 
 # Create the network graph
-d3.d3graph(df, cmap='Set2', dark_mode=False, background_color='#FFF000', show_controls=True, showfig=True)
+d3.d3graph(df, cmap='Set2', dark_mode=False, background_color='#FFF000', show_side_panel=True, showfig=True)
 # Extract the node colors from the network graph.
 # node_colors = d3.D3graph.node_properties