Reorganize docs and add a quickstart guide

.gitignore

@@ -1,3 +1,4 @@
+docs/output/
 /test-outputs/
 
 # packages installed in editable mode

README.md

@@ -1,15 +1,20 @@
 # arcadia-pycolor
 
-Tools for using the Arcadia color palettes and figure style guide in Python.  
-This package automatically generate color palettes and color maps for use with Matplotlib.
+This repo contains a Python package called `arcadia_pycolor` that provides too for using the Arcadia color palettes and for styling Matplotlib figures to comply with Arcadia's style guide.
 
 ## Installation
 
-TODO: write installation instructions once the package is hosted on PyPI.
+The package is hosted on PyPI and can be installed using pip:
+
+```bash
+pip install arcadia-pycolor
+```
 
 ## Usage
 
-See [this notebook](usage_example.ipynb) for examples of how to use the color palettes and color maps in this package.
+Please see [the quickstart guide](docs/quickstart.md) for an introduction to the package and how to use it to style Matplotlib and seaborn plots.
+
+For detailed documentation about the package and links to example plots, see the [documentation README](docs/README.md).
 
 ## Development
 

arcadia_pycolor/colors.py

@@ -25,7 +25,7 @@
 shell = HexCode("shell", "#EDE0D6")
 
 # Neutral colors
-lightgrey = HexCode("lightgrey", "#EBEDE8")
+gray = HexCode("gray", "#EBEDE8")
 chateau = HexCode("chateau", "#BAB0A8")
 bark = HexCode("bark", "#8F8885")
 slate = HexCode("slate", "#43413F")

arcadia_pycolor/mpl.py

@@ -62,11 +62,11 @@ def _arcadia_fonts_found() -> bool:
     return len(arcadia_fonts) > 0
 
 
-def save_figure(context: str = "web", **savefig_kwargs: dict[Any, Any]) -> None:
+def save_figure(fname: str, context: str = "web", **savefig_kwargs: dict[Any, Any]) -> None:
     "Save the current figure with the default settings for web."
     kwargs = SAVEFIG_KWARGS_WEB if context == "web" else SAVEFIG_KWARGS_PRINT
     kwargs.update(**savefig_kwargs)  # type: ignore
