0
# Figure Factory
1

2
Specialized figure creation functions for complex statistical and scientific visualizations. Figure Factory provides 19 high-level functions that generate sophisticated charts with minimal code, handling complex data transformations and styling automatically.
3

4
## Capabilities
5

6
### Statistical Visualizations
7

8
Advanced statistical chart creation functions for data analysis and scientific plotting.
9

10
```python { .api }
11
def create_annotated_heatmap(z, x=None, y=None, annotation_text=None, 
12
                            colorscale='RdBu', font_colors=None, showscale=False, 
13
                            reversescale=False, **kwargs):
14
    """
15
    Create an annotated heatmap with text labels in each cell.
16
    
17
    Parameters:
18
    - z: 2D array-like, matrix values for heatmap colors
19
    - x: array-like, x-axis labels
20
    - y: array-like, y-axis labels  
21
    - annotation_text: 2D array-like, text for each cell (defaults to z values)
22
    - colorscale: str or list, color scale name or custom scale
23
    - font_colors: list of str, font colors for annotations
24
    - showscale: bool, whether to show color scale
25
    - reversescale: bool, whether to reverse color scale
26
    
27
    Returns:
28
    Figure: Plotly figure object with annotated heatmap
29
    """
30

31
def create_dendrogram(X, orientation='bottom', labels=None, colorscale=None, 
32
                     distfun=None, linkagefun=None, hovertext=None, 
33
                     color_threshold=None):
34
    """
35
    Create a dendrogram for hierarchical clustering visualization.
36
    
37
    Parameters:
38
    - X: 2D array-like, data matrix for clustering
39
    - orientation: str, dendrogram orientation ('bottom', 'top', 'left', 'right')
40
    - labels: array-like, labels for data points
41
    - colorscale: str or list, color scale for dendrogram branches
42
    - distfun: callable, distance function for clustering
43
    - linkagefun: callable, linkage function for clustering
44
    - color_threshold: float, threshold for coloring clusters
45
    
46
    Returns:
47
    Figure: Plotly figure object with dendrogram
48
    """
49

50
def create_distplot(hist_data, group_labels, bin_size=1.0, curve_type='kde', 
51
                   colors=None, rug_text=None, histnorm='probability density', 
52
                   show_hist=True, show_curve=True, show_rug=True):
53
    """
54
    Create a distribution plot with histograms, curves, and rug plots.
55
    
56
    Parameters:
57
    - hist_data: list of array-like, data arrays for each group
58
    - group_labels: list of str, labels for each data group
59
    - bin_size: float, histogram bin size
60
    - curve_type: str, curve type ('kde', 'normal')
61
    - colors: list of str, colors for each group
62
    - rug_text: list of array-like, hover text for rug plots
63
    - histnorm: str, histogram normalization
64
    - show_hist: bool, whether to show histograms
65
    - show_curve: bool, whether to show distribution curves
66
    - show_rug: bool, whether to show rug plots
67
    
68
    Returns:
69
    Figure: Plotly figure object with distribution plot
70
    """
71

72
def create_violin(data, data_header=None, group_header=None, colors=None, 
73
                 use_colorscale=False, group_stats=None, rugplot=True, 
74
                 sort=False, height=450, width=600, title='Violin Plot'):
75
    """
76
    Create violin plots for distribution visualization.
77
    
78
    Parameters:
79
    - data: 2D array-like, data matrix where columns represent groups
80
    - data_header: str, header for data values
81
    - group_header: str, header for group labels
82
    - colors: list of str, colors for each violin
83
    - use_colorscale: bool, whether to use continuous color scale
84
    - group_stats: dict, statistical information for each group
85
    - rugplot: bool, whether to include rug plot
86
    - sort: bool, whether to sort violins by median
87
    - height: int, figure height in pixels
88
    - width: int, figure width in pixels
89
    - title: str, figure title
90
    
91
    Returns:
92
    Figure: Plotly figure object with violin plots
93
    """
94
```
95

96
### Financial Charts
97

98
Specialized functions for financial data visualization including candlestick and OHLC charts.
99

