0
# Plotly
1

2
An open-source interactive data visualization library for Python that enables developers to create interactive, browser-based graphs and charts. Built on top of plotly.js, it offers over 30 chart types including scientific charts, 3D graphs, statistical charts, SVG maps, and financial charts with declarative, high-level APIs.
3

4
## Package Information
5

6
- **Package Name**: plotly
7
- **Language**: Python
8
- **Installation**: `pip install plotly`
9

10
## Core Imports
11

12
```python
13
import plotly
14
```
15

16
High-level plotting interface:
17

18
```python
19
import plotly.express as px
20
```
21

22
Low-level graph objects:
23

24
```python
25
import plotly.graph_objects as go
26
```
27

28
Figure factory for specialized charts:
29

30
```python
31
import plotly.figure_factory as ff
32
```
33

34
I/O operations:
35

36
```python
37
import plotly.io as pio
38
```
39

40
Subplot and utility functions:
41

42
```python
43
import plotly.tools as tools
44
```
45

46
## Basic Usage
47

48
```python
49
import plotly.express as px
50
import pandas as pd
51

52
# Create sample data
53
df = pd.DataFrame({
54
    'x': [1, 2, 3, 4, 5],
55
    'y': [2, 4, 3, 5, 6],
56
    'category': ['A', 'B', 'A', 'B', 'A']
57
})
58

59
# Create a simple scatter plot
60
fig = px.scatter(df, x='x', y='y', color='category', 
61
                 title='Interactive Scatter Plot')
62
fig.show()
63

64
# Create a line chart with graph objects
65
import plotly.graph_objects as go
66

67
fig = go.Figure()
68
fig.add_trace(go.Scatter(x=[1, 2, 3, 4], y=[10, 11, 12, 13], mode='lines+markers'))
69
fig.update_layout(title='Line Chart with Graph Objects')
70
fig.show()
71
```
72

73
## Architecture
74

75
Plotly provides multiple levels of abstraction for creating visualizations:
76

77
- **Express (px)**: High-level interface for rapid prototyping with sensible defaults
78
- **Graph Objects (go)**: Low-level interface for full customization and control
79
- **Figure Factory (ff)**: Specialized functions for complex statistical visualizations
80
- **I/O Module**: Export/import capabilities for various formats (HTML, PNG, PDF, JSON)
81

82
The library integrates seamlessly with Jupyter notebooks, supports both online and offline rendering, and provides extensive customization options for publication-quality visualizations.
83

84
## Capabilities
85

86
### Express Plotting Interface
87

88
High-level plotting functions for rapid visualization creation with over 40 chart types including scatter, line, bar, histogram, box plots, geographic maps, 3D plots, and statistical charts.
89

90
```python { .api }
91
def scatter(data_frame, x=None, y=None, color=None, size=None, **kwargs): ...
92
def line(data_frame, x=None, y=None, color=None, **kwargs): ...
93
def bar(data_frame, x=None, y=None, color=None, **kwargs): ...
94
def histogram(data_frame, x=None, y=None, color=None, **kwargs): ...
95
def box(data_frame, x=None, y=None, color=None, **kwargs): ...
96
def scatter_geo(data_frame, lat=None, lon=None, **kwargs): ...
97
def choropleth(data_frame, locations=None, color=None, **kwargs): ...
98
def scatter_3d(data_frame, x=None, y=None, z=None, **kwargs): ...
99
```
100

101
[Express Plotting](./express-plotting.md)
102

103
### Graph Objects Interface
104

105
Low-level figure construction with complete control over traces, layout, and styling using 50+ trace types and comprehensive layout options.
106