-    plt.savefig(**kwargs)  # type: ignore
+    plt.savefig(fname=fname, **kwargs)  # type: ignore
 
 
 def set_yticklabel_font(
@@ -250,7 +250,7 @@ def set_colorbar_ticklabel_monospaced(axis: Union[Axes, None] = None):
         set_ticklabel_monospaced(axis=cbar.ax)
 
 
-def style_axis(
+def style_plot(
     axis: Union[Axes, None] = None,
     monospaced_axes: Literal["x", "y", "both", None] = None,
     categorical_axes: Literal["x", "y", "both", None] = None,
@@ -351,7 +351,7 @@ def add_legend_line(legend: Legend, linewidth: float = LEGEND_SEPARATOR_LINEWIDT
 
     # Check that we haven't already put a drawing area within the legend.
     # This should catch if we've already added the legend line
-    # through a different call to this function, e.g. calling "style_axis".
+    # through a different call to this function, e.g. calling "style_plot".
     # This won't catch if the DrawingArea is added by a user otherwise,
     # but most users shouldn't be adding new DrawingAreas to the legend.
     if not isinstance(entries[0], DrawingArea):

arcadia_pycolor/palettes.py

@@ -36,7 +36,7 @@
 neutral = Palette(
     "Neutral",
     [
-        colors.lightgrey,
+        colors.gray,
         colors.chateau,
         colors.bark,
         colors.slate,

arcadia_pycolor/style_defaults.py

@@ -78,8 +78,9 @@
     "axes.grid.axis": "both",
     "axes.grid.which": "major",
     "axes.prop_cycle": plt.cycler(color=palettes.all_ordered.colors),  # type: ignore
-    "axes.titlesize": TITLE_FONT_SIZE,
+    "axes.titlesize": TITLE_FONT_SIZE + 2,
     "axes.titleweight": "medium",
+    "axes.titlepad": 16,
     "axes.labelsize": BASE_FONT_SIZE,
     "axes.labelweight": "medium",
     "axes.labelcolor": colors.black,

arcadia_pycolor/tests/plotting/test_barplots.py

@@ -67,7 +67,7 @@ def plot_vertical_barplot_with_matplotlib_with_error_bars(ax):
     """
     sample_ids = _word_wrap_sample_ids(BARPLOT_SAMPLE_IDS)
     plt.bar(sample_ids, BARPLOT_NUM_READS, color=apc.aster)
-    apc.mpl.style_axis(ax, monospaced_axes="y")
+    apc.mpl.style_plot(ax, monospaced_axes="y")
     apc.mpl.set_xaxis_categorical()
     apc.mpl.add_commas_to_axis_tick_labels(ax.get_yaxis())
 
@@ -82,7 +82,7 @@ def plot_horizontal_barplot_with_matplotlib_with_error_bars(ax):
     This plot is identical to the vertical version, but with the x and y axes swapped.
     """
     plt.barh(BARPLOT_SAMPLE_IDS, BARPLOT_NUM_READS, color=apc.aster)
-    apc.mpl.style_axis(ax, monospaced_axes="x")
+    apc.mpl.style_plot(ax, monospaced_axes="x")
     apc.mpl.set_yaxis_categorical()
     apc.mpl.add_commas_to_axis_tick_labels(ax.get_xaxis())
     plt.xticks(rotation=30, ha="right")
@@ -110,7 +110,7 @@ def plot_vertical_barplot_with_matplotlib_with_categories(ax):
         BARPLOT_NUM_READS,
         color=colors,
     )
-    apc.mpl.style_axis(ax, monospaced_axes="y")
+    apc.mpl.style_plot(ax, monospaced_axes="y")
     apc.mpl.set_xaxis_categorical()
     apc.mpl.add_commas_to_axis_tick_labels(ax.get_yaxis())
     plt.ylabel("Number of reads")
@@ -129,7 +129,7 @@ def plot_vertical_barplot_with_seaborn(ax):
         saturation=1,
         ax=ax,
     )
-    apc.mpl.style_axis(ax, monospaced_axes="y")
+    apc.mpl.style_plot(ax, monospaced_axes="y")
     apc.mpl.set_xaxis_categorical()
     apc.mpl.add_commas_to_axis_tick_labels(ax.get_yaxis())
     plt.ylabel("Number of reads")
@@ -142,7 +142,7 @@ def plot_horizontal_barplot_with_seaborn(ax):
     This plot is identical to the vertical version, but with the x and y axes swapped.
     """
     sns.barplot(x=BARPLOT_NUM_READS, y=BARPLOT_SAMPLE_IDS, color=apc.aster, saturation=1, ax=ax)
-    apc.mpl.style_axis(ax, monospaced_axes="x")
+    apc.mpl.style_plot(ax, monospaced_axes="x")
     apc.mpl.set_yaxis_categorical()
     apc.mpl.add_commas_to_axis_tick_labels(ax.get_xaxis())
     plt.xticks(rotation=30, ha="right")
@@ -170,7 +170,7 @@ def plot_vertical_barplot_with_seaborn_with_categories(ax):
         ax=ax,
     )
 
-    apc.mpl.style_axis(ax, monospaced_axes="y")
+    apc.mpl.style_plot(ax, monospaced_axes="y")
     apc.mpl.set_xaxis_categorical()
     apc.mpl.add_commas_to_axis_tick_labels(ax.get_yaxis())
 

arcadia_pycolor/tests/plotting/test_bespoke_plots.py

@@ -41,7 +41,7 @@ def test_plot_stacked_barplot(output_dirpath, figure_size):
     assert legend is not None
     legend.set_title("Viability")
 
-    apc.mpl.style_axis(ax, categorical_axes="x", monospaced_axes="y")
+    apc.mpl.style_plot(ax, categorical_axes="x", monospaced_axes="y")
     apc.mpl.save_figure(fname=(output_dirpath / f"test_plot_stacked_barplot_{figure_size}.pdf"))
     plt.close(fig)
 
@@ -58,14 +58,14 @@ def test_plot_multiple_line_plot(output_dirpath, figure_size):
         figsize=apc.mpl.get_figure_dimensions(figure_size),
     )
 
-    colors = [apc.aegean, apc.lightgrey, apc.dragon]
+    colors = [apc.aegean, apc.gray, apc.dragon]
     cmap = apc.Gradient(name="", colors=colors).to_mpl_cmap()
 
     for ind, line in enumerate(lines):
         ax = axes[ind]
         color = cmap(ind / len(lines))
         ax.plot(line, color=color)
-        apc.mpl.style_axis(axis=ax, monospaced_axes="both")
+        apc.mpl.style_plot(axis=ax, monospaced_axes="both")
         ax.set_yticks([])
 
         if ind != len(lines) - 1:
@@ -108,7 +108,7 @@ def test_plot_heatmaps_with_seaborn(output_dirpath, figure_size):
     )
 
     for ax in axs:
-        apc.mpl.style_axis(
+        apc.mpl.style_plot(
             ax,
             categorical_axes="both",
             monospaced_axes="both",

arcadia_pycolor/tests/plotting/test_seaborn_plots.py

@@ -36,7 +36,7 @@ def plot_seaborn_scatterplot(ax):
         ax=ax,
         s=80,
     )
-    apc.mpl.style_axis(monospaced_axes="both")
+    apc.mpl.style_plot(monospaced_axes="both")
 
 
 def plot_seaborn_violinplot(ax):
@@ -56,7 +56,7 @@ def plot_seaborn_violinplot(ax):
         palette=colors,
         ax=ax,
     )
-    apc.mpl.style_axis(categorical_axes="x", monospaced_axes="y")
+    apc.mpl.style_plot(categorical_axes="x", monospaced_axes="y")
 
 
 @pytest.mark.parametrize("figure_size", apc.style_defaults.FIGURE_SIZES.keys())

docs/README.md

@@ -0,0 +1,20 @@
+# Documentation
+
+This directory contains the documentation for the `arcadia_pycolor` package. 
+
+## Quickstart guide
+
+If you are new to using the package, we recommend starting with the [quickstart guide](quickstart.md). This provides a quick introduction to the `arcadia_pycolor` package and how to use it to style Matplotlib and seaborn plots so that they comply with the Arcadia style guide.
+
+## Detailed documentation
+
+- [color_usage.ipynb](color_usage.ipynb): This notebook explains how to use the built-in color palettes and gradients and how to modify them to create your own custom color palettes and gradients.
+
+- [style_usage.ipynb](style_usage.ipynb): This notebook explains in more detail how the package sets the default styles for Matplotlib and how to use the `style_plot` function to apply the Arcadia style guide to individual plots. It also explains additional features of the `apc.mpl` module, like pre-defined figure sizes and a way to save figures with the correct resolution.
+
+- [color_vision_deficiency_tools.ipynb](color_vision_deficiency_tools.ipynb): This notebook explains how to use the color vision deficiency tools in the package to simulate color vision deficiencies in your plots. These tools are for testing the accessibility of your plots to people with color vision deficiencies. They are primarly intended for expert users and graphic designers.
+
+## Examples
+
+The [examples](examples/) directory contains examples of some common plot types that demonstrate how to use the package to style Matplotlib and seaborn plots. 
+