Skip to content

Commit 4370e2d

Browse files
committed
Add resizing option to trim_img() and pad_img()
1 parent 984f29b commit 4370e2d

File tree

7 files changed

+126
-74
lines changed

7 files changed

+126
-74
lines changed

README.md

Lines changed: 81 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -2,30 +2,53 @@
22

33
This is a Python module that contains some useful data visualization tools.
44

5-
## Table of contents
5+
**Table of contents:**
6+
7+
- [Python plotting utilities: `plot_utils`](#python-plotting-utilities-plot_utils)
8+
- [1. Installation](#1-installation)
9+
- [Note:](#note)
10+
- [2. API documentations](#2-api-documentations)
11+
- [3. Current functionalities](#3-current-functionalities)
12+
- [3.1. Visualizing one column of data](#31-visualizing-one-column-of-data)
13+
- [3.2. Visualizing two columns of data (\[example\])](#32-visualizing-two-columns-of-data-example)
14+
- [3.3. Visualizing multiple columns of data](#33-visualizing-multiple-columns-of-data)
15+
- [3.4. Map plotting](#34-map-plotting)
16+
- [3.5. Time series plotting](#35-time-series-plotting)
17+
- [3.6. Miscellaneous](#36-miscellaneous)
18+
- [4. Gallery](#4-gallery)
19+
- [4.1. One column of data](#41-one-column-of-data)
20+
- [4.2. Two columns of data](#42-two-columns-of-data)
21+
- [4.3. Multiple columns of data](#43-multiple-columns-of-data)
22+
- [4.3.1. 3D histograms](#431-3d-histograms)
23+
- [4.3.2. Multi-histogram plots](#432-multi-histogram-plots)
24+
- [4.3.3. Violin plots](#433-violin-plots)
25+
- [4.3.4. Correlation matrix](#434-correlation-matrix)
26+
- [4.3.5. Count missing values](#435-count-missing-values)
27+
- [4.4. Choropleth maps (a.k.a., "heat maps")](#44-choropleth-maps-aka-heat-maps)
28+
- [4.4.1. State-level choropleth maps for the US](#441-state-level-choropleth-maps-for-the-us)
29+
- [4.4.2. County-level choropleth maps for the US](#442-county-level-choropleth-maps-for-the-us)
30+
- [4.5. Time series plotting](#45-time-series-plotting)
31+
- [4.5.1. Single time series](#451-single-time-series)
32+
- [4.5.2. Multiple time series](#452-multiple-time-series)
33+
- [4.6. Miscellaneous](#46-miscellaneous)
34+
- [4.6.1. `get_colors()` function](#461-get_colors-function)
35+
- [4.6.2. `get_linespecs()` function](#462-get_linespecs-function)
36+
- [4.6.3. Plot with error bounds](#463-plot-with-error-bounds)
37+
- [4.6.4. Visualize cross-validation scores](#464-visualize-cross-validation-scores)
38+
- [5. Dependencies](#5-dependencies)
39+
- [6. Testing](#6-testing)
40+
- [7. Aesthetics](#7-aesthetics)
41+
- [8. References](#8-references)
42+
- [9. Copyright and license](#9-copyright-and-license)
43+
44+
45+
## 1. Installation
46+
47+
In the terminal, run the following command:
648

7-
* [Installation](#installation)
8-
* [API documentations](#api-documentations)
9-
* [Current functionalities](#current-functionalities)
10-
* [Gallery](#gallery)
11-
- [One column of data](#1-one-column-of-data)
12-
- [Two columns of data](#2-two-columns-of-data)
13-
- [Multiple columns of data](#3-multiple-columns-of-data)
14-
- [Choropleth maps (a.k.a., "heat maps")](#4-choropleth-maps-aka-heat-maps)
15-
- [Time series plotting](#5-time-series-plotting-1)
16-
- [Miscellaneous](#6-miscellaneous-1)
17-
* [Dependencies](#dependencies)
18-
* [Testing](#testing)
19-
* [Aesthetics](#aesthetics)
20-
* [References](#references)
21-
* [Copyright and license](#copyright-and-license)
22-
23-
24-
## Installation
25-
26-
In a command-line terminal, execute the following command:
27-
28-
`pip install git+https://github.com/jsh9/[email protected]`
49+
```
50+
pip install plot-utils
51+
```
2952

3053
##### Note:
3154

@@ -36,28 +59,28 @@ If you run into the following issue on Mac OS X (or macOS) when importing `plot_
3659
please follow this solution to fix the issue: https://stackoverflow.com/a/21789908/8892243
3760

3861

39-
## API documentations
62+
## 2. API documentations
4063

4164
All API documentations are on: https://python-plot-utils.readthedocs.io/en/stable/index.html.
4265

4366

44-
## Current functionalities
67+
## 3. Current functionalities
4568

4669
Current functionalities include (for full list, use `print(plot_utils.__doc__)`):
4770

48-
#### 1. Visualizing one column of data
71+
### 3.1. Visualizing one column of data
4972

5073
- **Pie chart**: proportions of distinct values in an array, more convenient than matplotlib's `pie()` function [[doc](https://python-plot-utils.readthedocs.io/en/stable/api_docs/pie_chart.html)], [[example](./examples/Pie_chart_example.ipynb)]
5174
- **Discrete histogram**: counts of distinct values in an array [[doc](https://python-plot-utils.readthedocs.io/en/stable/api_docs/discrete_histogram.html)], [[example](./examples/Discrete_histogram_example.ipynb)]
5275

53-
#### 2. Visualizing two columns of data ([[example](./examples/Two_columns_of_data_example.ipynb)])
76+
### 3.2. Visualizing two columns of data ([[example](./examples/Two_columns_of_data_example.ipynb)])
5477

5578
- **"Bin-and-mean" plot**: for two continuous variables [[doc](https://python-plot-utils.readthedocs.io/en/stable/api_docs/bin_and_mean.html)]
5679
- **Category mean**: for a categorical variable and a continuous variable [[doc](https://python-plot-utils.readthedocs.io/en/stable/api_docs/category_means.html)]
5780
- **Positive rate**: for a categorical variable and a binary categorical variable [[doc](https://python-plot-utils.readthedocs.io/en/stable/api_docs/positive_rate.html)]
5881
- **Contingency table**: for two categorical variables [[doc](https://python-plot-utils.readthedocs.io/en/stable/api_docs/contingency_table.html)]
5982

60-
#### 3. Visualizing multiple columns of data
83+
### 3.3. Visualizing multiple columns of data
6184

6285
+ **3D histograms**: distributions of multiple variables [[doc](https://python-plot-utils.readthedocs.io/en/stable/api_docs/3d_histograms.html)], [[example](./examples/3D_histograms_example.ipynb)]
6386
+ **Multiple histograms**: distribution of multiple variables [[doc](https://python-plot-utils.readthedocs.io/en/stable/api_docs/hist_multi.html)], [[example](./examples/Violin_plot_and_hist_multi_example.ipynb)]
@@ -67,18 +90,18 @@ Current functionalities include (for full list, use `print(plot_utils.__doc__)`)
6790
+ **Count missing values**: how many missing values are there in each column of the dataset [[doc](https://python-plot-utils.readthedocs.io/en/stable/api_docs/missing_values.html)], [[example](./examples/Missing_value_count_example.ipynb)]
6891

6992

70-
#### 4. Map plotting
93+
### 3.4. Map plotting
7194

7295
+ **Choropleth map** (a.k.a., "heat map") of the United States, on both the state and county level [[doc](https://python-plot-utils.readthedocs.io/en/stable/api_docs/choropleth_map.html)], [[example](./examples/Choropleth_map_example.ipynb)]
7396

7497

75-
#### 5. Time series plotting
98+
### 3.5. Time series plotting
7699

77100
- **Plot single time series**: [[doc](https://python-plot-utils.readthedocs.io/en/stable/api_docs/plot_time_series.html)], [[example](./examples/Plot_time_series_example.ipynb)]
78101
- **Plot multiple time series**: [[doc](https://python-plot-utils.readthedocs.io/en/stable/api_docs/plot_multiple_timeseries.html)], [[example](./examples/Plot_time_series_example.ipynb)]
79102
- **Fill time series with error bounds**: [[doc](https://python-plot-utils.readthedocs.io/en/stable/api_docs/fill_timeseries.html)], [[example](./examples/Plot_time_series_example.ipynb)]
80103

81-
#### 6. Miscellaneous
104+
### 3.6. Miscellaneous
82105

83106
+ A **get_colors()** function that conveniently queries different color palettes [[doc](https://python-plot-utils.readthedocs.io/en/stable/api_docs/get_colors.html)], [[example](./examples/Color_and_linespec_examples.ipynb)]
84107
+ A **get_linespecs()** function that generates distinct color/linestyle/linewidth combinations for plotting many lines together [[doc](https://python-plot-utils.readthedocs.io/en/stable/api_docs/get_linespecs.html)], [[example](./examples/Color_and_linespec_examples.ipynb)]
@@ -90,9 +113,9 @@ Current functionalities include (for full list, use `print(plot_utils.__doc__)`)
90113
+ **visualize_cv_scores()**, which visualizes cross-validation training/evaluation scores [[doc](https://python-plot-utils.readthedocs.io/en/stable/api_docs/visualize_cv_scores.html)], [[example](./examples/Visualize_cross_validation_results.ipynb)]
91114

92115

93-
## Gallery
116+
## 4. Gallery
94117

95-
### 1. One column of data
118+
### 4.1. One column of data
96119

97120
Using the "Titanic dataset" as example:
98121

@@ -112,7 +135,7 @@ Discrete histogram: [[doc](https://python-plot-utils.readthedocs.io/en/stable/ap
112135

113136

114137

115-
### 2. Two columns of data
138+
### 4.2. Two columns of data
116139

117140
Using the "Titanic dataset" as example:
118141

@@ -139,9 +162,9 @@ pu.contingency_table(titanic['ticket_class'], titanic['embarked'], dropna=True,
139162

140163

141164

142-
### 3. Multiple columns of data
165+
### 4.3. Multiple columns of data
143166

144-
#### 3.1. 3D histograms
167+
#### 4.3.1. 3D histograms
145168

146169
Useful for comparing multiple distributions:
147170

@@ -155,7 +178,7 @@ pu.histogram3d(iris[['petal_width', 'petal_length', 'sepal_width', 'sepal_length
155178
![histogram_3d](./examples/gallery/histogram_3d.png)
156179

157180

158-
#### 3.2. Multi-histogram plots
181+
#### 4.3.2. Multi-histogram plots
159182

160183
Another useful tool to compare multiple distributions:
161184

@@ -167,7 +190,7 @@ pu.hist_multi(iris[['sepal_length', 'sepal_width', 'petal_length', 'petal_width'
167190

168191
![](./examples/gallery/multi_histogram.png)
169192

170-
#### 3.3. Violin plots
193+
#### 4.3.3. Violin plots
171194

172195
To compare multiple distributions:
173196

@@ -181,7 +204,7 @@ pu.violin_plot(iris[['petal_width', 'petal_length', 'sepal_width', 'sepal_length
181204

182205

183206

184-
#### 3.4. Correlation matrix
207+
#### 4.3.4. Correlation matrix
185208

186209
```python
187210
iris = pd.read_csv('./examples/datasets/iris.csv')
@@ -198,7 +221,7 @@ The first figure shows the correlation (or "sample covariance") between each co
198221

199222

200223

201-
#### 3.5. Count missing values
224+
#### 4.3.5. Count missing values
202225

203226
To see how much data is missing in each column of a data set:
204227

@@ -215,9 +238,9 @@ Each bar corresponds to a column in `titanic`, and the numbers atop are the miss
215238

216239

217240

218-
### 4. Choropleth maps (a.k.a., "heat maps")
241+
### 4.4. Choropleth maps (a.k.a., "heat maps")
219242

220-
#### 4.1. State-level choropleth maps for the US
243+
#### 4.4.1. State-level choropleth maps for the US
221244

222245
```python
223246
pu.choropleth_map_state(state_level_data) # `state_level_data`: dict, pandas.DataFrame, or pandas.Series
@@ -227,7 +250,7 @@ pu.choropleth_map_state(state_level_data) # `state_level_data`: dict, pandas.Da
227250

228251
![choropleth_map_state](./examples/gallery/choropleth_map_state.png)
229252

230-
#### 4.2. County-level choropleth maps for the US
253+
#### 4.4.2. County-level choropleth maps for the US
231254

232255
```python
233256
pu.choropleth_map_county(county_level_data) # `county_level_data`: dict, pandas.DataFrame, or pandas.Series
@@ -239,9 +262,9 @@ pu.choropleth_map_county(county_level_data) # `county_level_data`: dict, pandas
239262

240263

241264

242-
### 5. Time series plotting
265+
### 4.5. Time series plotting
243266

244-
#### 5.1. Single time series
267+
#### 4.5.1. Single time series
245268

246269
```python
247270
df = pd.read_csv('./examples/datasets/Unemployment_rate_1976-2017.csv', index_col=0)
@@ -252,7 +275,7 @@ pu.plot_timeseries(df['CA'], ylabel='Unit: %', title='Unemployment rate, Califor
252275

253276
![](./examples/gallery/time_series_single.png)
254277

255-
#### 5.2. Multiple time series
278+
#### 4.5.2. Multiple time series
256279

257280
```python
258281
pu.plot_multiple_timeseries(df, ylabel='Unemployment rate [%]', ncol_legend=10)
@@ -264,9 +287,9 @@ pu.plot_multiple_timeseries(df, ylabel='Unemployment rate [%]', ncol_legend=10)
264287

265288

266289

267-
### 6. Miscellaneous
290+
### 4.6. Miscellaneous
268291

269-
#### 6.1. `get_colors()` function
292+
#### 4.6.1. `get_colors()` function
270293

271294
Easy querying of distinguishable color palettes.
272295

@@ -279,7 +302,7 @@ pu.Multiple_Colors(colors).show() # show colors as a palette
279302

280303
![](./examples/gallery/get_colors.png)
281304

282-
#### 6.2. `get_linespecs()` function
305+
#### 4.6.2. `get_linespecs()` function
283306

284307
Easy querying of distinguishable line specs.
285308

@@ -294,7 +317,7 @@ pu.linespecs_demo(line_specs)
294317

295318
![](./examples/gallery/get_linespecs.png)
296319

297-
#### 6.3. Plot with error bounds
320+
#### 4.6.3. Plot with error bounds
298321

299322
Plots data and error bounds on the same graph.
300323

@@ -306,7 +329,7 @@ pu.plot_with_error_bounds(x, y, y_upper_bound, y_lower_bound)
306329

307330
![](./examples/gallery/error_bounds.png)
308331

309-
#### 6.4. Visualize cross-validation scores
332+
#### 4.6.4. Visualize cross-validation scores
310333

311334
```python
312335
pu.visualize_cv_scores(n_folds=4, cv_scores=[0.675, 0.702, 0.689, 0.653], holdout_score=0.6745);
@@ -315,7 +338,7 @@ pu.visualize_cv_scores(n_folds=4, cv_scores=[0.675, 0.702, 0.689, 0.653], holdou
315338

316339
![](./examples/gallery/visualize_cv_scores.png)
317340

318-
## Dependencies
341+
## 5. Dependencies
319342

320343
+ Python 2.7 or 3.5+
321344
+ matplotlib 1.5.0+, or 2.0.0+ (Version 2.1.0+ is strongly recommended.)
@@ -327,27 +350,27 @@ pu.visualize_cv_scores(n_folds=4, cv_scores=[0.675, 0.702, 0.689, 0.653], holdou
327350
+ PIL (only if you want to use `trim_img()` or `pad_img()`)
328351

329352

330-
## Testing
353+
## 6. Testing
331354

332355
To test `plot_utils`, run the ipython notebooks in the `examples` folder.
333356

334357

335-
## Aesthetics
358+
## 7. Aesthetics
336359

337360
The aesthetics of of the `plot_utils` module are matplotlib-styled by default, but it doesn't mean that you can't use your favorite styles in seaborn or ggplot2.
338361

339362
Unlike some plotting packages that enforces their own styles and restrict users from customizing, users of this module can adjust the figure styles freely: either from within matplotlib (https://matplotlib.org/devdocs/gallery/style_sheets/style_sheets_reference.html), or `import seaborn` and let seaborn take care of everything.
340363

341364

342365

343-
## References
366+
## 8. References
344367

345368
I did not built every function of this module entirely from scratch. I documented the sources that I referenced in the documentation of the corresponding functions.
346369

347370

348371

349-
## Copyright and license
372+
## 9. Copyright and license
350373

351-
(c) 2017-2022, Jian Shi
374+
(c) 2017-2023, jsh9
352375

353-
License: GPL v3.0
376+
License: [GPL v3.0](./LICENSE)

doc/source/conf.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
author = 'Jian Shi'
2323

2424
# The full version, including alpha/beta/rc tags
25-
release = 'v0.6.12'
25+
release = 'v0.6.13'
2626

2727

2828
# -- General configuration ---------------------------------------------------

doc/source/index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Recommended method (in the terminal or command window, execute the following com
1515

1616
.. code-block:: bash
1717
18-
pip install git+https://github.com/jsh9/[email protected].12
18+
pip install git+https://github.com/jsh9/[email protected].13
1919
2020
For other installation alternatives, see the `installation guide <installation_guide.html>`_.
2121

doc/source/installation_guide.rst

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,19 +6,14 @@ Installation guide
66

77
.. code-block:: bash
88
9-
pip install git+https://github.com/jsh9/python-plot-utils
9+
pip install plot-utils
1010
1111
2. Install a specific release
1212
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1313

1414
.. code-block:: bash
1515
16-
pip install git+https://github.com/jsh9/[email protected]
17-
18-
3. The portable way
19-
^^^^^^^^^^^^^^^^^^^
20-
21-
Just download this repository, and you can put ``plot_utils.py`` anywhere within your Python search path.
16+
pip install git+https://github.com/jsh9/[email protected]
2217
2318
Note
2419
^^^^

plot_utils/__init__.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
__version__ = 'v0.6.12'
1+
__version__ = 'v0.6.13'
22

33
from .helper import *
44
from .helper import _find_axes_lim

0 commit comments

Comments
 (0)