Ring Layouts: Categorical, Continuous, Time#

graphistry.layout.ring.categorical.find_first_numeric_column(df)#
Parameters:

df (Any)

Return type:

str

graphistry.layout.ring.categorical.gen_axis(order, val_to_r, unhandled, combine_unhandled, append_unhandled, axis, label, reverse)#
Parameters:
  • order (List[str])

  • val_to_r (Dict[Any, float])

  • unhandled (Set[Any])

  • combine_unhandled (bool)

  • append_unhandled (bool)

  • axis (Dict[Any, str] | None)

  • label (Callable[[Any, int, float], str] | None)

  • reverse (bool)

Return type:

List[Dict]

graphistry.layout.ring.categorical.ring_categorical(g, ring_col, order=None, drop_empty=True, combine_unhandled=False, append_unhandled=True, min_r=100, max_r=1000, axis=None, format_axis=None, format_labels=None, reverse=False, play_ms=0, engine=EngineAbstract.AUTO)#

Radial graph layout where nodes are positioned based on a categorical column ring_col

Uses GPU when cudf nodes are used, otherwise pandas

min_r, max_r are the first/last axis positions

G:

Plottable

Ring_col:

Optional[str] Column name of nodes numerica-typed column; defaults to first numeric node column

Order:

Optional[List[Any]] Order of axis specified in category values

Drop_empty:

bool (default True) Whether to drop axis when no values populating them

Combine_unhandled:

bool (default False) Whether to collapse all unexpected values into one ring or one-per-unique-value

Append_unhandled:

bool (default True) Whether to append or prepend the unexpected items axis

Min_r:

float Minimum radius, default 100

Max_r:

float Maximum radius, default 1000

Ring_step:

Optional[float] Distance between rings in terms of pixels

Axis:

Optional[Dict[Any, str]], Set to provide labels for each ring by mapping from the categorical input domain values. Requires all values to be mapped.

Format_axis:

Optional[Callable[[List[Dict]], List[Dict]]] Optional transform function to format axis

Format_label:

Optional[Callable[[Any, int, float], str]] Optional transform function to format axis label text based on axis value, ring number, and ring position

Reverse:

bool Reverse the direction of the rings

Play_ms:

int initial layout time in milliseconds, default 2000

Engine:

Union[EngineAbstract, str], default EngineAbstract.AUTO, pick CPU vs GPU engine via ‘auto’, ‘pandas’, ‘cudf’

Returns:

Plotter

Return type:

Plotter

Parameters:
  • g (Plottable)

  • ring_col (str)

  • order (List[Any] | None)

  • drop_empty (bool)

  • combine_unhandled (bool)

  • append_unhandled (bool)

  • min_r (float)

  • max_r (float)

  • axis (Dict[Any, str] | None)

  • format_axis (Callable[[List[Dict]], List[Dict]] | None)

  • format_labels (Callable[[Any, int, float], str] | None)

  • reverse (bool)

  • play_ms (int)

  • engine (EngineAbstract | str)

Example: Minimal categorical ring layout

assert 'a_cat_node_column' in g._nodes
g.ring_categorical_layout('a_cat_node_column').plot()

Example: Categorical ring layout with a few rings, and rest as Other

g2 = g.ring_categorical_layout('a_cat_node_column', order=['a', 'b', 'c'], combine_unhandled=True)
g2.plot()

Example: Categorical ring layout with relabeled axis rings

g2 = g.ring_categorical_layout(
    'a_cat_node_column',
    axis={
        'a': 'ring a',
        'b': 'ring b',
        'c': 'ring c'
    }
)
g2.plot()

Example: Categorical ring layout without labels

EMPTY_AXIS_LIST = []
g2 = g.ring_categorical_layout('a_cat_node_column', format_labels=lambda axis: EMPTY_AXIS_LIST)

Example: Categorical ring layout with specific first and last ring positions

