From 50a6406d38e13c890f792bc237a175f989c3194c Mon Sep 17 00:00:00 2001 From: Andrew Date: Tue, 27 Jun 2023 21:46:30 +0100 Subject: [PATCH 01/10] docs --- docs/Makefile | 20 ++++ docs/_static/index_api.svg | 26 +++++ docs/_static/index_contribute.svg | 21 ++++ docs/_static/index_getting_started.svg | 18 ++++ docs/_static/index_user_guide.svg | 18 ++++ docs/_static/logo-full.jpg | Bin 0 -> 11783 bytes docs/_static/style.css | 45 ++++++++ docs/conf.py | 92 ++++++++++++++++ docs/getting/faq.rst | 42 ++++++++ docs/getting/index.rst | 54 ++++++++++ docs/getting/tutorial.rst | 88 +++++++++++++++ docs/index.rst | 86 +++++++++++++++ docs/make.bat | 35 ++++++ docs/user/index.rst | 14 +++ docs/user/initializing.rst | 37 +++++++ docs/user/reading.rst | 142 +++++++++++++++++++++++++ docs/user/unitsincells.rst | 44 ++++++++ requirements_docs.txt | 22 ++++ 18 files changed, 804 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/_static/index_api.svg create mode 100644 docs/_static/index_contribute.svg create mode 100644 docs/_static/index_getting_started.svg create mode 100644 docs/_static/index_user_guide.svg create mode 100644 docs/_static/logo-full.jpg create mode 100644 docs/_static/style.css create mode 100644 docs/conf.py create mode 100644 docs/getting/faq.rst create mode 100644 docs/getting/index.rst create mode 100644 docs/getting/tutorial.rst create mode 100644 docs/index.rst create mode 100644 docs/make.bat create mode 100644 docs/user/index.rst create mode 100644 docs/user/initializing.rst create mode 100644 docs/user/reading.rst create mode 100644 docs/user/unitsincells.rst create mode 100644 requirements_docs.txt diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/index_api.svg b/docs/_static/index_api.svg new file mode 100644 index 00000000..ceb5be6a --- /dev/null +++ b/docs/_static/index_api.svg @@ -0,0 +1,26 @@ + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + diff --git a/docs/_static/index_contribute.svg b/docs/_static/index_contribute.svg new file mode 100644 index 00000000..24a29f32 --- /dev/null +++ b/docs/_static/index_contribute.svg @@ -0,0 +1,21 @@ + + + + + + + + + image/svg+xml + + + + + + + + + + + + diff --git a/docs/_static/index_getting_started.svg b/docs/_static/index_getting_started.svg new file mode 100644 index 00000000..2afbbe1d --- /dev/null +++ b/docs/_static/index_getting_started.svg @@ -0,0 +1,18 @@ + + + + + + + + + image/svg+xml + + + + + + + + + diff --git a/docs/_static/index_user_guide.svg b/docs/_static/index_user_guide.svg new file mode 100644 index 00000000..d70b3d73 --- /dev/null +++ b/docs/_static/index_user_guide.svg @@ -0,0 +1,18 @@ + + + + + + + + + image/svg+xml + + + + + + + + + diff --git a/docs/_static/logo-full.jpg b/docs/_static/logo-full.jpg new file mode 100644 index 0000000000000000000000000000000000000000..e672456d17d4b0893bb926c092e338c9aa96ad9a GIT binary patch literal 11783 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 literal 0 HcmV?d00001 diff --git a/docs/_static/style.css b/docs/_static/style.css new file mode 100644 index 00000000..b2bc297d --- /dev/null +++ b/docs/_static/style.css @@ -0,0 +1,45 @@ +@import url('https://fonts.googleapis.com/css2?family=Lato:ital,wght@0,400;0,700;0,900;1,400;1,700;1,900&family=Open+Sans:ital,wght@0,400;0,600;1,400;1,600&display=swap'); + +body { + font-family: 'Open Sans', sans-serif; +} + +h1 { + font-family: "Lato", sans-serif; +} + +pre, code { + font-size: 100%; + line-height: 155%; +} + +/* Main page overview cards */ + +.sd-card { + border-radius: 0; + padding: 30px 10px 20px 10px; + margin: 10px 0px; +} + +.sd-card .sd-card-header { + text-align: center; +} + +.sd-card .sd-card-header .sd-card-text { + margin: 0px; +} + +.sd-card .sd-card-img-top { + height: 52px; + width: 52px; + margin-left: auto; + margin-right: auto; +} + +.sd-card .sd-card-header { + border: none; + color: #150458 !important; + font-size: var(--pst-font-size-h5); + font-weight: bold; + padding: 2.5rem 0rem 0.5rem 0rem; +} diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..89c65ec9 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,92 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +import datetime +from importlib.metadata import version + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. + + +# -- Project information ----------------------------------------------------- + +project = 'pint-pandas' +author = "Hernan E. Grecco" + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. + +try: # pragma: no cover + version = version(project) +except Exception: # pragma: no cover + # we seem to have a local copy not installed without setuptools + # so the reported version will be unknown + version = "unknown" + +release = version +this_year = datetime.date.today().year +copyright = f"2020-{this_year}, Pint-pandas Developers" + +exclude_patterns = ["_build"] + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.autosectionlabel", + "sphinx.ext.doctest", + "sphinx.ext.intersphinx", + "sphinx.ext.coverage", + "sphinx.ext.napoleon", + "sphinx.ext.viewcode", + "sphinx.ext.mathjax", + "matplotlib.sphinxext.plot_directive", + "nbsphinx", + "sphinx_copybutton", + "IPython.sphinxext.ipython_directive", + "IPython.sphinxext.ipython_console_highlighting", + "sphinx_design", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_book_theme" + +html_theme_options = { + "repository_url": "https://github.com/hgrecco/pint-pandas", + "repository_branch": "master", + "use_repository_button": True, + "use_issues_button": True, + "extra_navbar": "", + "navbar_footer_text": "", +} +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] +html_logo = "_static/logo-full.jpg" + +html_static_path = ["_static"] +html_css_files = ["style.css"] diff --git a/docs/getting/faq.rst b/docs/getting/faq.rst new file mode 100644 index 00000000..75d7db74 --- /dev/null +++ b/docs/getting/faq.rst @@ -0,0 +1,42 @@ +.. _faq: + +Frequently asked questions +========================== + + +Why the name *Pint*? +-------------------- + +Pint is a unit and sounds like Python in the first syllable. Most important, it is a good unit for beer. + + +You mention other similar Python libraries. Can you point me to those? +---------------------------------------------------------------------- + +`natu `_ + +`Buckingham `_ + +`Magnitude `_ + +`SciMath `_ + +`Python-quantities `_ + +`Unum `_ + +`Units `_ + +`udunitspy `_ + +`SymPy `_ + +`cf units `_ + +`astropy units `_ + +`yt `_ + +`measurement `_ + +If you're aware of another one, please contribute a patch to the docs. diff --git a/docs/getting/index.rst b/docs/getting/index.rst new file mode 100644 index 00000000..97b44e97 --- /dev/null +++ b/docs/getting/index.rst @@ -0,0 +1,54 @@ +Getting Started +=============== + +The getting started guide aims to get you using pint-pandas productively as quickly as possible. + + +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. + + +Installation +------------ + +Pint-pandas requires pint and pandas. + +.. grid:: 2 + + .. grid-item-card:: Prefer pip? + + **pint-pandas** can be installed via pip from `PyPI `__. + + ++++++++++++++++++++++ + + .. code-block:: bash + + pip install pint-pandas + + .. grid-item-card:: Working with conda? + + **pint-pandas** is part of the `Conda-Forge `__ + channel and can be installed with Anaconda or Miniconda: + + ++++++++++++++++++++++ + + .. code-block:: bash + + conda install -c conda-forge pint-pandas + + +That's all! You can check that Pint is correctly installed by starting up python, and importing Pint: + +.. code-block:: python + + >>> import pint_pandas + >>> pint_pandas.__version__ # doctest: +SKIP + +.. toctree:: + :maxdepth: 2 + :hidden: + + tutorial + faq diff --git a/docs/getting/tutorial.rst b/docs/getting/tutorial.rst new file mode 100644 index 00000000..5e0873c9 --- /dev/null +++ b/docs/getting/tutorial.rst @@ -0,0 +1,88 @@ +.. _tutorial: + +************************** +Tutorial +************************** + +This example will show the simplist way to use pandas with pint and the underlying objects. +It's slightly fiddly to set up units compared to reading data and units from a file. +A more typical use case is given in Reading a csv. + + +Imports +----------------------- +First some imports + +.. ipython:: python + + import pandas as pd + import pint + import pint_pandas + + pint_pandas.show_versions() + + +Create a DataFrame +----------------------- +Next, we create a DataFrame with PintArrays as columns. + +.. ipython:: python + + df = pd.DataFrame( + { + "torque": pd.Series([1.0, 2.0, 2.0, 3.0], dtype="pint[lbf ft]"), + "angular_velocity": pd.Series([1.0, 2.0, 2.0, 3.0], dtype="pint[rpm]"), + } + ) + df + + +DataFrame Operations +----------------------- +Operations with columns are units aware so behave as we would intuitively expect. + +.. ipython:: python + + df["power"] = df["torque"] * df["angular_velocity"] + df + + +.. note:: + + Notice that the units are not displayed in the cells of the DataFrame. + If you ever see units in the cells of the DataFrame, something isn't right. + See :ref:`units_in_cells` for more information. + +We can see the columns' units in the dtypes attribute + +.. ipython:: python + + df.dtypes + +Each column can be accessed as a Pandas Series + +.. ipython:: python + + df.power + +Which contains a PintArray + +.. ipython:: python + + df.power.values + +The PintArray contains a Quantity + +.. ipython:: python + + df.power.values.quantity + +Pandas Series Accessors +----------------------- +Pandas Series accessors are provided for most Quantity properties and methods. +Methods that return arrays will be converted to Series. + +.. ipython:: python + + df.power.pint.units + df.power.pint.to("kW") diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..2d84393b --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,86 @@ +:orphan: + +Pint: makes units easy +====================== + +**Useful links**: +`Code Repository `__ | +`Issues `__ | + + + +.. grid:: 1 1 2 2 + :gutter: 2 + + .. grid-item-card:: + :img-top: _static/index_getting_started.svg + :link: getting/index + :link-type: doc + + Getting Started + ^^^^^^^^^^^^^^^ + + New to pint-pandas? Check out the getting started guides. They contain an + introduction to pint-pandas's main concepts and links to additional tutorials. + + .. grid-item-card:: + :img-top: _static/index_user_guide.svg + :link: user/index + :link-type: doc + + User Guide + ^^^^^^^^^^ + + The user guide provides in-depth information on the + key concepts of pint-pandas with useful background information and explanation. + + .. grid-item-card:: + :img-top: _static/index_api.svg + :link: api/base + :link-type: doc + + API reference + ^^^^^^^^^^^^^ + + The reference guide contains a detailed description of the pint-pandas API. + The reference describes how the methods work and which parameters can + be used. It assumes that you have an understanding of the key concepts. + + .. grid-item-card:: + :img-top: _static/index_contribute.svg + :link: dev/contributing + :link-type: doc + + Developer guide + ^^^^^^^^^^^^^^^ + + Saw a typo in the documentation? Want to improve existing functionalities? + The contributing guidelines will guide you through the process of improving + pint-pandas. + + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: For users + + Getting started + User Guide + Advanced topics + ecosystem + API Reference + +.. toctree:: + :maxdepth: 1 + :hidden: + :caption: For developers + + dev/contributing + dev/pint-convert + +.. toctree:: + :maxdepth: 1 + :hidden: + :caption: Community + + GitHub repository \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..954237b9 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/user/index.rst b/docs/user/index.rst new file mode 100644 index 00000000..fa6c00e5 --- /dev/null +++ b/docs/user/index.rst @@ -0,0 +1,14 @@ +User Guide +========== + +In this user guide, you will find detailed descriptions and +examples that describe many common tasks that you can accomplish with pint. + + +.. toctree:: + :maxdepth: 2 + :hidden: + + reading + initializing + unitsincells \ No newline at end of file diff --git a/docs/user/initializing.rst b/docs/user/initializing.rst new file mode 100644 index 00000000..d3ad5dc8 --- /dev/null +++ b/docs/user/initializing.rst @@ -0,0 +1,37 @@ +.. _initializing: + +************************** +Initializing data +************************** + +There are several ways to initialize PintArrays in a DataFrame. Here's the most common methods. We'll use `PA_` and `Q_` as shorthand for PintArray and Quantity. + + + +.. ipython:: python + + import pandas as pd + import pint + import pint_pandas + import io + + PA_ = pint_pandas.PintArray + ureg = pint_pandas.PintType.ureg + Q_ = ureg.Quantity + + df = pd.DataFrame( + { + "length": pd.Series([1.0, 2.0], dtype="pint[m]"), + "width": PA_([2.0, 3.0], dtype="pint[m]"), + "distance": PA_([2.0, 3.0], dtype="m"), + "height": PA_([2.0, 3.0], dtype=ureg.m), + "depth": PA_.from_1darray_quantity(Q_([2, 3], ureg.m)), + "displacement": PA_(Q_([2.0, 3.0], ureg.m)), + } + ) + df + + +.. note:: + + "pint[unit]" must be used for the Series or DataFrame constuctor. diff --git a/docs/user/reading.rst b/docs/user/reading.rst new file mode 100644 index 00000000..16dc3b56 --- /dev/null +++ b/docs/user/reading.rst @@ -0,0 +1,142 @@ +.. _reading: + +************************** +Reading data and plotting +************************** + +Reading from files is the far more standard way to use pandas. To facilitate this, DataFrame accessors are provided to make it easy to get to PintArrays. + + +Read data from csv +----------------------- +First some imports + +.. ipython:: python + + import pandas as pd + import pint + import pint_pandas + import io + + +Here's the contents of the csv file. + +.. ipython:: python + + test_data = """ShaftSpeedIndex,rpm,1200,1200,1200,1600,1600,1600,2300,2300,2300 + pump,,A,B,C,A,B,C,A,B,C + TestDate,No Unit,01/01,01/01,01/01,01/01,01/01,01/01,01/02,01/02,01/02 + ShaftSpeed,rpm,1200,1200,1200,1600,1600,1600,2300,2300,2300 + FlowRate,m^3 h^-1,8.72,9.28,9.31,11.61,12.78,13.51,18.32,17.90,19.23 + DifferentialPressure,kPa,162.03,144.16,136.47,286.86,241.41,204.21,533.17,526.74,440.76 + ShaftPower,kW,1.32,1.23,1.18,3.09,2.78,2.50,8.59,8.51,7.61 + Efficiency,dimensionless,30.60,31.16,30.70,30.72,31.83,31.81,32.52,31.67,32.05""" + +Let's read that into a DataFrame. Here io.StringIO is used in place of reading a file from disk, whereas a csv file path would typically be used and is shown commented. + +.. ipython:: python + + df = pd.read_csv(io.StringIO(test_data), header=[0, 1], index_col=[0, 1]).T + # df = pd.read_csv("/path/to/test_data.csv", header=[0, 1]) + for col in df.columns: + df[col] = pd.to_numeric(df[col], errors="ignore") + df.dtypes + + +Pandas DataFrame Accessors +----------------------- +Then use the DataFrame's pint accessor's quantify method to convert the columns from np.ndarrays to PintArrays, with units from the bottom column level. + +Using 'No Unit' as the unit will prevent quantify converting a column to a PintArray. This can be changed by changing pint_pandas.pint_array.NO_UNIT. + +.. ipython:: python + + df_ = df.pint.quantify(level=-1) + df_ + +Let's confirm the units have been parsed correctly by looking at the dtypes. + +.. ipython:: python + + df_.dtypes + +Here the Efficiency has been parsed as dimensionless. Let's change it to percent. + +.. ipython:: python + + df_["Efficiency"] = pint_pandas.PintArray( + df_["Efficiency"].values.quantity.m, dtype="pint[percent]" + ) + df_.dtypes + +As previously, operations between DataFrame columns are unit aware + +.. ipython:: python + + df_.ShaftPower / df_.ShaftSpeed + df_["ShaftTorque"] = df_.ShaftPower / df_.ShaftSpeed + df_["FluidPower"] = df_["FlowRate"] * df_["DifferentialPressure"] + df_ + + +The DataFrame's pint.dequantify method then allows us to retrieve the units information as a header row once again. + +.. ipython:: python + + df_.pint.dequantify() + +This allows for some rather powerful abilities. For example, to change a column's units + +.. ipython:: python + + df_["FluidPower"] = df_["FluidPower"].pint.to("kW") + df_["FlowRate"] = df_["FlowRate"].pint.to("L/s") + df_["ShaftTorque"] = df_["ShaftTorque"].pint.to("N m") + df_.pint.dequantify() + +The units are harder to read than they need be, so lets change pints default format for displaying units. + +.. ipython:: python + + pint_pandas.PintType.ureg.default_format = "P~" + df_.pint.dequantify() + +or the entire table's units + +.. ipython:: python + + df_.pint.to_base_units().pint.dequantify() + + +Plotting +----------------------- + +Pint's matplotlib support allows columns with the same dimensionality to be plotted. +First, set up matplotlib to use pint's units. + + +.. ipython:: python + + import matplotlib.pyplot as plt + pint_pandas.PintType.ureg.setup_matplotlib() + +Let's convert a column to a different unit and plot two columns with different units. Pint's matplotlib support will automatically convert the units to the first units and add the units to the axis labels. + +.. ipython:: python + + df_['FluidPower'] = df_['FluidPower'].pint.to('W') + df_[["ShaftPower", "FluidPower"]].dtypes + + fig, ax = plt.subplots() + + @savefig plot_simple.png + ax = df_[["ShaftPower", "FluidPower"]].unstack("pump").plot(ax=ax) + + +.. ipython:: python + + ax.yaxis.units + ax.yaxis.label + +.. TODO add index with units example + diff --git a/docs/user/unitsincells.rst b/docs/user/unitsincells.rst new file mode 100644 index 00000000..fc415c9c --- /dev/null +++ b/docs/user/unitsincells.rst @@ -0,0 +1,44 @@ +.. _unitsincells: + +************************** +Units in Cells +************************** + +The most common issue pint-pandas users encouter is that they have a DataFrame with column that aren't PintArrays. +An obvious indicator is unit strings showing in cells when viewing the DataFrame. + + +.. ipython:: python + :suppress: + + import pandas as pd + import pint + import pint_pandas + + PA_ = pint_pandas.PintArray + ureg = pint_pandas.PintType.ureg + Q_ = ureg.Quantity + +.. ipython:: python + :okwarning: + + df = pd.DataFrame( + { + "length": pd.Series(np.array([Q_(2.0, ureg.m), Q_(3.0, ureg.m)],dtype="object")), + } + ) + df + + +To confirm the DataFrame does not contain PintArrays, check the dtypes. + +.. ipython:: python + + df.dtypes + + +Pint-pandas provides an accessor to fix this issue by converting the non PintArray columns to PintArrays. + +.. ipython:: python + + df.pint.convert_object_dtype() \ No newline at end of file diff --git a/requirements_docs.txt b/requirements_docs.txt new file mode 100644 index 00000000..8f441096 --- /dev/null +++ b/requirements_docs.txt @@ -0,0 +1,22 @@ +sphinx>4 +ipython<=8.12 +matplotlib +mip>=1.13 +nbsphinx +numpy +pytest +jupyter_client +ipykernel +ipython +graphviz +xarray +pooch +sparse +dask[complete] +setuptools>=41.2 +Serialize +pygments>=2.4 +sphinx-book-theme==0.3.3 +sphinx_copybutton +sphinx_design +typing_extensions From 2d16990833aec9cc6286e50e40266f9e7c7ba68c Mon Sep 17 00:00:00 2001 From: Andrew Date: Tue, 27 Jun 2023 22:44:02 +0100 Subject: [PATCH 02/10] readthedocs --- .readthedocs.yaml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..d180754e --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,14 @@ +version: 2 +build: + os: ubuntu-22.04 + tools: + python: "3.9" +sphinx: + configuration: docs/conf.py + fail_on_warning: false +python: + install: + - requirements: requirements_docs.txt + - method: pip + path: . + system_packages: false From 5a4c005ed56785ce8db82a1010425aa78ffc4b47 Mon Sep 17 00:00:00 2001 From: Andrew Date: Tue, 27 Jun 2023 22:46:23 +0100 Subject: [PATCH 03/10] conf --- docs/conf.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 89c65ec9..054508f3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -87,6 +87,4 @@ # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] html_logo = "_static/logo-full.jpg" - -html_static_path = ["_static"] html_css_files = ["style.css"] From 1ef1ff86fb49f0801ceceb9ce39b714696c354fb Mon Sep 17 00:00:00 2001 From: Andrew Date: Tue, 27 Jun 2023 21:46:30 +0100 Subject: [PATCH 04/10] docs --- docs/Makefile | 20 ++++ docs/_static/index_api.svg | 26 +++++ docs/_static/index_contribute.svg | 21 ++++ docs/_static/index_getting_started.svg | 18 ++++ docs/_static/index_user_guide.svg | 18 ++++ docs/_static/logo-full.jpg | Bin 0 -> 11783 bytes docs/_static/style.css | 45 ++++++++ docs/conf.py | 92 ++++++++++++++++ docs/getting/faq.rst | 42 ++++++++ docs/getting/index.rst | 54 ++++++++++ docs/getting/tutorial.rst | 88 +++++++++++++++ docs/index.rst | 86 +++++++++++++++ docs/make.bat | 35 ++++++ docs/user/index.rst | 14 +++ docs/user/initializing.rst | 37 +++++++ docs/user/reading.rst | 142 +++++++++++++++++++++++++ docs/user/unitsincells.rst | 44 ++++++++ requirements_docs.txt | 22 ++++ 18 files changed, 804 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/_static/index_api.svg create mode 100644 docs/_static/index_contribute.svg create mode 100644 docs/_static/index_getting_started.svg create mode 100644 docs/_static/index_user_guide.svg create mode 100644 docs/_static/logo-full.jpg create mode 100644 docs/_static/style.css create mode 100644 docs/conf.py create mode 100644 docs/getting/faq.rst create mode 100644 docs/getting/index.rst create mode 100644 docs/getting/tutorial.rst create mode 100644 docs/index.rst create mode 100644 docs/make.bat create mode 100644 docs/user/index.rst create mode 100644 docs/user/initializing.rst create mode 100644 docs/user/reading.rst create mode 100644 docs/user/unitsincells.rst create mode 100644 requirements_docs.txt diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/index_api.svg b/docs/_static/index_api.svg new file mode 100644 index 00000000..ceb5be6a --- /dev/null +++ b/docs/_static/index_api.svg @@ -0,0 +1,26 @@ + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + diff --git a/docs/_static/index_contribute.svg b/docs/_static/index_contribute.svg new file mode 100644 index 00000000..24a29f32 --- /dev/null +++ b/docs/_static/index_contribute.svg @@ -0,0 +1,21 @@ + + + + + + + + + image/svg+xml + + + + + + + + + + + + diff --git a/docs/_static/index_getting_started.svg b/docs/_static/index_getting_started.svg new file mode 100644 index 00000000..2afbbe1d --- /dev/null +++ b/docs/_static/index_getting_started.svg @@ -0,0 +1,18 @@ + + + + + + + + + image/svg+xml + + + + + + + + + diff --git a/docs/_static/index_user_guide.svg b/docs/_static/index_user_guide.svg new file mode 100644 index 00000000..d70b3d73 --- /dev/null +++ b/docs/_static/index_user_guide.svg @@ -0,0 +1,18 @@ + + + + + + + + + image/svg+xml + + + + + + + + + diff --git a/docs/_static/logo-full.jpg b/docs/_static/logo-full.jpg new file mode 100644 index 0000000000000000000000000000000000000000..e672456d17d4b0893bb926c092e338c9aa96ad9a GIT binary patch literal 11783 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 literal 0 HcmV?d00001 diff --git a/docs/_static/style.css b/docs/_static/style.css new file mode 100644 index 00000000..b2bc297d --- /dev/null +++ b/docs/_static/style.css @@ -0,0 +1,45 @@ +@import url('https://fonts.googleapis.com/css2?family=Lato:ital,wght@0,400;0,700;0,900;1,400;1,700;1,900&family=Open+Sans:ital,wght@0,400;0,600;1,400;1,600&display=swap'); + +body { + font-family: 'Open Sans', sans-serif; +} + +h1 { + font-family: "Lato", sans-serif; +} + +pre, code { + font-size: 100%; + line-height: 155%; +} + +/* Main page overview cards */ + +.sd-card { + border-radius: 0; + padding: 30px 10px 20px 10px; + margin: 10px 0px; +} + +.sd-card .sd-card-header { + text-align: center; +} + +.sd-card .sd-card-header .sd-card-text { + margin: 0px; +} + +.sd-card .sd-card-img-top { + height: 52px; + width: 52px; + margin-left: auto; + margin-right: auto; +} + +.sd-card .sd-card-header { + border: none; + color: #150458 !important; + font-size: var(--pst-font-size-h5); + font-weight: bold; + padding: 2.5rem 0rem 0.5rem 0rem; +} diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..89c65ec9 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,92 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +import datetime +from importlib.metadata import version + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. + + +# -- Project information ----------------------------------------------------- + +project = 'pint-pandas' +author = "Hernan E. Grecco" + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. + +try: # pragma: no cover + version = version(project) +except Exception: # pragma: no cover + # we seem to have a local copy not installed without setuptools + # so the reported version will be unknown + version = "unknown" + +release = version +this_year = datetime.date.today().year +copyright = f"2020-{this_year}, Pint-pandas Developers" + +exclude_patterns = ["_build"] + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.autosectionlabel", + "sphinx.ext.doctest", + "sphinx.ext.intersphinx", + "sphinx.ext.coverage", + "sphinx.ext.napoleon", + "sphinx.ext.viewcode", + "sphinx.ext.mathjax", + "matplotlib.sphinxext.plot_directive", + "nbsphinx", + "sphinx_copybutton", + "IPython.sphinxext.ipython_directive", + "IPython.sphinxext.ipython_console_highlighting", + "sphinx_design", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_book_theme" + +html_theme_options = { + "repository_url": "https://github.com/hgrecco/pint-pandas", + "repository_branch": "master", + "use_repository_button": True, + "use_issues_button": True, + "extra_navbar": "", + "navbar_footer_text": "", +} +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] +html_logo = "_static/logo-full.jpg" + +html_static_path = ["_static"] +html_css_files = ["style.css"] diff --git a/docs/getting/faq.rst b/docs/getting/faq.rst new file mode 100644 index 00000000..75d7db74 --- /dev/null +++ b/docs/getting/faq.rst @@ -0,0 +1,42 @@ +.. _faq: + +Frequently asked questions +========================== + + +Why the name *Pint*? +-------------------- + +Pint is a unit and sounds like Python in the first syllable. Most important, it is a good unit for beer. + + +You mention other similar Python libraries. Can you point me to those? +---------------------------------------------------------------------- + +`natu `_ + +`Buckingham `_ + +`Magnitude `_ + +`SciMath `_ + +`Python-quantities `_ + +`Unum `_ + +`Units `_ + +`udunitspy `_ + +`SymPy `_ + +`cf units `_ + +`astropy units `_ + +`yt `_ + +`measurement `_ + +If you're aware of another one, please contribute a patch to the docs. diff --git a/docs/getting/index.rst b/docs/getting/index.rst new file mode 100644 index 00000000..97b44e97 --- /dev/null +++ b/docs/getting/index.rst @@ -0,0 +1,54 @@ +Getting Started +=============== + +The getting started guide aims to get you using pint-pandas productively as quickly as possible. + + +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. + + +Installation +------------ + +Pint-pandas requires pint and pandas. + +.. grid:: 2 + + .. grid-item-card:: Prefer pip? + + **pint-pandas** can be installed via pip from `PyPI `__. + + ++++++++++++++++++++++ + + .. code-block:: bash + + pip install pint-pandas + + .. grid-item-card:: Working with conda? + + **pint-pandas** is part of the `Conda-Forge `__ + channel and can be installed with Anaconda or Miniconda: + + ++++++++++++++++++++++ + + .. code-block:: bash + + conda install -c conda-forge pint-pandas + + +That's all! You can check that Pint is correctly installed by starting up python, and importing Pint: + +.. code-block:: python + + >>> import pint_pandas + >>> pint_pandas.__version__ # doctest: +SKIP + +.. toctree:: + :maxdepth: 2 + :hidden: + + tutorial + faq diff --git a/docs/getting/tutorial.rst b/docs/getting/tutorial.rst new file mode 100644 index 00000000..5e0873c9 --- /dev/null +++ b/docs/getting/tutorial.rst @@ -0,0 +1,88 @@ +.. _tutorial: + +************************** +Tutorial +************************** + +This example will show the simplist way to use pandas with pint and the underlying objects. +It's slightly fiddly to set up units compared to reading data and units from a file. +A more typical use case is given in Reading a csv. + + +Imports +----------------------- +First some imports + +.. ipython:: python + + import pandas as pd + import pint + import pint_pandas + + pint_pandas.show_versions() + + +Create a DataFrame +----------------------- +Next, we create a DataFrame with PintArrays as columns. + +.. ipython:: python + + df = pd.DataFrame( + { + "torque": pd.Series([1.0, 2.0, 2.0, 3.0], dtype="pint[lbf ft]"), + "angular_velocity": pd.Series([1.0, 2.0, 2.0, 3.0], dtype="pint[rpm]"), + } + ) + df + + +DataFrame Operations +----------------------- +Operations with columns are units aware so behave as we would intuitively expect. + +.. ipython:: python + + df["power"] = df["torque"] * df["angular_velocity"] + df + + +.. note:: + + Notice that the units are not displayed in the cells of the DataFrame. + If you ever see units in the cells of the DataFrame, something isn't right. + See :ref:`units_in_cells` for more information. + +We can see the columns' units in the dtypes attribute + +.. ipython:: python + + df.dtypes + +Each column can be accessed as a Pandas Series + +.. ipython:: python + + df.power + +Which contains a PintArray + +.. ipython:: python + + df.power.values + +The PintArray contains a Quantity + +.. ipython:: python + + df.power.values.quantity + +Pandas Series Accessors +----------------------- +Pandas Series accessors are provided for most Quantity properties and methods. +Methods that return arrays will be converted to Series. + +.. ipython:: python + + df.power.pint.units + df.power.pint.to("kW") diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..2d84393b --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,86 @@ +:orphan: + +Pint: makes units easy +====================== + +**Useful links**: +`Code Repository `__ | +`Issues `__ | + + + +.. grid:: 1 1 2 2 + :gutter: 2 + + .. grid-item-card:: + :img-top: _static/index_getting_started.svg + :link: getting/index + :link-type: doc + + Getting Started + ^^^^^^^^^^^^^^^ + + New to pint-pandas? Check out the getting started guides. They contain an + introduction to pint-pandas's main concepts and links to additional tutorials. + + .. grid-item-card:: + :img-top: _static/index_user_guide.svg + :link: user/index + :link-type: doc + + User Guide + ^^^^^^^^^^ + + The user guide provides in-depth information on the + key concepts of pint-pandas with useful background information and explanation. + + .. grid-item-card:: + :img-top: _static/index_api.svg + :link: api/base + :link-type: doc + + API reference + ^^^^^^^^^^^^^ + + The reference guide contains a detailed description of the pint-pandas API. + The reference describes how the methods work and which parameters can + be used. It assumes that you have an understanding of the key concepts. + + .. grid-item-card:: + :img-top: _static/index_contribute.svg + :link: dev/contributing + :link-type: doc + + Developer guide + ^^^^^^^^^^^^^^^ + + Saw a typo in the documentation? Want to improve existing functionalities? + The contributing guidelines will guide you through the process of improving + pint-pandas. + + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: For users + + Getting started + User Guide + Advanced topics + ecosystem + API Reference + +.. toctree:: + :maxdepth: 1 + :hidden: + :caption: For developers + + dev/contributing + dev/pint-convert + +.. toctree:: + :maxdepth: 1 + :hidden: + :caption: Community + + GitHub repository \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..954237b9 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/user/index.rst b/docs/user/index.rst new file mode 100644 index 00000000..fa6c00e5 --- /dev/null +++ b/docs/user/index.rst @@ -0,0 +1,14 @@ +User Guide +========== + +In this user guide, you will find detailed descriptions and +examples that describe many common tasks that you can accomplish with pint. + + +.. toctree:: + :maxdepth: 2 + :hidden: + + reading + initializing + unitsincells \ No newline at end of file diff --git a/docs/user/initializing.rst b/docs/user/initializing.rst new file mode 100644 index 00000000..d3ad5dc8 --- /dev/null +++ b/docs/user/initializing.rst @@ -0,0 +1,37 @@ +.. _initializing: + +************************** +Initializing data +************************** + +There are several ways to initialize PintArrays in a DataFrame. Here's the most common methods. We'll use `PA_` and `Q_` as shorthand for PintArray and Quantity. + + + +.. ipython:: python + + import pandas as pd + import pint + import pint_pandas + import io + + PA_ = pint_pandas.PintArray + ureg = pint_pandas.PintType.ureg + Q_ = ureg.Quantity + + df = pd.DataFrame( + { + "length": pd.Series([1.0, 2.0], dtype="pint[m]"), + "width": PA_([2.0, 3.0], dtype="pint[m]"), + "distance": PA_([2.0, 3.0], dtype="m"), + "height": PA_([2.0, 3.0], dtype=ureg.m), + "depth": PA_.from_1darray_quantity(Q_([2, 3], ureg.m)), + "displacement": PA_(Q_([2.0, 3.0], ureg.m)), + } + ) + df + + +.. note:: + + "pint[unit]" must be used for the Series or DataFrame constuctor. diff --git a/docs/user/reading.rst b/docs/user/reading.rst new file mode 100644 index 00000000..16dc3b56 --- /dev/null +++ b/docs/user/reading.rst @@ -0,0 +1,142 @@ +.. _reading: + +************************** +Reading data and plotting +************************** + +Reading from files is the far more standard way to use pandas. To facilitate this, DataFrame accessors are provided to make it easy to get to PintArrays. + + +Read data from csv +----------------------- +First some imports + +.. ipython:: python + + import pandas as pd + import pint + import pint_pandas + import io + + +Here's the contents of the csv file. + +.. ipython:: python + + test_data = """ShaftSpeedIndex,rpm,1200,1200,1200,1600,1600,1600,2300,2300,2300 + pump,,A,B,C,A,B,C,A,B,C + TestDate,No Unit,01/01,01/01,01/01,01/01,01/01,01/01,01/02,01/02,01/02 + ShaftSpeed,rpm,1200,1200,1200,1600,1600,1600,2300,2300,2300 + FlowRate,m^3 h^-1,8.72,9.28,9.31,11.61,12.78,13.51,18.32,17.90,19.23 + DifferentialPressure,kPa,162.03,144.16,136.47,286.86,241.41,204.21,533.17,526.74,440.76 + ShaftPower,kW,1.32,1.23,1.18,3.09,2.78,2.50,8.59,8.51,7.61 + Efficiency,dimensionless,30.60,31.16,30.70,30.72,31.83,31.81,32.52,31.67,32.05""" + +Let's read that into a DataFrame. Here io.StringIO is used in place of reading a file from disk, whereas a csv file path would typically be used and is shown commented. + +.. ipython:: python + + df = pd.read_csv(io.StringIO(test_data), header=[0, 1], index_col=[0, 1]).T + # df = pd.read_csv("/path/to/test_data.csv", header=[0, 1]) + for col in df.columns: + df[col] = pd.to_numeric(df[col], errors="ignore") + df.dtypes + + +Pandas DataFrame Accessors +----------------------- +Then use the DataFrame's pint accessor's quantify method to convert the columns from np.ndarrays to PintArrays, with units from the bottom column level. + +Using 'No Unit' as the unit will prevent quantify converting a column to a PintArray. This can be changed by changing pint_pandas.pint_array.NO_UNIT. + +.. ipython:: python + + df_ = df.pint.quantify(level=-1) + df_ + +Let's confirm the units have been parsed correctly by looking at the dtypes. + +.. ipython:: python + + df_.dtypes + +Here the Efficiency has been parsed as dimensionless. Let's change it to percent. + +.. ipython:: python + + df_["Efficiency"] = pint_pandas.PintArray( + df_["Efficiency"].values.quantity.m, dtype="pint[percent]" + ) + df_.dtypes + +As previously, operations between DataFrame columns are unit aware + +.. ipython:: python + + df_.ShaftPower / df_.ShaftSpeed + df_["ShaftTorque"] = df_.ShaftPower / df_.ShaftSpeed + df_["FluidPower"] = df_["FlowRate"] * df_["DifferentialPressure"] + df_ + + +The DataFrame's pint.dequantify method then allows us to retrieve the units information as a header row once again. + +.. ipython:: python + + df_.pint.dequantify() + +This allows for some rather powerful abilities. For example, to change a column's units + +.. ipython:: python + + df_["FluidPower"] = df_["FluidPower"].pint.to("kW") + df_["FlowRate"] = df_["FlowRate"].pint.to("L/s") + df_["ShaftTorque"] = df_["ShaftTorque"].pint.to("N m") + df_.pint.dequantify() + +The units are harder to read than they need be, so lets change pints default format for displaying units. + +.. ipython:: python + + pint_pandas.PintType.ureg.default_format = "P~" + df_.pint.dequantify() + +or the entire table's units + +.. ipython:: python + + df_.pint.to_base_units().pint.dequantify() + + +Plotting +----------------------- + +Pint's matplotlib support allows columns with the same dimensionality to be plotted. +First, set up matplotlib to use pint's units. + + +.. ipython:: python + + import matplotlib.pyplot as plt + pint_pandas.PintType.ureg.setup_matplotlib() + +Let's convert a column to a different unit and plot two columns with different units. Pint's matplotlib support will automatically convert the units to the first units and add the units to the axis labels. + +.. ipython:: python + + df_['FluidPower'] = df_['FluidPower'].pint.to('W') + df_[["ShaftPower", "FluidPower"]].dtypes + + fig, ax = plt.subplots() + + @savefig plot_simple.png + ax = df_[["ShaftPower", "FluidPower"]].unstack("pump").plot(ax=ax) + + +.. ipython:: python + + ax.yaxis.units + ax.yaxis.label + +.. TODO add index with units example + diff --git a/docs/user/unitsincells.rst b/docs/user/unitsincells.rst new file mode 100644 index 00000000..fc415c9c --- /dev/null +++ b/docs/user/unitsincells.rst @@ -0,0 +1,44 @@ +.. _unitsincells: + +************************** +Units in Cells +************************** + +The most common issue pint-pandas users encouter is that they have a DataFrame with column that aren't PintArrays. +An obvious indicator is unit strings showing in cells when viewing the DataFrame. + + +.. ipython:: python + :suppress: + + import pandas as pd + import pint + import pint_pandas + + PA_ = pint_pandas.PintArray + ureg = pint_pandas.PintType.ureg + Q_ = ureg.Quantity + +.. ipython:: python + :okwarning: + + df = pd.DataFrame( + { + "length": pd.Series(np.array([Q_(2.0, ureg.m), Q_(3.0, ureg.m)],dtype="object")), + } + ) + df + + +To confirm the DataFrame does not contain PintArrays, check the dtypes. + +.. ipython:: python + + df.dtypes + + +Pint-pandas provides an accessor to fix this issue by converting the non PintArray columns to PintArrays. + +.. ipython:: python + + df.pint.convert_object_dtype() \ No newline at end of file diff --git a/requirements_docs.txt b/requirements_docs.txt new file mode 100644 index 00000000..8f441096 --- /dev/null +++ b/requirements_docs.txt @@ -0,0 +1,22 @@ +sphinx>4 +ipython<=8.12 +matplotlib +mip>=1.13 +nbsphinx +numpy +pytest +jupyter_client +ipykernel +ipython +graphviz +xarray +pooch +sparse +dask[complete] +setuptools>=41.2 +Serialize +pygments>=2.4 +sphinx-book-theme==0.3.3 +sphinx_copybutton +sphinx_design +typing_extensions From 0c478ac24884aa02f256aaf22fa24c7e0b64d243 Mon Sep 17 00:00:00 2001 From: Andrew Date: Tue, 27 Jun 2023 22:44:02 +0100 Subject: [PATCH 05/10] readthedocs --- .readthedocs.yaml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..d180754e --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,14 @@ +version: 2 +build: + os: ubuntu-22.04 + tools: + python: "3.9" +sphinx: + configuration: docs/conf.py + fail_on_warning: false +python: + install: + - requirements: requirements_docs.txt + - method: pip + path: . + system_packages: false From c37b0e0e24f11c852a222086d11764bd9137aed5 Mon Sep 17 00:00:00 2001 From: Andrew Date: Tue, 27 Jun 2023 22:46:23 +0100 Subject: [PATCH 06/10] conf --- docs/conf.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 89c65ec9..054508f3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -87,6 +87,4 @@ # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] html_logo = "_static/logo-full.jpg" - -html_static_path = ["_static"] html_css_files = ["style.css"] From 005129c646669b5b76af594df22643e2f6f6f5fe Mon Sep 17 00:00:00 2001 From: Andrew Date: Tue, 27 Jun 2023 23:43:24 +0100 Subject: [PATCH 07/10] ossies --- .gitignore | 1 + docs/user/{unitsincells.rst => common.rst} | 20 ++++++++++++++------ docs/user/index.rst | 2 +- docs/user/initializing.rst | 13 +++++++------ 4 files changed, 23 insertions(+), 13 deletions(-) rename docs/user/{unitsincells.rst => common.rst} (68%) diff --git a/.gitignore b/.gitignore index d3e751fa..250c3664 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,7 @@ __pycache__ *.pyc .DS_Store docs/_build/ +docs/savefig/ .idea .vscode build/ diff --git a/docs/user/unitsincells.rst b/docs/user/common.rst similarity index 68% rename from docs/user/unitsincells.rst rename to docs/user/common.rst index fc415c9c..175f5bbb 100644 --- a/docs/user/unitsincells.rst +++ b/docs/user/common.rst @@ -1,15 +1,23 @@ -.. _unitsincells: +.. _common: ************************** -Units in Cells +Common Issues ************************** +Pandas support for ``ExtensionArray`` is still in development. As a result, there are some common issues that pint-pandas users may encounter. +This page provides some guidance on how to resolve these issues. + +Units in Cells (Object dtype columns) +------------------------------------- + The most common issue pint-pandas users encouter is that they have a DataFrame with column that aren't PintArrays. An obvious indicator is unit strings showing in cells when viewing the DataFrame. +Several pandas operations return numpy arrays of ``Quantity`` objects, which can cause this. .. ipython:: python :suppress: + :okwarning: import pandas as pd import pint @@ -18,15 +26,15 @@ An obvious indicator is unit strings showing in cells when viewing the DataFrame PA_ = pint_pandas.PintArray ureg = pint_pandas.PintType.ureg Q_ = ureg.Quantity - -.. ipython:: python - :okwarning: - + df = pd.DataFrame( { "length": pd.Series(np.array([Q_(2.0, ureg.m), Q_(3.0, ureg.m)],dtype="object")), } ) + +.. ipython:: python + df diff --git a/docs/user/index.rst b/docs/user/index.rst index fa6c00e5..3cd88f64 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -11,4 +11,4 @@ examples that describe many common tasks that you can accomplish with pint. reading initializing - unitsincells \ No newline at end of file + common \ No newline at end of file diff --git a/docs/user/initializing.rst b/docs/user/initializing.rst index d3ad5dc8..db9db783 100644 --- a/docs/user/initializing.rst +++ b/docs/user/initializing.rst @@ -21,12 +21,13 @@ There are several ways to initialize PintArrays in a DataFrame. Here's the most df = pd.DataFrame( { - "length": pd.Series([1.0, 2.0], dtype="pint[m]"), - "width": PA_([2.0, 3.0], dtype="pint[m]"), - "distance": PA_([2.0, 3.0], dtype="m"), - "height": PA_([2.0, 3.0], dtype=ureg.m), - "depth": PA_.from_1darray_quantity(Q_([2, 3], ureg.m)), - "displacement": PA_(Q_([2.0, 3.0], ureg.m)), + "A": pd.Series([1.0, 2.0], dtype="pint[m]"), + "B": pd.Series([1.0, 2.0]).astype("pint[m]"), + "C": PA_([2.0, 3.0], dtype="pint[m]"), + "D": PA_([2.0, 3.0], dtype="m"), + "E": PA_([2.0, 3.0], dtype=ureg.m), + "F": PA_.from_1darray_quantity(Q_([2, 3], ureg.m)), + "G": PA_(Q_([2.0, 3.0], ureg.m)), } ) df From 7a2e1ad6b04572c0a35c1db6d254f13ea3fb8c66 Mon Sep 17 00:00:00 2001 From: Andrew Date: Wed, 28 Jun 2023 00:38:08 +0100 Subject: [PATCH 08/10] changes --- CHANGES | 4 +--- docs/ecosystem.rst | 12 ++++++++++++ docs/getting/tutorial.rst | 2 +- docs/user/reading.rst | 13 +++++++------ 4 files changed, 21 insertions(+), 10 deletions(-) create mode 100644 docs/ecosystem.rst diff --git a/CHANGES b/CHANGES index 962c5e10..598fb77e 100644 --- a/CHANGES +++ b/CHANGES @@ -4,9 +4,7 @@ pint-pandas Changelog 0.5 (unreleased) ---------------- -<<<<<<< HEAD -- Support for values in columns with integer magnitudes -- Support for magnitudes of any type, such as complex128 or tuples #146 +- ReadTheDocs Documentation created. - Support for pandas 2.0, allowing `.cumsum, .cummax, .cummin` methods for `Series` and `DataFrame`. #186 - Minimum Pint version is 0.21 - Minimum Pandas vesrion is 2.0 diff --git a/docs/ecosystem.rst b/docs/ecosystem.rst new file mode 100644 index 00000000..3442a7df --- /dev/null +++ b/docs/ecosystem.rst @@ -0,0 +1,12 @@ +Ecosystem +========= + +Here is a list of known projects, packages and integrations using pint. + + +Pint packages: +------------------ + +- `pint ` Base package +- `pint-pandas `_ Pandas integration +- `pint-xarray `_ Xarray integration diff --git a/docs/getting/tutorial.rst b/docs/getting/tutorial.rst index 5e0873c9..30996285 100644 --- a/docs/getting/tutorial.rst +++ b/docs/getting/tutorial.rst @@ -6,7 +6,7 @@ Tutorial This example will show the simplist way to use pandas with pint and the underlying objects. It's slightly fiddly to set up units compared to reading data and units from a file. -A more typical use case is given in Reading a csv. +A more typical use case is given in :doc:`Reading from csv <../user/reading>`. Imports diff --git a/docs/user/reading.rst b/docs/user/reading.rst index 16dc3b56..41e837c9 100644 --- a/docs/user/reading.rst +++ b/docs/user/reading.rst @@ -4,7 +4,8 @@ Reading data and plotting ************************** -Reading from files is the far more standard way to use pandas. To facilitate this, DataFrame accessors are provided to make it easy to get to PintArrays. +Reading from files is the far more standard way to use pandas. +To facilitate this, :py:class:`DataFrame` accessors are provided to make it easy to get to :py:class:`PintArray` objects. Read data from csv @@ -44,10 +45,10 @@ Let's read that into a DataFrame. Here io.StringIO is used in place of reading a Pandas DataFrame Accessors ------------------------ -Then use the DataFrame's pint accessor's quantify method to convert the columns from np.ndarrays to PintArrays, with units from the bottom column level. +--------------------------- +Then use the :py:class:`DataFrame`'s pint accessor's quantify method to convert the columns from :py:class:`ndarray` to :py:class:`PintArray`, with units from the bottom column level. -Using 'No Unit' as the unit will prevent quantify converting a column to a PintArray. This can be changed by changing pint_pandas.pint_array.NO_UNIT. +Using 'No Unit' as the unit will prevent quantify converting a column to a :py:class:`PintArray`. This can be changed by changing :py:attr:`pint_pandas.pint_array.NO_UNIT`. .. ipython:: python @@ -94,7 +95,7 @@ This allows for some rather powerful abilities. For example, to change a column' df_["ShaftTorque"] = df_["ShaftTorque"].pint.to("N m") df_.pint.dequantify() -The units are harder to read than they need be, so lets change pints default format for displaying units. +The units are harder to read than they need be, so lets change pint's `default format for displaying units `_. .. ipython:: python @@ -111,7 +112,7 @@ or the entire table's units Plotting ----------------------- -Pint's matplotlib support allows columns with the same dimensionality to be plotted. +Pint's `matplotlib support `_ allows columns with the same dimensionality to be plotted. First, set up matplotlib to use pint's units. From 330e246a86845866b1187774586e3636a141c920 Mon Sep 17 00:00:00 2001 From: Andrew Date: Wed, 28 Jun 2023 00:41:02 +0100 Subject: [PATCH 09/10] lint --- docs/conf.py | 8 ++++---- docs/getting/index.rst | 2 +- docs/getting/tutorial.rst | 6 +++--- docs/index.rst | 2 +- docs/user/common.rst | 8 ++++---- docs/user/index.rst | 2 +- docs/user/initializing.rst | 2 +- docs/user/reading.rst | 13 ++++++------- 8 files changed, 21 insertions(+), 22 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 054508f3..b90fe148 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -14,7 +14,7 @@ # -- Project information ----------------------------------------------------- -project = 'pint-pandas' +project = "pint-pandas" author = "Hernan E. Grecco" # The version info for the project you're documenting, acts as replacement for @@ -59,12 +59,12 @@ ] # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ["_templates"] # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] # -- Options for HTML output ------------------------------------------------- @@ -85,6 +85,6 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = ["_static"] html_logo = "_static/logo-full.jpg" html_css_files = ["style.css"] diff --git a/docs/getting/index.rst b/docs/getting/index.rst index 97b44e97..719574f1 100644 --- a/docs/getting/index.rst +++ b/docs/getting/index.rst @@ -13,7 +13,7 @@ It is convenient to use the Pandas package when dealing with numerical data, so Installation ------------ -Pint-pandas requires pint and pandas. +Pint-pandas requires pint and pandas. .. grid:: 2 diff --git a/docs/getting/tutorial.rst b/docs/getting/tutorial.rst index 30996285..43070121 100644 --- a/docs/getting/tutorial.rst +++ b/docs/getting/tutorial.rst @@ -49,8 +49,8 @@ Operations with columns are units aware so behave as we would intuitively expect .. note:: - Notice that the units are not displayed in the cells of the DataFrame. - If you ever see units in the cells of the DataFrame, something isn't right. + Notice that the units are not displayed in the cells of the DataFrame. + If you ever see units in the cells of the DataFrame, something isn't right. See :ref:`units_in_cells` for more information. We can see the columns' units in the dtypes attribute @@ -79,7 +79,7 @@ The PintArray contains a Quantity Pandas Series Accessors ----------------------- -Pandas Series accessors are provided for most Quantity properties and methods. +Pandas Series accessors are provided for most Quantity properties and methods. Methods that return arrays will be converted to Series. .. ipython:: python diff --git a/docs/index.rst b/docs/index.rst index 2d84393b..317dc2cf 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -83,4 +83,4 @@ Pint: makes units easy :hidden: :caption: Community - GitHub repository \ No newline at end of file + GitHub repository diff --git a/docs/user/common.rst b/docs/user/common.rst index 175f5bbb..7760e3f6 100644 --- a/docs/user/common.rst +++ b/docs/user/common.rst @@ -10,9 +10,9 @@ This page provides some guidance on how to resolve these issues. Units in Cells (Object dtype columns) ------------------------------------- -The most common issue pint-pandas users encouter is that they have a DataFrame with column that aren't PintArrays. +The most common issue pint-pandas users encouter is that they have a DataFrame with column that aren't PintArrays. An obvious indicator is unit strings showing in cells when viewing the DataFrame. -Several pandas operations return numpy arrays of ``Quantity`` objects, which can cause this. +Several pandas operations return numpy arrays of ``Quantity`` objects, which can cause this. .. ipython:: python @@ -26,7 +26,7 @@ Several pandas operations return numpy arrays of ``Quantity`` objects, which can PA_ = pint_pandas.PintArray ureg = pint_pandas.PintType.ureg Q_ = ureg.Quantity - + df = pd.DataFrame( { "length": pd.Series(np.array([Q_(2.0, ureg.m), Q_(3.0, ureg.m)],dtype="object")), @@ -49,4 +49,4 @@ Pint-pandas provides an accessor to fix this issue by converting the non PintArr .. ipython:: python - df.pint.convert_object_dtype() \ No newline at end of file + df.pint.convert_object_dtype() diff --git a/docs/user/index.rst b/docs/user/index.rst index 3cd88f64..ccdd4b03 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -11,4 +11,4 @@ examples that describe many common tasks that you can accomplish with pint. reading initializing - common \ No newline at end of file + common diff --git a/docs/user/initializing.rst b/docs/user/initializing.rst index db9db783..f50fb3ac 100644 --- a/docs/user/initializing.rst +++ b/docs/user/initializing.rst @@ -9,7 +9,7 @@ There are several ways to initialize PintArrays in a DataFrame. Here's the most .. ipython:: python - + import pandas as pd import pint import pint_pandas diff --git a/docs/user/reading.rst b/docs/user/reading.rst index 41e837c9..60758a25 100644 --- a/docs/user/reading.rst +++ b/docs/user/reading.rst @@ -51,14 +51,14 @@ Then use the :py:class:`DataFrame`'s pint accessor's quantify method to convert Using 'No Unit' as the unit will prevent quantify converting a column to a :py:class:`PintArray`. This can be changed by changing :py:attr:`pint_pandas.pint_array.NO_UNIT`. .. ipython:: python - + df_ = df.pint.quantify(level=-1) df_ Let's confirm the units have been parsed correctly by looking at the dtypes. .. ipython:: python - + df_.dtypes Here the Efficiency has been parsed as dimensionless. Let's change it to percent. @@ -69,7 +69,7 @@ Here the Efficiency has been parsed as dimensionless. Let's change it to percent df_["Efficiency"].values.quantity.m, dtype="pint[percent]" ) df_.dtypes - + As previously, operations between DataFrame columns are unit aware .. ipython:: python @@ -101,7 +101,7 @@ The units are harder to read than they need be, so lets change pint's `default f pint_pandas.PintType.ureg.default_format = "P~" df_.pint.dequantify() - + or the entire table's units .. ipython:: python @@ -129,8 +129,8 @@ Let's convert a column to a different unit and plot two columns with different u df_[["ShaftPower", "FluidPower"]].dtypes fig, ax = plt.subplots() - - @savefig plot_simple.png + + @savefig plot_simple.png ax = df_[["ShaftPower", "FluidPower"]].unstack("pump").plot(ax=ax) @@ -140,4 +140,3 @@ Let's convert a column to a different unit and plot two columns with different u ax.yaxis.label .. TODO add index with units example - From 6f94a94912d4b38b352b2c7816421a1331ba14df Mon Sep 17 00:00:00 2001 From: Andrew Date: Wed, 6 Sep 2023 00:43:05 +0100 Subject: [PATCH 10/10] michael review --- docs/getting/index.rst | 4 +++- docs/user/common.rst | 16 +++++++++++++++- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/getting/index.rst b/docs/getting/index.rst index 719574f1..da8a44a5 100644 --- 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 index 7760e3f6..0256db0d 100644 --- 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.