107
```python { .api }
108
class Figure:
109
    def __init__(self, data=None, layout=None, **kwargs): ...
110
    def add_trace(self, trace, **kwargs): ...
111
    def update_layout(self, **kwargs): ...
112
    def show(self, **kwargs): ...
113

114
class Scatter:
115
    def __init__(self, x=None, y=None, mode=None, **kwargs): ...
116

117
class Bar:
118
    def __init__(self, x=None, y=None, **kwargs): ...
119

120
class Heatmap:
121
    def __init__(self, z=None, x=None, y=None, **kwargs): ...
122
```
123

124
[Graph Objects](./graph-objects.md)
125

126
### Figure Factory
127

128
Specialized figure creation functions for complex statistical and scientific visualizations including annotated heatmaps, dendrograms, distplots, and candlestick charts.
129

130
```python { .api }
131
def create_annotated_heatmap(z, x=None, y=None, **kwargs): ...
132
def create_dendrogram(X, **kwargs): ...
133
def create_distplot(hist_data, group_labels, **kwargs): ...
134
def create_candlestick(open, high, low, close, dates, **kwargs): ...
135
def create_gantt(df, **kwargs): ...
136
```
137

138
[Figure Factory](./figure-factory.md)
139

140
### Input/Output Operations
141

142
Export and import functionality supporting multiple formats including HTML, static images (PNG, JPEG, PDF, SVG), and JSON serialization with Kaleido engine integration.
143

144
```python { .api }
145
def show(fig, **kwargs): ...
146
def write_html(fig, file, **kwargs): ...
147
def write_image(fig, file, format=None, **kwargs): ...
148
def write_json(fig, file, **kwargs): ...
149
def read_json(file): ...
150
def to_html(fig, **kwargs): ...
151
def to_image(fig, format=None, **kwargs): ...
152
```
153

154
[Input/Output](./io-operations.md)
155

156
### Color Utilities
157

158
Comprehensive color management with built-in color scales, palette generation, and color format conversion supporting sequential, diverging, cyclical, and qualitative color schemes.
159

160
```python { .api }
161
def hex_to_rgb(hex_color): ...
162
def rgb_to_hex(rgb_tuple): ...
163
def make_colorscale(colors, **kwargs): ...
164
def sample_colorscale(colorscale, samplepoints, **kwargs): ...
165

166
# Color scale namespaces
167
sequential: ...  # Viridis, Plasma, Blues, etc.
168
diverging: ...   # RdBu, RdYlBu, Spectral, etc.
169
qualitative: ... # Set1, Set2, Pastel1, etc.
170
cyclical: ...    # IceFire, Edge, Phase, etc.
171
```
172

173
[Color Utilities](./color-utilities.md)
174

175
### Built-in Datasets
176

177
Sample datasets for learning and experimentation including iris, tips, gapminder, stocks, and other commonly used datasets in data science.
178

179
```python { .api }
180
def iris(): ...
181
def tips(): ...
182
def gapminder(): ...
183
def stocks(): ...
184
def flights(): ...
185
def election(): ...
186
```
187

188
[Built-in Datasets](./datasets.md)
189

190
### Subplot and Utility Functions
191

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

194
```python { .api }
195
def make_subplots(rows=1, cols=1, subplot_titles=None, **kwargs): ...
196
def get_subplots(rows=1, columns=1, **kwargs): ...
197
def mpl_to_plotly(fig, resize=False, **kwargs): ...
198
def get_config_plotly_server_url(): ...
199
```
200

201
[Subplot Tools](./tools-utilities.md)
202

203
## Types
204

205
```python { .api }
206
# Core figure type returned by all plotting functions
207
class Figure:
208
    data: tuple  # Traces
209
    layout: dict  # Layout configuration
210
    
211
    def show(self, **kwargs): ...
212
    def update_layout(self, **kwargs): ...
213
    def add_trace(self, trace, **kwargs): ...
214
    def write_html(self, file, **kwargs): ...
215
    def write_image(self, file, **kwargs): ...
216

217
# Widget version for Jupyter notebooks
218
class FigureWidget(Figure):
219
    def __init__(self, data=None, layout=None, **kwargs): ...
220
```