assert 'float' in g._nodes.my_numeric_col.dtype.name
g2 = g.ring_categorical_layout(
    'a_cat_node_column',
    min_r=400,
    max_r=1000,
)
g2.plot()

Example: Categorical ring layout in reverse order

g2 = g.ring_categorical_layout('a_cat_node_column', order=['a', 'b', 'c'], reverse=True)
g2.plot()
graphistry.layout.ring.continuous.find_first_numeric_column(df)#
Parameters:

df (Any)

Return type:

str

graphistry.layout.ring.continuous.gen_axis(axis_input, num_rings, v_start, v_step, r_start, step_r, label=None, reverse=False)#
Parameters:
  • axis_input (Dict[float, str] | List[str] | None)

  • num_rings (int)

  • v_start (float)

  • v_step (float)

  • r_start (float)

  • step_r (float)

  • label (Callable[[float, int, float], str] | None)

  • reverse (bool)

Return type:

List[Dict]

graphistry.layout.ring.continuous.ring_continuous(g, ring_col=None, v_start=None, v_end=None, v_step=None, min_r=100, max_r=1000, normalize_ring_col=True, num_rings=None, ring_step=None, axis=None, format_axis=None, format_labels=None, reverse=False, play_ms=0, engine=EngineAbstract.AUTO)#

Radial graph layout where nodes are positioned based on a numeric-typed column ring_col

Uses GPU when cudf nodes are used, otherwise pandas

min_r, max_r are the first/last axis positions

optional v_start, v_end are used to line up the input value domain to the axis:
  • v_start: corresponds to the first axis at min_r, defaulting to g._nodes[ring_col].min()

  • v_end: corresponds to the last axis at max_r, defaulting to g._nodes[ring_col].max()

G:

Plottable

Ring_col:

Optional[str] Column name of nodes numerica-typed column; defaults to first numeric node column

V_start:

Optional[float] Value at innermost axis (at min_r), defaults to g._nodes[ring_col].min()

V_end:

Optional[float] Value at outermost axis (at max_r), defaults to g._nodes[ring_col].max()

V_step:

Optional[float] Distance between rings in terms of ring column value domain

Min_r:

float Minimum radius, default 100

Max_r:

float Maximum radius, default 1000

Normalize_ring_col:

bool, default True, Whether to recale to min/max r, or pass through existing values

Num_rings:

Optional[int] Number of rings

Ring_step:

Optional[float] Distance between rings in terms of pixels

Axis:

Optional[Union[Dict[float,str],List[str]]], Set to provide labels for each ring, and in dict mode, also specify radius for each

Format_axis:

Optional[Callable[[List[Dict]], List[Dict]]] Optional transform function to format axis

Format_label:

Optional[Callable[[float, int, float], str]] Optional transform function to format axis label text based on axis value, ring number, and ring width

Reverse:

bool Reverse the direction of the rings

Play_ms:

int initial layout time in milliseconds, default 2000

Engine:

Union[EngineAbstract, str], default EngineAbstract.AUTO, pick CPU vs GPU engine via ‘auto’, ‘pandas’, ‘cudf’

Returns:

Plotter

Return type:

Plotter

Parameters:
  • g (Plottable)

  • ring_col (str | None)

  • v_start (float | None)

  • v_end (float | None)

  • v_step (float | None)

  • min_r (float | None)

  • max_r (float | None)

  • normalize_ring_col (bool)

  • num_rings (int | None)

  • ring_step (float | None)

  • axis (Dict[float, str] | List[str] | None)

  • format_axis (Callable[[List[Dict]], List[Dict]] | None)

  • format_labels (Callable[[float, int, float], str] | None)

  • reverse (bool)

  • play_ms (int)

  • engine (EngineAbstract | str)

Example: Minimal continuous ring layout

g.ring_continuous_layout().plot()

Example: Continuous ring layout

