reorder content

Author: LiamConnors

doc/python/performance.md

@@ -36,6 +36,77 @@ jupyter:
     thumbnail: thumbnail/webgl.jpg
 ---
 
+## DataFrames Types
+
+Plotly Express natively supports [pandas, Polars, PyArrow, and Modin dataframes](/python/px-arguments). When building figures with Plotly Express, changing your dataframe library may help improve performance.
+
+## NumPy and NumPy Convertible Arrays for Improved Performance
+
+*New in Plotly.py version 6*
+
+Improve the performance of generating Plotly figures that use a large number of data points by using NumPy arrays and other objects that Plotly can convert to NumPy arrays, such as Pandas and Polars Series.
+
+Plotly.py uses Plotly.js for rendering, which supports typed arrays. In Plotly.py, NumPy array and NumPy-convertible arrays are base64 encoded before being passed to Plotly.js for rendering.
+
+### Arrays and Data Types Supported
+
+The following types of objects in Python are supported for improved performance:
+
+- Numpy `numpy.ndarray` objects.
+- Pandas Index, Pandas Series, Polars Series, and PyArrow Chunked Array objects.
+- Array objects that can be converted to `numpy.ndarray` objects. i.e., they implement `"__array__"` or `"__array_interface__"` and return a `numpy.ndarray`.
+
+The following [array data types](https://numpy.org/devdocs/reference/arrays.scalars.html) are supported:
+
+- float32
+- float64
+- int8
+- uint8
+- int16
+- uint16
+- int32
+- uint32
+
+*If the array dtype is **int64** and **uint64**, often the default dtype for arrays in NumPy when no dtype is specified, those dtypes will be changed to other types internally by Plotly.py where possible. When working with NumPY directly, you can [specify the `dtype`](https://numpy.org/doc/stable/user/basics.types.html#array-types-and-conversions-between-types) when creating `ndarray` objects.
+
+### Unsupported Attributes
+
+Arrays passed to attributes with the following names are not supported:
+
+`geojson`, `layers`, and `range`.
+
+
+### Example with NumPy Arrays
+
+Here, we use NumPy arrays with a `go.Scatter3d` figure.
+
+```python
+import plotly.graph_objects as go
+import numpy as np
+
+np.random.seed(1)
+
+# Number of data points
+N = 10000
+
+# Generate random data
+x = np.random.randn(N)
+y = np.random.randn(N).astype('float32')
+z = np.random.randint(size=N, low=0, high=256, dtype='uint8')
+c = np.random.randint(size=N, low=-10, high=10, dtype='int8')
+
+fig = go.Figure(data=[go.Scatter3d(
+    x=x,
+    y=y,
+    z=z,
+    marker=dict(color=c),
+    mode='markers',
+    opacity=0.2
+)])
+
+fig.show()
+```
+
 ## WebGL
 
 `plotly` figures are rendered by web browsers, which broadly speaking have two families of capabilities for rendering graphics:
@@ -152,73 +223,6 @@ fig.show()
 
 See https://plotly.com/python/reference/scattergl/ for more information and chart attribute options!
 
-## NumPy and NumPy Convertible Arrays for Improved Performance
-
-*New in Plotly.py version 6*
-
-Improve the performance of generating Plotly figures that use a large number of data points by using NumPy arrays and other objects that Plotly can convert to NumPy arrays, such as Pandas and Polars Series.
-
-Plotly.py uses Plotly.js for rendering, which supports typed arrays. In Plotly.py, NumPy array and NumPy-convertible arrays are base64 encoded before being passed to Plotly.js for rendering.
-
-### Arrays and Data Types Supported
-
-The following types of objects in Python are supported for improved performance:
-
-- Numpy `numpy.ndarray` objects.
-- Pandas Index, Pandas Series, Polars Series, and PyArrow Chunked Array objects.
-- Array objects that can be converted to `numpy.ndarray` objects. i.e., they implement `"__array__"` or `"__array_interface__"` and return a `numpy.ndarray`.
-
-The following [array data types](https://numpy.org/devdocs/reference/arrays.scalars.html) are supported:
-
-- float32
-- float64
-- int8
-- uint8
-- int16
-- uint16
-- int32
-- uint32
-
-*If the array dtype is **int64** and **uint64**, often the default dtype for arrays in NumPy when no dtype is specified, those dtypes will be changed to other types internally by Plotly.py where possible. When working with NumPY directly, you can [specify the `dtype`](https://numpy.org/doc/stable/user/basics.types.html#array-types-and-conversions-between-types) when creating `ndarray` objects.
-
-### Unsupported Attributes
-
-Arrays passed to attributes with the following names are not supported:
-
-`geojson`, `layers`, and `range`.
-
-
-### Example with NumPy Arrays
-
-Here, we use NumPy arrays with a `go.Scatter3d` figure.
-
-```python
-import plotly.graph_objects as go
-import numpy as np
-
-np.random.seed(1)
-
-# Number of data points
-N = 10000
-
-# Generate random data
-x = np.random.randn(N)
-y = np.random.randn(N).astype('float32')
-z = np.random.randint(size=N, low=0, high=256, dtype='uint8')
-c = np.random.randint(size=N, low=-10, high=10, dtype='int8')
-
-fig = go.Figure(data=[go.Scatter3d(
-    x=x,
-    y=y,
-    z=z,
-    marker=dict(color=c),
-    mode='markers',
-    opacity=0.2
-)])
-
-fig.show()
-```
-
 ## Datashader
 
 Use [Datashader](https://datashader.org/) to reduce the size of a dataset passed to the browser for rendering by creating a rasterized representation of the dataset. This makes it ideal for working with datasets of tens to hundreds of millions of points.