Restructure multiline and grouped bar chart functions (#20)

* add multiline chart * rewrite grouped bar function * correct x tick placement for grouped bar graph * add requirements file * correct multiline function * add todos * add comments and typehints * formatting * modify ticks function to work with datetime dataframe index * update docstrings * update x tick calculation * correct bar percent change placement * update multiline example plots * add example plot for grouped bar chart * make some small updates to READMEs * increasing borderpad of legend * add legend for line charts * add shaded areas and update legend * add minor ticks * update sphinx gallery * build into root docs folder * Update .gitignore * update sphinx gallery * fix sphinx issues --------- Co-authored-by: Raphael Dumas <[email protected]>
CityofToronto · Apr 22, 2024 · a7bdfa7 · a7bdfa7
1 parent 461fa91
commit a7bdfa7
Show file tree

Hide file tree

Showing 240 changed files with 8,709 additions and 39,132 deletions.
diff --git a/.gitignore b/.gitignore
@@ -138,5 +138,11 @@ $RECYCLE.BIN/
 # Windows shortcuts
 *.lnk
 
+# Database connections 
+db.cfg
+dbsettings.cfg
+
+
 .vscode/
 email_notifications/client_secret.json
+sphinx/build/doctrees/
diff --git a/README.md b/README.md
@@ -1,21 +1,25 @@
 # Welcome to the BDITTO Plotting Gallery !
+
 Are you tired of re-inventing the matplotlib wheel every time you need a chart for a new project?
 Did you forget where to find the right colour palette for those bars?
 Do you need a total rewrite just to include one more line in a line chart?
 If you said yes to any of the above, this Gallery is for you!
 
-This repo contains a collection of reusable chart functions that strive to conform to standardized formats and designs based on output the BDITTO team has already created for various projects.  
+This repo contains a collection of reusable chart functions that strive to conform to standardized formats and designs based on output the BDITTO team has already created for various projects.
+
+The Gallery collection includes:
 
-The Gallery collection includes:  
-- a built-in module called Repeatable Information Charts Kit (RICK) that already contains many chart types for use out-of-the-box. Some customization is possible. The source code for all RICK charts is found in `rick.py`.   
+- a built-in module called Repeatable Information Charts Kit (RICK) that already contains many chart types for use out-of-the-box. Some customization is possible. The source code for all RICK charts is found in `rick.py`.
 - stand-alone examples beyond the scope of RICK  with source code up-front to allow easy customization as you desire
 
 All charts were developed with proper python documentation to allow the documentation for each chart to be auto-generated using [sphinx](http://www.sphinx-doc.org/en/master/).
 
 ## Contribute to the Gallery
+
 This is a work in progress and we need YOU to add to the collective knowledge! Please go to the README in the `sphinx` directory for a step-by-step guide to adding your own example to the Gallery.
 
 ## Browse the Gallery
+
 Please visit [this page](https://cityoftoronto.github.io/bdit_plotting_gallery) to browse the Gallery and associated (auto-generated) documentation. There you can also download the scripts and example notebooks for your own use.
 
 A quick summary of the charts currently available in the Gallery is listed below:
@@ -38,23 +42,23 @@ This function creates a chloropleth map.
 
 The following arguments must be passed in order for the function to run.
 
-|argument|variable type|description|
-|-----|-----|-----|
-con|SQL Connection Object|Used to additional layers from the SQL database.
-df|GeoPandas DataFrame|Data for the chloropleth map. The data must only contain 2 columns; the first column has to be the `geom` column and the second has to be the data that needs to be mapped.
-lower|int|Lower bound for the colourmap
-upper|int|Upper bound for the colourmap
-title|str|Text string for the title text
+| argument | variable type         | description                                                                                                                                                                   |
+| -------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| con      | SQL Connection Object | Used to additional layers from the SQL database.                                                                                                                              |
+| df       | GeoPandas DataFrame   | Data for the chloropleth map. The data must only contain 2 columns; the first column has to be the `geom` column and the second has to be the data that needs to be mapped. |
+| lower    | int                   | Lower bound for the colourmap                                                                                                                                                 |
+| upper    | int                   | Upper bound for the colourmap                                                                                                                                                 |
+| title    | str                   | Text string for the title text                                                                                                                                                |
 
 Additionally, there are optional arguments that can be passed to the function
 
-|argument|variable type|default|description|
-|-----|-----|-----|-----|
-subway|boolean|`False`|Flag to plot the subway network on the map. False indicates the subway network does not show up.
-island|boolean|`True`|Flag to plot the Toronto Islands as having no data. True indicates the islands are coloured the same as the Waterfront neighbourhood.
-cmap|str|`YlOrRd`|String to specify colourmap for the map.
-unit|str|`None`|Specifies if a unit should be added to the legend box. The automatic placement of the unit only works if the upper or lower are whole numbers.
-nbins|int|`2`|Number of ticks in the colourmap 
+| argument | variable type | default    | description                                                                                                                                    |
+| -------- | ------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| subway   | boolean       | `False`  | Flag to plot the subway network on the map. False indicates the subway network does not show up.                                               |
+| island   | boolean       | `True`   | Flag to plot the Toronto Islands as having no data. True indicates the islands are coloured the same as the Waterfront neighbourhood.          |
+| cmap     | str           | `YlOrRd` | String to specify colourmap for the map.                                                                                                       |
+| unit     | str           | `None`   | Specifies if a unit should be added to the legend box. The automatic placement of the unit only works if the upper or lower are whole numbers. |
+| nbins    | int           | `2`      | Number of ticks in the colourmap                                                                                                               |
 
 #### `charts.line_chart(data, ylab, xlab, **kwargs)`
 
@@ -69,38 +73,71 @@ The function defines the styling with the `props` variable, so the only manipula
 
 The following arguments must be passed in order for the function to run.
 
-|argument|variable type|description|
-|-----|-----|-----|
-data|Series or list|Data for the chart
-ylab|str|Label for the yaxis
-xlab|str|Label for the xaxis
+| argument | variable type  | description         |
+| -------- | -------------- | ------------------- |
+| data     | Series or list | Data for the chart  |
+| ylab     | str            | Label for the yaxis |
+| xlab     | str            | Label for the xaxis |
 
 Additionally, there are optional arguments that can be passed to the function
 
-|argument|variable type|default|description|
-|-----|-----|-----|-----|
-ymin|int|0|Lower bound for the yaxis
-ymax|int|The maximum value of the dataset|Upper bound for the yaxis
-yinc|int|One-third of the range of the data|Interval for the yaxis ticks
+| argument | variable type | default                            | description                  |
+| -------- | ------------- | ---------------------------------- | ---------------------------- |
+| ymin     | int           | 0                                  | Lower bound for the yaxis    |
+| ymax     | int           | The maximum value of the dataset   | Upper bound for the yaxis    |
+| yinc     | int           | One-third of the range of the data | Interval for the yaxis ticks |
 
 #### `charts.tow_chart(data, ylab, **kwargs)`
 
 Produces a 7-Day time of week chart that shows data points for each hour during one week. The xaxis is fixed to the 168 hours that produces the week, and the data must be ordered so that the first entry represents Monday at midnight.
 
 The following arguments must be passed in order for the function to run.
 
-|argument|variable type|description|
-|-----|-----|-----|
-data|Series or list|Data for the chart
-ylab|str|Label for the yaxis
+| argument | variable type  | description         |
+| -------- | -------------- | ------------------- |
+| data     | Series or list | Data for the chart  |
+| ylab     | str            | Label for the yaxis |
 
 Additionally, there are optional arguments that can be passed to the function
 
-|argument|variable type|default|description|
-|-----|-----|-----|-----|
-ymin|int|0|Lower bound for the yaxis
-ymax|int|The maximum value of the dataset|Upper bound for the yaxis
-yinc|int|One-third of the range of the data|Interval for the yaxis ticks
+| argument | variable type | default                            | description                  |
+| -------- | ------------- | ---------------------------------- | ---------------------------- |
+| ymin     | int           | 0                                  | Lower bound for the yaxis    |
+| ymax     | int           | The maximum value of the dataset   | Upper bound for the yaxis    |
+| yinc     | int           | One-third of the range of the data | Interval for the yaxis ticks |
+
+#### Helper functions
+
+| function                         | purpose                                                                                                     |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `calculate_params()`           | Finds minimum, maximum and incremental values used to determine the limits and ticks of the dependent axis. |
+| `calculate_delta()`            | Required for `calculate_params()`.                                                                        |
+| `init_fig()`                   | Initializes the figure object corresponding to the plot being made.                                         |
+| `set_plot_style()`             | Sets size, background and grid for plot.                                                                    |
+| `set_grid()`                   | Sets the grid for plot. Called by `set_plot_style()`.                                                     |
+| `set_ticks()`                  | Sets x and y axis ticks. Format depends on type of index being used.                                        |
+| `set_labels()`                 | Set the labels of the y and x axes.                                                                         |
+| `add_bar_annotations()`        | Adds annotations to charts including bars, such as the height of bars or percent changes.                   |
+| `horizontal_bar_annotations()` | Called by `add_bar_annotations()` in the case of horizontal graphs.                                       |
+| `vertical_bar_annotations()`   | Called by `add_bar_annotations()` in the case of vertical graphs.                                         |
+| `plot_line_data()`             | Used for line-type plots.                                                                                   |
+| `plot_grouped_bar_data()`      | Used for bar charts.                                                                                        |
 
 ### Stand-alone examples
-WIP..... 
+
+WIP.....
+
+### Adding to / modifying the Charts class
+
+If you would like to add a new plotting function to the `Charts` class:
+
+1. Check through the [autogenerated documentation](https://cityoftoronto.github.io/bdit_plotting_gallery/code.html) and `rick.py` to see if there is a similar pre-existing function to avoid duplication.
+2. Try to make use of the helper functions available. If there is functionality that you would like to add that is not covered by the available helper functions, consider updating them or creating new ones. Ideally, we want to avoid repetition of code throughout `rick.py` to make it easier to debug and add features later on.
+3. Make sure to include docstrings formatted according to the Sphinx gallery requirements (check [here](./sphinx/README.md#documenting-the-code)) so that they can automatically be added to the autogenerated documentation.
+4. Create some examples that can be added to the online Gallery following the instructions [here](./sphinx/README.md#graph-gallery). Ideally, do not create new examples that depend on database connections so that they are always reproducible. 
+5. Create a PR in this repo and make sure to include your new examples. Prior to merging, make sure to manually move the autogenerated contents of `sphnix/build/html` under `docs/`.
+
+If you are updating an existing function:
+
+1. Recreate the corresponding example from the Sphinx gallery and make sure that it still works.
+2. Include this in your PR.
diff --git a/sphinx/build/html/.buildinfo → docs/.buildinfo b/sphinx/build/html/.buildinfo → docs/.buildinfo
@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: c47c1904b830b46af59b9eefd0a57777
+config: 401af6414e3faf067e6215b0d0028290
 tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/docs/_downloads/07fcc19ba03226cd3d83d4e40ec44385/auto_examples_python.zip b/docs/_downloads/07fcc19ba03226cd3d83d4e40ec44385/auto_examples_python.zip