assert 'float' in g._nodes.my_numeric_col.dtype.name
g2 = g.ring_continuous_layout('my_numeric_col')
g2.plot()        

Example: Continuous ring layout with 7 rings

assert 'float' in g._nodes.my_numeric_col.dtype.name
g2 = g.ring_continuous_layout('my_numeric_col', num_rings=7)
g2.plot()

Example: Continuous ring layout using small steps

assert 'float' in g._nodes.my_numeric_col.dtype.name
g2 = g.ring_continuous_layout('my_numeric_col', ring_step=20.0)
g2.plot()

Example: Continuous ring layout without labels

assert 'float' in g._nodes.my_numeric_col.dtype.name
EMPTY_AXIS_LIST = []
g2 = g.ring_continuous_layout('my_numeric_col', format_labels=lambda axis: EMPTY_AXIS_LIST)

Example: Continuous ring layout with specific first and last ring positions

assert 'float' in g._nodes.my_numeric_col.dtype.name
g2 = g.ring_continuous_layout(
    'my_numeric_col',
    min_r=200,
    max_r=2000,
    v_start=32,  # corresponding column value at first axis radius at pixel radius 200
    v_end=83,  # corresponding column value at last axius radius at pixel radius 2000
)
g2.plot()

Example: Continuous ring layout in reverse order

assert 'float' in g._nodes.my_numeric_col.dtype.name
g2 = g.ring_continuous_layout('my_numeric_col', reverse=True)
g2.plot()
graphistry.layout.ring.time.TimeUnit#

Time unit for axis labels

  • ‘s’: seconds

  • ‘m’: minutes

  • ‘h’: hours

  • ‘D’: days

  • ‘W’: weeks

  • ‘M’: months

  • ‘Y’: years

  • ‘C’: centuries

alias of Literal[‘s’, ‘m’, ‘h’, ‘D’, ‘W’, ‘M’, ‘Y’, ‘C’]

graphistry.layout.ring.time.find_round_bin_width(duration, time_unit=None)#
Parameters:
  • duration (timedelta64)

  • time_unit (Literal['s', 'm', 'h', 'D', 'W', 'M', 'Y', 'C'] | None)

Return type:

Tuple[Literal[‘s’, ‘m’, ‘h’, ‘D’, ‘W’, ‘M’, ‘Y’, ‘C’], ~pandas._libs.tslibs.offsets.DateOffset, ~numpy.timedelta64]

graphistry.layout.ring.time.gen_axis(num_rings, time_start, step_dur, rounded_set_offset, round_unit, r_start, r_end, scalar, label=None, reverse=False)#
Parameters:
  • num_rings (int)

  • time_start (datetime64)

  • step_dur (timedelta64)

  • rounded_set_offset (DateOffset)

  • round_unit (Literal['s', 'm', 'h', 'D', 'W', 'M', 'Y', 'C'])

  • r_start (float)

  • r_end (float)

  • scalar (float)

  • label (Callable[[datetime64, int, timedelta64], str] | None)

  • reverse (bool)

Return type:

List[Dict]

graphistry.layout.ring.time.pretty_print_time(time, round_unit)#
Parameters:
  • time (datetime64)

  • round_unit (Literal['s', 'm', 'h', 'D', 'W', 'M', 'Y', 'C'])

Return type:

str

graphistry.layout.ring.time.round_to_nearest(time, unit)#
Parameters:
  • time (datetime64)

  • unit (timedelta64)

Return type:

datetime64

graphistry.layout.ring.time.time_ring(g, time_col=None, num_rings=None, time_start=None, time_end=None, time_unit=None, min_r=100, max_r=1000, reverse=False, format_axis=None, format_label=None, play_ms=2000, engine=EngineAbstract.AUTO)#

Radial graph layout where nodes are positioned based on a datetime64-typed column time_col

Uses GPU when cudf nodes are used, otherwise pandas with custom start and end times

G:

Plottable

