Plot options (#18)

* initial stab at global figure options

* added figure options

* pandas api needs overhaul

* added some docstrings

* fixed bug in drawing, needs tests

* added tests for axis drawing

* fixed extra args passed in pandas api

* fixed extra args passed in pandas api

* added test for drawing canvas

* added some docs in drawing module

* updated docs for API ref

* added custom api docs

* revert makefile change

* updated docstrings

* updated docs with new options for plotting

* fixed the drawing tests

* updated examples and changelog

CHANGELOG.rst

@@ -3,6 +3,13 @@ Changelog
 =========
 
 
+Version 0.1.4
+-------------
+- Fixed bug in x-axis drawing, spurious rounding
+- Added options to modify global figure properties, e.g. xlim, figsize, etc
+- Updated docs for manually curated API reference as opposed to sphinx api-doc
+
+
 Version 0.1.3
 -------------
 - Fixed bug in x-axis drawing, now tick marks are aligned with plot

docs/api.rst

@@ -0,0 +1,21 @@
+.. _api_reference:
+
+API Reference
+===================
+
+Plotting functions
+-------------------
+
+.. autofunction:: shellplot.plot
+
+.. autofunction:: shellplot.hist
+
+.. autofunction:: shellplot.barh
+
+.. autofunction:: shellplot.boxplot
+
+
+Data loading
+-------------------
+
+.. autofunction:: shellplot.load_dataset

docs/examples/basic_usage.rst

@@ -45,6 +45,54 @@ Scatter plots can be created via the ``plot`` function::
               -4               -2               0                 2                4
 
 
+It is possible to modify the appearance of the plot by passing keyword args,
+using a similar syntax to `matplotlib`_. E.g. we could modify the above call to
+``plot`` like so::
+
+
+        >>> import numpy as np
+        >>> import shellplot as plt
+        >>> x = np.arange(-4, 4, 0.01)
+        >>> y = np.cos(x)
+        >>> plt_str = plt.plot(
+                x, y,
+                figsize=(40, 21),
+                xlim=(0, 3),
+                ylim=(-1, 1),
+                xlabel="x",
+                ylabel="cos(x)",
+                return_type="str",
+            )
+        >>> print(plt_str)
+
+          cos(x)
+          1.0┤+++++
+             |    ++++
+             |       +++
+             |         +++
+             |           +++
+          0.5┤             ++
+             |              +++
+             |                ++
+             |                 ++
+             |                   ++
+          0.0┤                    ++
+             |                     ++
+             |                      +++
+             |                        ++
+             |                         ++
+         -0.5┤                           ++
+             |                            +++
+             |                              ++
+             |                               ++++
+             |                                  ++++
+         -1.0┤                                     +++
+             └┬------------┬------------┬------------┬
+              0            1            2            3
+                                  x
+
+Please refer to :ref:`api_reference` for the full list of possible options.
+
 Histogram
 -------------------
 
@@ -212,3 +260,4 @@ parameter::
 
 
 .. _pandas: https://pandas.pydata.org/
+.. _matplotlib: https://matplotlib.org/contents.html#

docs/index.rst

@@ -53,10 +53,11 @@ Contents
 
    Installation <installation>
    Examples <examples/index>
+   API Reference <api>
    License <license>
    Authors <authors>
    Changelog <changelog>
-   Module Reference <api/modules>
+
 
 
 Indices and tables

docs/installation.rst

@@ -11,3 +11,17 @@ Install shellplot via ``pip``::
 
 This will install the latest stable version, as well as the required
 dependencies.
+
+
+Dependencies
+-------------
+
+Shellplot has the following dependencies, all of which are installed automatically
+with the above installation command:
+
+- python 3.6 or newer
+- `Numpy`_
+- `Pandas`_
+
+.. _NumPy: http://www.numpy.org/
+.. _Pandas: http://pandas.pydata.org

examples/basic_usage.py

@@ -4,13 +4,31 @@
 
 x = np.arange(-4, 4, 0.01)
 y = np.cos(x)
-plt.plot(x, y)
+plt.plot(x, y, xlabel="x", ylabel="f(x)", figsize=(60, 25))
+
+plt_str = plt.plot(
+    x,
+    y,
+    figsize=(40, 21),
+    xlim=(0, 3),
+    ylim=(-1, 1),
+    xlabel="x",
+    ylabel="cos(x)",
+    return_type="str",
+)
+print(plt_str)
+
 
 x = [np.random.randn(100) for i in range(3)]
-plt.boxplot(x, labels=np.array(["dist_1", "dist_2", "dist_3"]))
+plt.boxplot(x, labels=np.array(["dist_1", "dist_2", "dist_3"]), figsize=(40, 25))
 
-x = np.random.randn(100)
-plt.hist(x)
+x = np.random.randn(1000)
+plt.hist(x, bins=12, figsize=(40, 20), xlabel="normal distribution")
 
 x = np.logspace(0, 1, 3)
-plt.barh(x, labels=np.array(["bar_1", "bar_b", "bar_3"]))
+plt.barh(
+    x,
+    labels=np.array(["bar_1", "bar_b", "bar_3"]),
+    xlabel="my_fun_bars",
+    figsize=(40, 20),
+)

examples/penguins_eda.py

@@ -8,16 +8,20 @@
 df = plt.load_dataset("penguins")
 
 
-df["body_mass_g"].hist()
+df["body_mass_g"].hist(figsize=(60, 20))
 
-df[["species", "island"]].value_counts().plot.barh()
+df["species"].value_counts().plot.barh(figsize=(30, 13))
 
-df.boxplot(column=["bill_length_mm", "bill_depth_mm"])
 
-df.boxplot(column=["bill_length_mm"], by="species")
+# df[["island", "species"]].value_counts().plot.barh(figsize=(30, 30))
 
-df.dropna().plot("bill_length_mm", "flipper_length_mm", color="species")
+df.boxplot(column=["bill_length_mm", "bill_depth_mm"], figsize=(80, 13))
 
+df.boxplot(column=["bill_length_mm"], by="species", figsize=(30, 13))
+
+df.dropna().plot(
+    "bill_length_mm", "flipper_length_mm", color="species", figsize=(40, 23)
+)
 
 # df.loc[df["species"] == "Adelie"].dropna().plot(
 #     "bill_depth_mm", "body_mass_g", color="island"

src/shellplot/axis.py

@@ -18,22 +18,26 @@
 
 
 class Axis:
-    def __init__(self, display_length, title=None, limits=None):
+    def __init__(self, display_length, label=None, limits=None):
         self.display_max = display_length - 1
-        self._title = title
-        self._limits = limits
+        self.label = label
+        self.limits = limits
+
+        # reverted setting ticks and labels - need to think about the logic here
+        # self.ticks = ticks
+        # self.labels = labels
 
     # -------------------------------------------------------------------------
     # Public properties that can be set by the user
     # -------------------------------------------------------------------------
 
     @property
-    def title(self):
-        return self._title
+    def label(self):
+        return self._label
 
-    @title.setter
-    def title(self, title):
-        self._title = title
+    @label.setter
+    def label(self, label):
+        self._label = label
 
     @property
     def limits(self):
@@ -42,7 +46,8 @@ def limits(self):
     @limits.setter
     def limits(self, limits):
         self._limits = limits
-        self.fit()  # setting axis limits automatically fits the axis
+        if limits is not None:
+            self.fit()  # setting axis limits automatically fits the axis
 
     @property
     def n_ticks(self):
@@ -89,7 +94,9 @@ def fit(self, x=None):
         return self
 
     def transform(self, x):
-        return np.around(self.scale * (x - self.limits[0])).astype(int)
+        x_scaled = np.around(self.scale * (x - self.limits[0])).astype(int)
+        within_display = np.logical_and(x_scaled >= 0, x_scaled <= self.display_max)
+        return np.ma.masked_where(~within_display, x_scaled)
 
     def fit_transform(self, x):
         self = self.fit(x)