100
```python { .api }
101
def create_candlestick(open, high, low, close, dates=None, direction='increasing', 
102
                      **kwargs):
103
    """
104
    Create a candlestick chart for financial data.
105
    
106
    Parameters:
107
    - open: array-like, opening prices
108
    - high: array-like, high prices
109
    - low: array-like, low prices
110
    - close: array-like, closing prices
111
    - dates: array-like, date/time values for x-axis
112
    - direction: str, price movement direction ('increasing', 'decreasing', 'both')
113
    
114
    Returns:
115
    Figure: Plotly figure object with candlestick chart
116
    """
117

118
def create_ohlc(open, high, low, close, dates=None, direction='increasing', 
119
               **kwargs):
120
    """
121
    Create an OHLC (Open-High-Low-Close) chart for financial data.
122
    
123
    Parameters:
124
    - open: array-like, opening prices
125
    - high: array-like, high prices  
126
    - low: array-like, low prices
127
    - close: array-like, closing prices
128
    - dates: array-like, date/time values for x-axis
129
    - direction: str, price movement direction
130
    
131
    Returns:
132
    Figure: Plotly figure object with OHLC chart
133
    """
134
```
135

136
### Scientific Visualizations
137

138
Functions for specialized scientific and engineering visualizations.
139

140
```python { .api }
141
def create_quiver(x, y, u, v, scale=1, arrow_scale=1, angle=None, **kwargs):
142
    """
143
    Create a quiver plot for vector field visualization.
144
    
145
    Parameters:
146
    - x: array-like, x coordinates of vector origins
147
    - y: array-like, y coordinates of vector origins
148
    - u: array-like, x components of vectors
149
    - v: array-like, y components of vectors
150
    - scale: float, scaling factor for vector lengths
151
    - arrow_scale: float, scaling factor for arrow sizes
152
    - angle: str, angle convention ('uv' or 'radians')
153
    
154
    Returns:
155
    Figure: Plotly figure object with quiver plot
156
    """
157

158
def create_streamline(x, y, u, v, density=1, angle=None, **kwargs):
159
    """
160
    Create a streamline plot for flow visualization.
161
    
162
    Parameters:
163
    - x: 2D array-like, x coordinates grid
164
    - y: 2D array-like, y coordinates grid  
165
    - u: 2D array-like, x components of flow vectors
166
    - v: 2D array-like, y components of flow vectors
167
    - density: float, streamline density factor
168
    - angle: str, angle convention
169
    
170
    Returns:
171
    Figure: Plotly figure object with streamline plot
172
    """
173

174
def create_trisurf(x, y, z, simplices=None, colormap=None, show_colorbar=True, 
175
                  edges_color='rgb(50, 50, 50)', title='Triangular Surface Plot', 
176
                  **kwargs):
177
    """
178
    Create a triangulated surface plot.
179
    
180
    Parameters:
181
    - x: array-like, x coordinates of vertices
182
    - y: array-like, y coordinates of vertices
183
    - z: array-like, z coordinates of vertices
184
    - simplices: array-like, triangulation connectivity (if None, computed automatically)
185
    - colormap: str or list, color scale for surface
186
    - show_colorbar: bool, whether to show color bar
187
    - edges_color: str, color for triangle edges
188
    - title: str, figure title
189
    
190
    Returns:
191
    Figure: Plotly figure object with triangulated surface
192
    """
193
```
194

195
### Table and Matrix Visualizations
196

197
Functions for creating formatted tables and matrix displays.
198

199
```python { .api }
200
def create_table(table_text, colorscale=None, font_colors=None, index=False, 
201
                index_title='', annotation_offset=0.45, height_constant=30, 
202
                hoverinfo='none', **kwargs):
203
    """
204
    Create a formatted table visualization.
205
    
206
    Parameters:
207
    - table_text: 2D array-like, table data with headers in first row
208
    - colorscale: str or list, background color scale for cells
209
    - font_colors: 2D array-like, font colors for each cell
210
    - index: bool, whether to include row indices
211
    - index_title: str, title for index column
212
    - annotation_offset: float, vertical offset for text annotations
213
    - height_constant: float, height scaling factor for rows
214
    - hoverinfo: str, hover information mode
215
    
216
    Returns:
217
    Figure: Plotly figure object with formatted table
218
    """
219

220
def create_2d_density(x, y, colorscale='Blues', ncontours=20, hist_color=(0, 0, 0.5), 
221
                     point_color=(0, 0, 0.5), point_size=2, title='2D Density Plot', 
222
                     height=600, width=600):
223
    """
224
    Create a 2D density plot with marginal histograms.
225
    
226
    Parameters:
227
    - x: array-like, x coordinates
228
    - y: array-like, y coordinates
229
    - colorscale: str or list, color scale for density contours
230
    - ncontours: int, number of contour levels
231
    - hist_color: tuple, RGB color for marginal histograms
232
    - point_color: tuple, RGB color for scatter points
233
    - point_size: float, size of scatter points
234
    - title: str, figure title
235
    - height: int, figure height in pixels
236
    - width: int, figure width in pixels
237
    
238
    Returns:
239
    Figure: Plotly figure object with 2D density plot
240
    """
241
```
242

