MovingBubbles
- D3Blocks.movingbubbles(df, datetime: str = 'datetime', sample_id: str = 'sample_id', state: str = 'state', center: str = None, size=5, color=None, opacity: float = 0.6, stroke: str = '#000000', cmap: str = 'Set1', color_method: str = 'state', dt_format: str = '%d-%m-%Y %H:%M:%S', damper: float = 1, fontsize: int = 14, timedelta: str = 'minutes', standardize: str = 'samplewise', speed: dict = {'fast': 25, 'medium': 250, 'slow': 750, 'superfast': 5}, figsize=[1024, 768], note: str = None, time_notes: str = None, show_controls: bool = True, dark_mode: bool = True, background_color: str = '#12141c', node_text_inside: bool = True, title: str = 'Movingbubbles - D3Blocks', filepath: str = 'movingbubbles.html', showfig: bool = True, overwrite: bool = True, notebook: bool = False, save_button: bool = True, return_html: bool = False, reset_properties: bool = True)
Movingbubbles block.
The MovingBubbles provides insights into when one action follows the other across time. It can help to understand the movements of entities, and whether clusters occur at specific time points and state(s). It may not be the most visually efficient method, but it is one of the more visually satisfying ones with force-directed and colliding nodes. The function d3.import_example(‘random_time’) is created to generate a randomized dataset with various states. The input dataset should contain 3 columns;
DateTime column: Describes the data-time when an event occurs.
State column: Describes what the particular state was at that point of time of the specific sample_id.
Sample_id column: A sample can have multiple states at various time points but can not have two states at exactly the same point in time.
- Parameters:
df (Input data, pd.DataFrame()) – Input data.
datetime (str, (default: 'datetime')) – Name of the column with the datetime.
sample_id (str, (default: 'sample_id')) – Name of the column with the sample ids.
state (str, (default: 'state')) – Name of the column with the states.
center (String, (default: None)) – Center this category.
size (int, list/array/Series, or dictionary. (default: 5)) –
- Size the nodes.
5: set all nodes to this size.
[4, 10, 5, …]: array-like of the same length as
df, aligned positionally with its rows (same convention asd3.scatter’ssize).{‘0’: 4, ‘1’: 10, ‘2’: 5, ..}: dict keyed by sample_id value.
color (int, list/array/Series, or dictionary. (default: '#808080') or {sample_id i: hex-color}) –
- Color the nodes.
’#000FFF’: set all nodes to this color.
[‘#808080’, ‘#FFF000’, …]: array-like of the same length as
df, aligned positionally with its rows.{‘0’: ‘#808080’, ‘1’: ‘#FFF000’, ‘3’: ‘#000000’, ..}: dict keyed by sample_id value.
None: Colors are based on sample_id using the cmap.
opacity (float, list/array/Series, or dictionary, (default: 0.6)) –
- Opacity of the bubbles [0-1].
0.6: set all nodes to this opacity.
[0.4, 0.9, …]: array-like of the same length as
df, aligned positionally with its rows.{‘0’: 0.4, ‘1’: 0.9, ..}: dict keyed by sample_id value.
stroke (str, list/array/Series, or dictionary, (default: '#000000')) –
- Stroke color of the bubbles.
’#000000’: set all nodes to this stroke color.
[‘#000000’, ‘#ffffff’, …]: array-like of the same length as
df, aligned positionally with its rows.{‘0’: ‘#000000’, ‘1’: ‘#ffffff’, ..}: dict keyed by sample_id value.
color_method (str) –
- Coloring of the nodes.
’state’: Use the colors defined per state as (d3.node_properties).
’node’: Use the colors defined in the dataframe (d3.edge_properties).
dt_format (str) –
- Date time format.
’%d-%m-%Y %H:%M:%S’.
damper (float, (default: 1)) –
- Movement of samples. A smaller number is slower/smoother movement.
0.1: min
10: max
fontsize (int, (default: 14)) – Fontsize of the states.
timedelta (String, (default: 'minutes')) –
- The time delta between states. Change accordingly.
’seconds’
’minutes’
’days’
standardize (str. (default: None)) –
- Method to standardize the data.
None: standardize over the entire timeframe. Sample_ids are dependent to each other.
’samplewise’: Standardize per sample_id by substracting the minimum time per sample_id.
’relative’: Standardize across the entire dataframe after sorting on time. Each action is relative to the previous one in time without considering sample_id.
’minimum’: Movements are relative to the minimum time in the dataset.
speed (dict, (default: {"slow": 1000, "medium": 200, "fast": 50, "superfast": 20})) – Reference delays (ms) for the playback speed continuum. Lower values move time faster. Keys map to slider regions;
slowis the slowest non-stopped delay andsuperfastis the fastest (right end of the slider).note (str, (default: None)) –
- A specific note, such as project description can be put on the html page.
None: Default text will be provided about the simulation, and states.
time_notes (dict, (default: None)) –
The time notes will be shown between specific time points.
Example:
time_notes = [{"start_minute": 1, "stop_minute": 5, "note": "Enter your note here and it is shown between 1 min and 5 min."}] time_notes.append({"start_minute": 6, "stop_minute": 10, "note": "Enter your second note here and it is shown between 6 min and 10 min."})
show_controls (bool, (default: True)) – True: Show the floating control panels (Playback, Display, Filtering, Export). False: Hide all control panels; only the chart itself is shown.
dark_mode (bool, (default: True)) – True: Dark theme. False: Light theme.
background_color (str, (default: '#12141c')) – Background color used for the dark theme.
node_text_inside (bool, (default: True)) – True: Per-bubble labels (Layout -> Label) are centered inside the node, with the text color automatically switched between black/white for contrast against the node’s fill color. False: Labels are placed above the node, matching the theme’s text color (this was the only behavior previously).
cmap (String, (default: 'Set1')) –
- All colors can be reversed with ‘_r’, e.g. ‘binary’ to ‘binary_r’
’tab20c’, ‘Set1’, ‘Set2’
’rainbow’, ‘bwr’, ‘binary’, ‘seismic’
’Blues’, ‘Reds’, ‘Pastel1’, ‘Paired’
’twilight’, ‘hsv’, ‘inferno’
title (String, (default: None)) –
- Title of the figure.
’Movingbubbles’
filepath (String, (Default: user temp directory)) –
- File path to save the output.
Temporarily path: ‘d3blocks.html’
Relative path: ‘./d3blocks.html’
Absolute path: ‘c://temp//d3blocks.html’
None: Return HTML
figsize (tuple) –
- Size of the figure in the browser, [width, height].
[780, 800]
showfig (bool, (default: True)) –
True: Open browser-window.
False: Do not open browser-window.
overwrite (bool, (default: True)) –
True: Overwrite the html in the destination directory.
False: Do not overwrite destination file but show warning instead.
notebook (bool) –
True: Use IPython to show chart in notebook.
False: Do not use IPython.
save_button (bool, (default: True)) –
True: Save button is shown in the HTML to save the image in svg.
False: No save button is shown in the HTML.
return_html (bool, (default: False)) –
True: Return html
False: Nothing is returned
reset_properties (bool, (default: True)) –
True: Reset the node_properties at each run.
False: Use the d3.node_properties()
- Returns:
d3.node_properties (DataFrame of dictionary) – Contains properties of the unique input label/nodes/samples.
d3.edge_properties (DataFrame of dictionary) – Contains properties of the unique input edges/links.
d3.config (dictionary) – Contains configuration properties.
Examples
>>> # Load d3blocks >>> from d3blocks import D3Blocks >>> # >>> # Initialize >>> d3 = D3Blocks() >>> # >>> # Load example data >>> df = d3.import_example('random_time', n=10000, c=300, date_start="1-1-2000 00:10:05", date_stop="1-1-2000 23:59:59") >>> # >>> # Plot >>> d3.movingbubbles(df, speed={"slow": 1000, "medium": 200, "fast": 50, "superfast": 20}, filepath='movingbubbles.html') >>> #
Examples
>>> # Load d3blocks >>> from d3blocks import D3Blocks >>> # >>> # Initialize >>> d3 = D3Blocks(chart='movingbubbles', frame=False) >>> # >>> # Import example >>> df = d3.import_example('random_time', n=1000, c=100, date_start="1-1-2000 00:10:05", date_stop="1-1-2000 23:59:59") >>> # >>> # Coloring the states. >>> d3.set_node_properties(df['state']) >>> print(d3.node_properties) >>> # Color the sleeping state black >>> d3.node_properties.get('Sleeping')['color']='#000000' >>> # >>> d3.set_edge_properties(df) >>> print(d3.edge_properties) >>> # >>> # Show >>> d3.show(title='Movingbubbles with adjusted configurations')
Examples
>>> # Load d3blocks >>> import random >>> from d3blocks import D3Blocks >>> # >>> # Initialize >>> d3 = D3Blocks(chart='movingbubbles') >>> # >>> # Import example >>> df = d3.import_example('random_time', n=10000, c=300, date_start="1-1-2000 00:10:05", date_stop="1-1-2000 23:59:59") >>> # >>> # Specify the colors and node sizes for the specific sample_id or for demonstration, generated randomly >>> # size = {1: 15, 3: 30, 5: 25} >>> size = {i: random.randint(2, 15) for i in range(1, 100)} >>> color = {1: '#FF0000', 3: '#000FFF'} >>> # >>> # Show >>> d3.movingbubbles(df, color=color, size=size)
References
Input Data (MovingBubbles)
The input data is a dataframe that should contain the columns datatime, sample_id and state. If the column names are different, then the column name can be specified.
# datetime sample_id state
# 0 2000-01-01 00:10:32 30 Sick
# 1 2000-01-01 00:10:36 23 Work
# 2 2000-01-01 00:11:16 179 Sleeping
# 3 2000-01-01 00:11:28 122 Sport
# 4 2000-01-01 00:13:02 226 Sleeping
# ... ... ...
# 9994 2000-01-01 23:59:56 300 Sleeping
# 9995 2000-01-01 23:59:57 217 Home
# 9996 2000-01-01 23:59:57 89 Sleeping
# 9997 2000-01-01 23:59:58 42 Sleeping
# 9998 2000-01-01 23:59:58 237 Work
# [9999 rows x 3 columns]