Time_col:

Optional[str] Column name of nodes datetime64-typed column; defaults to first node datetime64 column

Num_rings:

Optional[int] Number of rings

Time_start:

Optional[numpy.datetime64] First ring and axis label

Time_end:

Optional[numpy.datetime64] Last ring and axis label

Time_unit:

Optional[TimeUnit] Time unit for axis labels

Min_r:

float Minimum radius, default 100

Max_r:

float Maximum radius, default 1000

Reverse:

bool Reverse the direction of the rings in terms of time

Format_axis:

Optional[Callable[[List[Dict]], List[Dict]]] Optional transform function to format axis

Format_label:

Optional[Callable[[numpy.datetime64, int, numpy.timedelta64], str]] Optional transform function to format axis label text based on axis time, ring number, and ring duration width

Play_ms:

int initial layout time in milliseconds, default 2000

Engine:

Union[EngineAbstract, str], default EngineAbstract.AUTO, pick CPU vs GPU engine via ‘auto’, ‘pandas’, ‘cudf’

Returns:

Plotter

Return type:

Plotter

Parameters:
  • g (Plottable)

  • time_col (str | None)

  • num_rings (int | None)

  • time_start (datetime64 | None)

  • time_end (datetime64 | None)

  • time_unit (Literal['s', 'm', 'h', 'D', 'W', 'M', 'Y', 'C'] | None)

  • min_r (float)

  • max_r (float)

  • reverse (bool)

  • format_axis (Callable[[List[Dict]], List[Dict]] | None)

  • format_label (Callable[[datetime64, int, timedelta64], str] | None)

  • play_ms (int)

  • engine (EngineAbstract | str)

Example: Minimal time ring layout

g.time_ring_layout().plot()

Example: Time ring layout

assert 'datetime64' in g._nodes.my_time_col.dtype.name
g2 = g.time_ring_layout('my_time_col')
g2.plot()        

Example: Time ring layout with 7 rings

assert 'datetime64' in g._nodes.my_time_col.dtype.name
g2 = g.time_ring_layout('my_time_col', num_rings=7)
g2.plot()

Example: Time ring layout using days

assert 'datetime64' in g._nodes.my_time_col.dtype.name
g2 = g.time_ring_layout('my_time_col', time_unit='D')
g2.plot()

Example: Time ring layout without labels

assert 'datetime64' in g._nodes.my_time_col.dtype.name
EMPTY_AXIS_LIST = []
g2 = g.time_ring_layout('my_time_col', format_labels=lambda axis: EMPTY_AXIS_LIST)

Example: Time ring layout with specific first and last ring positions

assert 'datetime64' in g._nodes.my_time_col.dtype.name
g2 = g.time_ring_layout('my_time_col', min_r=200, max_r=2000)
g2.plot()

Example: Time ring layout in reverse order

assert 'datetime64' in g._nodes.my_time_col.dtype.name  
g2 = g.time_ring_layout('my_time_col', reverse=True)
g2.plot()
graphistry.layout.ring.time.time_stats(s, num_rings=20, time_start=None, time_end=None, time_unit=None)#
Parameters:
  • s (Series)

  • num_rings (int | None)

  • time_start (datetime64 | None)

  • time_end (datetime64 | None)

  • time_unit (Literal['s', 'm', 'h', 'D', 'W', 'M', 'Y', 'C'] | None)

Return type:

Tuple[Literal[‘s’, ‘m’, ‘h’, ‘D’, ‘W’, ‘M’, ‘Y’, ‘C’], ~numpy.timedelta64, ~pandas._libs.tslibs.offsets.DateOffset, ~numpy.datetime64, ~numpy.datetime64, int]

graphistry.layout.ring.time.unit_to_timedelta(unit)#
Parameters:

unit (Literal['s', 'm', 'h', 'D', 'W', 'M', 'Y', 'C'])

Return type:

timedelta64