243
### Project Management and Specialized Charts
244

245
Functions for project management visualizations and specialized chart types.
246

247
```python { .api }
248
def create_gantt(df, colors=None, index_col=None, show_colorbar=False, 
249
                reverse_colors=False, title='Gantt Chart', bar_width=0.2, 
250
                showgrid_x=False, showgrid_y=False, height=600, width=900, 
251
                tasks=None, task_names=None, data=None, **kwargs):
252
    """
253
    Create a Gantt chart for project timeline visualization.
254
    
255
    Parameters:
256
    - df: DataFrame, data with columns for tasks, start times, end times
257
    - colors: dict or list, color mapping for different task categories
258
    - index_col: str, column name to use for task identification
259
    - show_colorbar: bool, whether to show color bar
260
    - reverse_colors: bool, whether to reverse color order
261
    - title: str, chart title
262
    - bar_width: float, width of Gantt bars
263
    - showgrid_x: bool, whether to show x-axis grid
264
    - showgrid_y: bool, whether to show y-axis grid
265
    - height: int, figure height in pixels
266
    - width: int, figure width in pixels
267
    
268
    Returns:
269
    Figure: Plotly figure object with Gantt chart
270
    """
271

272
def create_bullet(ranges, measures, subtitles=None, titles=None, 
273
                 orientation='h', measure_colors=None, range_colors=None, 
274
                 scatter_options=None, **kwargs):
275
    """
276
    Create bullet charts for performance measurement.
277
    
278
    Parameters:
279
    - ranges: list of lists, background range values for each chart
280
    - measures: list of lists, performance measure values for each chart  
281
    - subtitles: list of str, subtitles for each chart
282
    - titles: list of str, main titles for each chart
283
    - orientation: str, chart orientation ('h' for horizontal, 'v' for vertical)
284
    - measure_colors: list of str, colors for measure markers
285
    - range_colors: list of str, colors for background ranges
286
    - scatter_options: dict, styling options for measure markers
287
    
288
    Returns:
289
    Figure: Plotly figure object with bullet charts
290
    """
291

292
def create_scatterplotmatrix(df, diag='scatter', size=10, height=500, width=500, 
293
                           title='Scatterplot Matrix', **kwargs):
294
    """
295
    Create a scatterplot matrix for multivariate data exploration.
296
    
297
    Parameters:
298
    - df: DataFrame, data for matrix with numeric columns
299
    - diag: str, diagonal plot type ('scatter', 'histogram', 'box')
300
    - size: float, marker size for scatter plots
301
    - height: int, figure height in pixels
302
    - width: int, figure width in pixels  
303
    - title: str, figure title
304
    
305
    Returns:
306
    Figure: Plotly figure object with scatterplot matrix
307
    """
308
```
309

310
### Geographic and Specialized Visualizations
311

312
Additional specialized chart types for specific visualization needs.
313

