0
# Subplot and Utility Functions
1

2
Tools for creating subplot layouts, converting matplotlib figures, and other utility operations essential for complex figure composition and integration with other plotting libraries.
3

4
## Capabilities
5

6
### Subplot Creation
7

8
Functions for creating multi-panel figure layouts with customizable subplot arrangements and spacing.
9

10
```python { .api }
11
def make_subplots(rows=1, cols=1, shared_xaxes=False, shared_yaxes=False, 
12
                  start_cell='top-left', print_grid=False, horizontal_spacing=None, 
13
                  vertical_spacing=None, subplot_titles=None, column_widths=None, 
14
                  row_heights=None, specs=None, insets=None, column_titles=None, 
15
                  row_titles=None, x_title=None, y_title=None, **kwargs):
16
    """
17
    Create subplots with customizable layout and spacing.
18
    
19
    Parameters:
20
    - rows: int, number of subplot rows
21
    - cols: int, number of subplot columns  
22
    - shared_xaxes: bool or str, whether to share x-axes across subplots
23
    - shared_yaxes: bool or str, whether to share y-axes across subplots
24
    - start_cell: str, starting position ('top-left', 'bottom-left', etc.)
25
    - horizontal_spacing: float, spacing between subplot columns (0-1)
26
    - vertical_spacing: float, spacing between subplot rows (0-1)
27
    - subplot_titles: list of str, titles for each subplot
28
    - column_widths: list of float, relative widths of subplot columns
29
    - row_heights: list of float, relative heights of subplot rows
30
    - specs: list of list of dict, subplot specifications
31
    - insets: list of dict, inset subplot specifications
32
    - column_titles: list of str, titles for each column
33
    - row_titles: list of str, titles for each row
34
    - x_title: str, shared x-axis title
35
    - y_title: str, shared y-axis title
36
    
37
    Returns:
38
    Figure: Figure object with subplot layout configured
39
    """
40

41
def get_subplots(rows=1, columns=1, print_grid=False, **kwargs):
42
    """
43
    Legacy function for creating subplot layouts (deprecated, use make_subplots).
44
    
45
    Parameters:
46
    - rows: int, number of subplot rows
47
    - columns: int, number of subplot columns
48
    - print_grid: bool, whether to print grid layout
49
    - **kwargs: additional subplot parameters
50
    
51
    Returns:
52
    Figure: Figure object with subplot layout
53
    """
54
```
55

56
### Matplotlib Conversion
57

58
Convert matplotlib figures to plotly format for interactive visualization.
59

60
```python { .api }
61
def mpl_to_plotly(fig, resize=False, strip_style=False, verbose=False):
62
    """
63
    Convert matplotlib figure to plotly figure.
64
    
65
    Parameters:
66
    - fig: matplotlib Figure object to convert
67
    - resize: bool, whether to resize the converted figure
68
    - strip_style: bool, whether to remove matplotlib styling
69
    - verbose: bool, whether to print conversion details
70
    
71
    Returns:
72
    Figure: Plotly figure object equivalent to matplotlib input
73
    """
74
```
75

76
### Configuration Utilities
77

78
Access plotly server configuration and validation utilities.
79

80
```python { .api }
81
def get_config_plotly_server_url():
82
    """
83
    Get configured plotly server URL.
84
    
85
    Returns:
86
    str: Server URL configuration string
87
    """
88

89
def get_graph_obj(obj, obj_type=None):
90
    """
91
    Validate and convert object to plotly graph object.
92
    
93
    Parameters:
94
    - obj: object to convert/validate
95
    - obj_type: str, expected object type
96
    
97
    Returns:
98
    graph object: Validated plotly graph object
99
    """
100

101
def return_figure_from_figure_or_data(figure_or_data, validate_figure):
102
    """
103
    Extract figure from figure or data input.
104
    
105
    Parameters:
106
    - figure_or_data: Figure object or data traces
107
    - validate_figure: bool, whether to validate the figure
108
    
109
    Returns:
110
    Figure: Plotly figure object
111
    """
112
```
113

114
## Usage Examples
115

116
```python
117
import plotly.tools as tools
118
import plotly.graph_objects as go
119
import matplotlib.pyplot as plt
120

121
# Create subplot layout
122
fig = tools.make_subplots(
123
    rows=2, cols=2,
124
    subplot_titles=['Plot 1', 'Plot 2', 'Plot 3', 'Plot 4'],
125
    horizontal_spacing=0.1,
126
    vertical_spacing=0.1
127
)
128

129
# Add traces to specific subplots
130
fig.add_trace(go.Scatter(x=[1, 2, 3], y=[4, 5, 6]), row=1, col=1)
131
fig.add_trace(go.Bar(x=['A', 'B', 'C'], y=[1, 2, 3]), row=1, col=2)
132
fig.add_trace(go.Scatter(x=[1, 2, 3], y=[6, 5, 4]), row=2, col=1)
133
fig.add_trace(go.Heatmap(z=[[1, 2], [3, 4]]), row=2, col=2)
134

135
fig.show()
136

137
# Convert matplotlib figure
138
plt.figure(figsize=(8, 6))
139
plt.plot([1, 2, 3, 4], [1, 4, 2, 3])
140
plt.title('Matplotlib Figure')
141
mpl_fig = plt.gcf()
142

143
# Convert to plotly
144
plotly_fig = tools.mpl_to_plotly(mpl_fig)
145
plotly_fig.show()
146

147
# Shared axes example
148
fig_shared = tools.make_subplots(
149
    rows=3, cols=1,
150
    shared_xaxes=True,
151
    vertical_spacing=0.02,
152
    subplot_titles=['Time Series 1', 'Time Series 2', 'Time Series 3']
153
)
154

155
# Add time series data
156
import pandas as pd
157
dates = pd.date_range('2023-01-01', periods=100)
158
fig_shared.add_trace(go.Scatter(x=dates, y=range(100)), row=1, col=1)
159
fig_shared.add_trace(go.Scatter(x=dates, y=range(100, 0, -1)), row=2, col=1)
160
fig_shared.add_trace(go.Scatter(x=dates, y=[i**2 for i in range(100)]), row=3, col=1)
161

162
fig_shared.show()
163
```