Updated docs structure and added gh-action

dhhagan · Apr 25, 2024 · 9241858 · 9241858
1 parent 9058230
commit 9241858
Show file tree

Hide file tree

Showing 16 changed files with 87 additions and 17 deletions.
diff --git a/docs/example_thumbs/dielplot_thumb.png b/docs/example_thumbs/dielplot_thumb.png
diff --git a/docs/example_thumbs/pollution_rose_thumb.png b/docs/example_thumbs/pollution_rose_thumb.png
diff --git a/docs/example_thumbs/regression_thumb.png b/docs/example_thumbs/regression_thumb.png
diff --git a/docs/examples/_images/regression.png b/docs/examples/_images/regression.png
diff --git a/docs/examples/dielplot.py b/docs/examples/dielplot.py
@@ -2,7 +2,7 @@
 Diurnal Ozone
 =============
 
-_thumb: .4, .4
+_thumb: .8, .8
 """
 import atmospy
 import pandas as pd

diff --git a/docs/examples/pollution_rose.py b/docs/examples/pollution_rose.py
@@ -2,7 +2,7 @@
 Pollution Rose
 ==============
 
-_thumb: .6, .2
+_thumb: .8, .8
 """
 import atmospy
 atmospy.set_theme()

diff --git a/docs/tutorial/plots.rst b/docs/tutorial/plots.rst
@@ -5,28 +5,104 @@
 Plotting Functions
 ===================
 
-Seaborn is a library for making statistical graphics in Python. It builds on top of `matplotlib <https://matplotlib.org/>`_ and integrates closely with `pandas <https://pandas.pydata.org/>`_ data structures.
+Atmospy is a library for making useful, professional figures for atmospheric chemistry and air 
+quality professionals. It is built on top of `matplotlib <https://matplotlib.org/>`_, 
+`pandas <https://pandas.pydata.org/>`_, and `seaborn <https://seaborn.pydata.org>`_. Below, 
+we will walk through examples of how to use atmospy and how you can extend it with 
+seaborn and matplotlib.
 
-Seaborn helps you explore and understand your data. Its plotting functions operate on dataframes and arrays containing whole datasets and internally perform the necessary semantic mapping and statistical aggregation to produce informative plots. Its dataset-oriented, declarative API lets you focus on what the different elements of your plots mean, rather than on the details of how to draw them.
+.. code:: ipython3
 
-Here's an example of what seaborn can do:
+    import atmospy
+    import pandas as pd
+    import numpy as np
+    import seaborn as sns
+    import matplotlib.pyplot as plt
+    
+    atmospy.set_theme()
 
 Comparing Data from Multiple Sensors
 ------------------------------------
 
+Often, we find the need to compare multiple variables against one
+another. In the air sensor world, this may be the regression of two
+variables against one another or one air sensor against a reference
+sensor. Using the ``atmospy.regplot``, we can easily plot the regression
+between two variables, fit a linear model, and display the fit
+parameters on the figure itself:
+
 .. code:: ipython3
 
-    import atmospy
-    
     df = atmospy.load_dataset("air-sensors-pm")
+    
+    # plot the Reference measurement vs Sensor A using defaults
+    atmospy.regplot(df, x="Reference", y="Sensor A");
+
+
+
+.. image:: plots_files/plots_3_0.png
+
+
+Under the hood, ``atmospy.regplot`` is simply making a call to seaborn’s
+``jointplot`` function with a few added pieces including adding a unity
+line and displaying the fit parameters for the linear model in the
+legend.
+
+The call returns a seaborn ``JointGrid`` which is a group of subplots.
+As seen above, the joint axis shows the relationship between the two
+variables with a unity line (1:1), the best fit line (shown in solid
+blue above), and the distributions for each variables shown on the
+marginal axes.
+
+If for some reason, you *don’t* want to fit a linear model to the data,
+you can turn that functionality off by setting ``fit_reg=False``:
 
 .. code:: ipython3
 
-    atmospy.regplot(df, x="Reference", y="Sensor A")
+    atmospy.regplot(df, x="Reference", y="Sensor A", fit_reg=False);
 
 
 
-.. image:: plots_files/plots_3_0.png
+.. image:: plots_files/plots_5_0.png
+
+
+Because we’re just making a call to seaborn’s ``jointplot`` function,
+you can send along most configuration options as keyword arguments to
+``atmospy.regplot``. For example, if you wanted to change what is shown
+on the marginal axes, you can:
+
+.. code:: ipython3
+
+    atmospy.regplot(df, x="Reference", y="Sensor A", marginal_kws={"bins": 25, "fill": False});
+
+
+
+.. image:: plots_files/plots_7_0.png
+
+
+A ``JointGrid`` object is returned, which allows you to continue
+customizing as you’d like:
+
+.. code:: ipython3
+
+    g = atmospy.regplot(df, x="Reference", y="Sensor A")
+    g.plot_marginals(sns.rugplot, color='r', height=-0.15, clip_on=False);
+
+
+
+.. image:: plots_files/plots_9_0.png
+
+
+You can easily edit the marker choice, color of marker, or anything else
+as well:
+
+.. code:: ipython3
+
+    atmospy.regplot(df, x="Reference", y="Sensor A", color='g', marker="^", alpha=.15);
+
+
+
+.. image:: plots_files/plots_11_0.png
 
 
 Evaluating Trends
@@ -49,7 +125,7 @@ Evaluating Trends
 
 
 
-.. image:: plots_files/plots_5_1.png
+.. image:: plots_files/plots_13_1.png
 
 
 Identifying Sources
@@ -63,7 +139,7 @@ Identifying Sources
 
 
 
-.. image:: plots_files/plots_7_0.png
+.. image:: plots_files/plots_15_0.png
 
 
 -  Comparing data

diff --git a/docs/tutorial/plots_files/plots_11_0.png b/docs/tutorial/plots_files/plots_11_0.png
diff --git a/docs/tutorial/plots_files/plots_13_1.png b/docs/tutorial/plots_files/plots_13_1.png
diff --git a/docs/tutorial/plots_files/plots_15_0.png b/docs/tutorial/plots_files/plots_15_0.png
diff --git a/docs/tutorial/plots_files/plots_3_0.png b/docs/tutorial/plots_files/plots_3_0.png
diff --git a/docs/tutorial/plots_files/plots_5_0.png b/docs/tutorial/plots_files/plots_5_0.png
diff --git a/docs/tutorial/plots_files/plots_5_1.png b/docs/tutorial/plots_files/plots_5_1.png
diff --git a/docs/tutorial/plots_files/plots_7_0.png b/docs/tutorial/plots_files/plots_7_0.png
diff --git a/docs/tutorial/plots_files/plots_9_0.png b/docs/tutorial/plots_files/plots_9_0.png
diff --git a/docs/tutorial/pollution_roses.rst b/docs/tutorial/pollution_roses.rst