michael review

hgrecco · Sep 5, 2023 · 6f94a94 · 6f94a94
1 parent 330e246
commit 6f94a94
Show file tree

Hide file tree

Showing 2 changed files with 18 additions and 2 deletions.
diff --git a/docs/getting/index.rst b/docs/getting/index.rst
@@ -7,7 +7,9 @@ The getting started guide aims to get you using pint-pandas productively as quic
 What is Pint-pandas?
 --------------------
 
-It is convenient to use the Pandas package when dealing with numerical data, so Pint-pandas provides PintArray. A PintArray is a Pandas ExtensionArray, which allows Pandas to recognise the Quantity and store it in Pandas DataFrames and Series.
+The Pandas package provides powerful DataFrame and Series abstractions for dealing with numerical, temporal, categorical, string-based, and even user-defined data (using its ExtensionArray feature). The Pint package provides a rich and extensible vocabulary of units for constructing Quantities and an equally rich and extensible range of unit conversions to make it easy to perform unit-safe calculations using Quantities. Pint-pandas provides PintArray, aPandas ExtensionArray that efficiently implements Pandas DataFrame and Series functionality as unit-aware operations where appropriate.
+
+Those who have used Pint know well that good units discipline often catches not only simple mistakes, but sometimes more fundamental errors as well. Pint-pandas can reveal similar errors when it comes to slicing and dicing Pandas data.
 
 
 Installation

diff --git a/docs/user/common.rst b/docs/user/common.rst
@@ -29,7 +29,7 @@ Several pandas operations return numpy arrays of ``Quantity`` objects, which can
 
     df = pd.DataFrame(
         {
-            "length": pd.Series(np.array([Q_(2.0, ureg.m), Q_(3.0, ureg.m)],dtype="object")),
+            "length": pd.Series(np.array([Q_(2.0, ureg.m), Q_(3.0, ureg.m)], dtype="object")),
         }
     )
 
@@ -50,3 +50,17 @@ Pint-pandas provides an accessor to fix this issue by converting the non PintArr
 .. ipython:: python
 
     df.pint.convert_object_dtype()
+
+
+Creating DataFrames from Series
+---------------------------------
+
+The default operation of Pandas `pd.concat` function is to perform row-wise concatenation.  When given a list of Series, each of which is backed by a PintArray, this will inefficiently convert all the PintArrays to arrays of `object` type, concatenate the several series into a DataFrame with that many rows, and then leave it up to you to convert that DataFrame back into column-wise PintArrays.  A much more efficient approach is to concatenate Series in a column-wise fashion:
+
+.. ipython:: python
+    :suppress:
+    :okwarning:
+        df = pd.concat(list_of_series, axis=1)
+
+
+This will preserve all the PintArrays in each of the Series.