314
```python { .api }
315
def create_hexbin_mapbox(data_frame, lat=None, lon=None, color=None, 
316
                        agg_func=np.mean, gridsize=30, min_count=1, 
317
                        opacity=0.5, labels=None, color_continuous_scale=None, 
318
                        range_color=None, mapbox_style='open-street-map', 
319
                        zoom=8, center=None, animation_frame=None, **kwargs):
320
    """
321
    Create hexagonal binning visualization on mapbox.
322
    
323
    Parameters:
324
    - data_frame: DataFrame, data with lat/lon coordinates
325
    - lat: str, column name for latitude
326
    - lon: str, column name for longitude
327
    - color: str, column name for color aggregation
328
    - agg_func: callable, aggregation function for hexbins
329
    - gridsize: int, number of hexagons along x-axis
330
    - min_count: int, minimum points required per hexbin
331
    - opacity: float, hexbin opacity (0-1)
332
    - mapbox_style: str, mapbox style
333
    - zoom: int, initial map zoom level
334
    - center: dict, map center coordinates {'lat': float, 'lon': float}
335
    
336
    Returns:
337
    Figure: Plotly figure object with hexbin mapbox
338
    """
339

340
def create_ternary_contour(coordinates, values, pole_labels=['a', 'b', 'c'], 
341
                          interp_mode='cartesian', ncontours=None, 
342
                          colorscale='Viridis', showscale=True, **kwargs):
343
    """
344
    Create contour plots on ternary coordinate system.
345
    
346
    Parameters:
347
    - coordinates: array-like, ternary coordinates as 3-column array
348
    - values: array-like, values for contouring at each coordinate
349
    - pole_labels: list of str, labels for the three ternary axes
350
    - interp_mode: str, interpolation mode ('cartesian' or 'barycentric')  
351
    - ncontours: int, number of contour levels
352
    - colorscale: str or list, color scale for contours
353
    - showscale: bool, whether to show color scale
354
    
355
    Returns:
356
    Figure: Plotly figure object with ternary contour plot
357
    """
358

359
def create_parallel_coordinates(df, class_column=None, cols=None, 
360
                               dimensions=None, color=None, 
361
                               colorscale='Viridis', **kwargs):
362
    """
363
    Create parallel coordinates plot for multivariate data.
364
    
365
    Parameters:
366
    - df: DataFrame, data with numeric columns for parallel axes
367
    - class_column: str, column name for color encoding classes
368
    - cols: list of str, specific columns to include as dimensions
369
    - dimensions: list of dict, custom dimension configurations
370
    - color: str or array-like, values for color encoding
371
    - colorscale: str or list, color scale for lines
372
    
373
    Returns:
374
    Figure: Plotly figure object with parallel coordinates plot
375
    """
376
```
377

378
## Usage Examples
379

380
```python
381
import plotly.figure_factory as ff
382
import numpy as np
383
import pandas as pd
384

385
# Create annotated heatmap
386
z = [[1, 20, 30], [20, 1, 60], [30, 60, 1]]
387
x = ['Team A', 'Team B', 'Team C']  
388
y = ['Team A', 'Team B', 'Team C']
389

390
fig = ff.create_annotated_heatmap(z, x=x, y=y, colorscale='Viridis')
391
fig.update_layout(title='Team Performance Correlation')
392
fig.show()
393

394
# Create distribution plot
395
data1 = np.random.randn(200)
396
data2 = np.random.randn(200) + 2
397
data3 = np.random.randn(200) - 2
398

399
hist_data = [data1, data2, data3]
400
group_labels = ['Group 1', 'Group 2', 'Group 3']
401

402
fig = ff.create_distplot(hist_data, group_labels, bin_size=0.2)
403
fig.update_layout(title='Distribution Comparison')
404
fig.show()
405

406
# Create Gantt chart
407
df_gantt = pd.DataFrame([
408
    dict(Task="Job A", Start='2023-01-01', Finish='2023-01-15', Resource='Alice'),
409
    dict(Task="Job B", Start='2023-01-10', Finish='2023-01-25', Resource='Bob'), 
410
    dict(Task="Job C", Start='2023-01-20', Finish='2023-02-10', Resource='Alice')
411
])
412

413
fig = ff.create_gantt(df_gantt, colors={'Alice': 'rgb(220, 0, 0)', 
414
                                       'Bob': 'rgb(0, 0, 220)'})
415
fig.update_layout(title='Project Timeline')
416
fig.show()
417

418
# Create candlestick chart
419
dates = pd.date_range('2023-01-01', periods=30, freq='D')
420
open_prices = 100 + np.random.randn(30).cumsum()
421
high_prices = open_prices + np.random.uniform(0, 5, 30)
422
low_prices = open_prices - np.random.uniform(0, 5, 30)
423
close_prices = open_prices + np.random.randn(30)
424

425
fig = ff.create_candlestick(open_prices, high_prices, low_prices, 
426
                           close_prices, dates=dates)
427
fig.update_layout(title='Stock Price Chart', xaxis_rangeslider_visible=False)
428
fig.show()
429
```