Submission Group 27: covizpy (Python)

Submitting Author: Rohit Rawat (@rrrohit1), Rong Li (@lirnish), Thomas Siu (@thomassiu), Ting Zhe Yan (@ytz) Package Name: covizpy One-Line Description of Package: Python package for easily visualizing COVID-19 statistics Repository Link: https://github.com/UBC-MDS/covizpy Version submitted: 1.0.23 Editor: Rohit Rawat (@rrrohit1), Rong Li (@lirnish), Thomas Siu (@thomassiu), Ting Zhe Yan (@ytz) Reviewer 1: Sukhleen Kaur (@sukhleen999) Reviewer 2: Philson Chan (@PhilsChan) Reviewer 3: Kingslin Lv (@Kingslin0810)

Description

Include a brief paragraph describing what your package does:

This Python package provides easy access to COVID-19 data from the Our World in Data website. It includes functions that could easily generate relevant COVID-19 charts and summaries.

Scope

Please indicate which category or categories this package falls under:
- [x] Data retrieval
- [ ] Data extraction
- [ ] Data munging
- [ ] Data deposition
- [ ] Reproducibility
- [ ] Geospatial
- [ ] Education
- [x] Data visualization*

* Please fill out a pre-submission inquiry before submitting a data visualization package. For more info, see notes on categories of our guidebook.

Explain how the and why the package falls under these categories (briefly, 1-2 sentences):

Our package extracts covid data from an online source, and visualizes the data using bar plot and line plot.
Who is the target audience and what are scientific applications of this package?

The target audience is the researchers, journalists, and data analysts who need to understand and communicate COVID-19 related issues.
Are there other Python packages that accomplish the same thing? If so, how does yours differ?

There is an existing package covid19pandas that allows users to download and generate Covid-19 charts. However, we utilized another data source that includes different metrics, and we also provide simpler functions that allow users to answer questions regarding the COVID-19 pandemic as quickly as possible.
If you made a pre-submission enquiry, please paste the link to the corresponding issue, forum post, or other discussion, or @tag the editor you contacted:

Not applicable

Technical checks

For details about the pyOpenSci packaging requirements, see our packaging guide. Confirm each of the following by checking the box. This package:

[x] does not violate the Terms of Service of any service it interacts with.
[x] has an OSI approved license.
[x] contains a README with instructions for installing the development version.
[x] includes documentation with examples for all functions.
[x] contains a vignette with examples of its essential functions and uses.
[x] has a test suite.
[x] has continuous integration, such as Travis CI, AppVeyor, CircleCI, and/or others.

Publication options

[ ] Do you wish to automatically submit to the Journal of Open Source Software? If so:

JOSS Checks

- [ ] The package has an **obvious research application** according to JOSS's definition in their [submission requirements][JossSubmissionRequirements]. Be aware that completing the pyOpenSci review process **does not** guarantee acceptance to JOSS. Be sure to read their submission requirements (linked above) if you are interested in submitting to JOSS. - [ ] The package is not a "minor utility" as defined by JOSS's [submission requirements][JossSubmissionRequirements]: "Minor ‘utility’ packages, including ‘thin’ API clients, are not acceptable." pyOpenSci welcomes these packages under "Data Retrieval", but JOSS has slightly different criteria. - [ ] The package contains a `paper.md` matching [JOSS's requirements][JossPaperRequirements] with a high-level description in the package root or in `inst/`. - [ ] The package is deposited in a long-term repository with the DOI: *Note: Do not submit your package separately to JOSS*

Are you OK with Reviewers Submitting Issues and/or pull requests to your Repo Directly?

This option will allow reviewers to open smaller issues that can then be linked to PR's rather than submitting a more dense text based review. It will also allow you to demonstrate addressing the issue via PR links.

[x] Yes I am OK with reviewers submitting requested changes as issues to my repo. Reviewers will then link to the issues in their submitted review.

Code of conduct

[x] I agree to abide by pyOpenSci's Code of Conduct during the review process and in maintaining my package should it be accepted.

P.S. *Have feedback/comments about our review process? Leave a comment here

Editor and Review Templates

Editor and review templates can be found here

Package Review

Please check off boxes as applicable, and elaborate in comments below. Your review is not limited to these topics, as described in the reviewer guide

[x] As the reviewer I confirm that there are no conflicts of interest for me to review this work (If you are unsure whether you are in conflict, please speak to your editor before starting your review).

Documentation

The package includes all the following forms of documentation:

[x] A statement of need clearly stating problems the software is designed to solve and its target audience in README
[x] Installation instructions: for the development version of package and any non-standard dependencies in README
[ ] Vignette(s) demonstrating major functionality that runs successfully locally
[x] Function Documentation: for all user-facing functions
[x] Examples for all user-facing functions
[x] Community guidelines including contribution guidelines in the README or CONTRIBUTING.
[ ] Metadata including author(s), author e-mail(s), a url, and any other relevant metadata e.g., in a setup.py file or elsewhere.

Readme requirements The package meets the readme requirements below:

[x] Package has a README.md file in the root directory.

The README should include, from top to bottom:

[x] The package name
[x] Badges for continuous integration and test coverage, a repostatus.org badge, and any other badges. If the README has many more badges, you might want to consider using a table for badges: see this example. Such a table should be more wide than high. (Note that the badge for pyOpenSci peer-review will be provided upon acceptance.)
[ ] Short description of goals of package, with descriptive links to all vignettes (rendered, i.e. readable, cf the documentation website section) unless the package is small and there’s only one vignette repeating the README.
[x] Installation instructions
[x] Any additional setup required (authentication tokens, etc)
[x] Brief demonstration usage
[ ] Direction to more detailed documentation (e.g. your documentation files or website).
[x] If applicable, how the package compares to other similar packages and/or how it relates to other packages
[x] Citation information

Usability

Reviewers are encouraged to submit suggestions (or pull requests) that will improve the usability of the package as a whole. Package structure should follow general community best-practices. In general please consider:

[x] The documentation is easy to find and understand
[x] The need for the package is clear
[x] All functions have documentation and associated examples for use

Functionality

[x] Installation: Installation succeeds as documented.
[ ] Functionality: Any functional claims of the software been confirmed.
[ ] Performance: Any performance claims of the software been confirmed.
[x] Automated tests: Tests cover essential functions of the package and a reasonable range of inputs and conditions. All tests pass on the local machine.
[x] Continuous Integration: Has continuous integration, such as Travis CI, AppVeyor, CircleCI, and/or others.
[x] Packaging guidelines: The package conforms to the pyOpenSci packaging guidelines.

For packages co-submitting to JOSS

[ ] The package has an obvious research application according to JOSS's definition in their submission requirements.

Note: Be sure to check this carefully, as JOSS's submission requirements and scope differ from pyOpenSci's in terms of what types of packages are accepted.

The package contains a paper.md matching JOSS's requirements with:

[ ] A short summary describing the high-level functionality of the software
[ ] Authors: A list of authors with their affiliations
[ ] A statement of need clearly stating problems the software is designed to solve and its target audience.
[ ] References: with DOIs for all those that have one (e.g. papers, datasets, software).

Final approval (post-review)

[ ] The author has responded to my review and made changes to my satisfaction. I recommend approving this package.

Estimated hours spent reviewing:

2.5 hours

Review Comments

Congratulations group 27 and well done on your covizpy package! It's a well-organized and user-friendly package for anyone with basic python programming knowledge to quickly understand the covid-19 data summaries. Overall, I think your project is well designed. Some highlights are the package repo is clearly structured, mostly everything required being included, easy to follow, and the written documentation being very well organized which is simple to follow.

I have a few recommendations for improvement:

Might consider adding exception handing for dates prior to “2020-01-01” when the covid data was not generated for the function get_data.
The input argument location in the function plot_summary (var input), plot_spec, and plot_metric are optional but they are built based on whatever input is entered in the function get_data. Maybe this needs to be clearly documented in the docstring, and so we don't run into below unclear presentation.
The README file looks good, but I think it would be better to explicitly list a direct weblink to your documentation as opposed to just include the docs badge.
A nitpicking thing in your README should the function get_data be always the first to run prior to others? Like the function is listed in the third under Features.
Your example doesn’t have output plots exhibited which makes audiences hard to understand your functions. I haven’t tested yet but alt.renderers.enable('mimetype') might save a backup image of each Altair plot as a PNG so that we can see the plots in output.
Your documentation page has two repetitive logos in the front page which are distracting to your contents for presentation. I suggest you keep one logo.

Other than above minor suggestions, I feel that the code is in a good state; again, great work team, I really enjoyed reading through this. Thank you.

Package Review

Please check off boxes as applicable, and elaborate in comments below. Your review is not limited to these topics, as described in the reviewer guide

[x] As the reviewer I confirm that there are no conflicts of interest for me to review this work (If you are unsure whether you are in conflict, please speak to your editor before starting your review).

Documentation

The package includes all the following forms of documentation:

[x] A statement of need clearly stating problems the software is designed to solve and its target audience in README
[x] Installation instructions: for the development version of package and any non-standard dependencies in README
[ ] Vignette(s) demonstrating major functionality that runs successfully locally
[x] Function Documentation: for all user-facing functions
[x] Examples for all user-facing functions
[x] Community guidelines including contribution guidelines in the README or CONTRIBUTING.
[ ] Metadata including author(s), author e-mail(s), a url, and any other relevant metadata e.g., in a setup.py file or elsewhere.

Readme requirements The package meets the readme requirements below:

[x] Package has a README.md file in the root directory.

The README should include, from top to bottom:

[x] The package name
[x] Badges for continuous integration and test coverage, a repostatus.org badge, and any other badges. If the README has many more badges, you might want to consider using a table for badges: see this example. Such a table should be more wide than high. (Note that the badge for pyOpenSci peer-review will be provided upon acceptance.)
[x] Short description of goals of package, with descriptive links to all vignettes (rendered, i.e. readable, cf the documentation website section) unless the package is small and there’s only one vignette repeating the README.
[x] Installation instructions
[ ] Any additional setup required (authentication tokens, etc)
[x] Brief demonstration usage
[ ] Direction to more detailed documentation (e.g. your documentation files or website).
[x] If applicable, how the package compares to other similar packages and/or how it relates to other packages
[ ] Citation information

Usability

[x] The documentation is easy to find and understand
[x] The need for the package is clear
[ ] All functions have documentation and associated examples for use

Functionality

[x] Installation: Installation succeeds as documented.
[x] Functionality: Any functional claims of the software been confirmed.
[x] Performance: Any performance claims of the software been confirmed.
[x] Automated tests: Tests cover essential functions of the package and a reasonable range of inputs and conditions. All tests pass on the local machine.
[x] Continuous Integration: Has continuous integration, such as Travis CI, AppVeyor, CircleCI, and/or others.
[x] Packaging guidelines: The package conforms to the pyOpenSci packaging guidelines.

For packages co-submitting to JOSS

[ ] The package has an obvious research application according to JOSS's definition in their submission requirements.

Note: Be sure to check this carefully, as JOSS's submission requirements and scope differ from pyOpenSci's in terms of what types of packages are accepted.

The package contains a paper.md matching JOSS's requirements with:

[ ] A short summary describing the high-level functionality of the software
[ ] Authors: A list of authors with their affiliations
[ ] A statement of need clearly stating problems the software is designed to solve and its target audience.
[ ] References: with DOIs for all those that have one (e.g. papers, datasets, software).

Final approval (post-review)

[ ] The author has responded to my review and made changes to my satisfaction. I recommend approving this package.

Estimated hours spent reviewing: 1.5 hours

Review Comments

The package looks very neat and cool in general. The documentations are clear and easy to follow, in which users with little python programming skills could use this handy visualization tool without any barrier. The pipeline for data retreival and visualization are seamless, and the charts could present the data clearly.

Here are some recommendations and suggestions that you might work on for the future:

The function interface could be more unified. Functions plot_spec and plot_summary both have df as their primary input, while plot_metric does not. This might confused the users a bit, and I suggest that all the plotting functions could consider using similar function interface and keyword arguments so that the user experience would be smoother.
Similar to the issue above, the behaviour of some default arguments are different among the functions. For example, the default behaviour of date_from and date_to for plot_metric are setting it to two actual date, while the other functions set the range to 7 days prior to the current date.
The functions could be more flexible with different input format. For instance, as the output of get_data is a pandas dataframe, where its date column is in datatype of pandas.Timestamp, you might consider support such datatype as input for arguments like date_from and date_to. I believe it could enhance the usability of the package when users want to play around with the data set.
For the function plot_summary, the argument fun only accept string object. However as a user, I don't know what could I input for the parameter apart from "sum". I suggest that you might put a list of possible values for this particular argument in the documentation. It is also suggested that a function or lambda could be passed to the argument so that users could defined their own aggregate functions.
The README file shall include link to the readthedocs documentation.
In the documentation, plot_metric do not have an example section. I think adding the section could make the whole package more unified and easier for users to follow.

Apart from the minor concerns stated above, the package in general is already so comprehensive and ready-to-use. I really appreciate that you could make the data visualization much easier for non-tech people with this package. Thank you!

Package Review

Please check off boxes as applicable, and elaborate in comments below. Your review is not limited to these topics, as described in the reviewer guide

[x] As the reviewer I confirm that there are no conflicts of interest for me to review this work (If you are unsure whether you are in conflict, please speak to your editor before starting your review).

Documentation

The package includes all the following forms of documentation:

[x] A statement of need clearly stating problems the software is designed to solve and its target audience in README
[x] Installation instructions: for the development version of package and any non-standard dependencies in README
[ ] Vignette(s) demonstrating major functionality that runs successfully locally
[x] Function Documentation: for all user-facing functions
[x] Examples for all user-facing functions
[x] Community guidelines including contribution guidelines in the README or CONTRIBUTING.
[ ] Metadata including author(s), author e-mail(s), a url, and any other relevant metadata e.g., in a setup.py file or elsewhere.

Readme requirements The package meets the readme requirements below:

[x] Package has a README.md file in the root directory.

The README should include, from top to bottom:

[x] The package name
[x] Badges for continuous integration and test coverage, a repostatus.org badge, and any other badges. If the README has many more badges, you might want to consider using a table for badges: see this example. Such a table should be more wide than high. (Note that the badge for pyOpenSci peer-review will be provided upon acceptance.)
[x] Short description of goals of package, with descriptive links to all vignettes (rendered, i.e. readable, cf the documentation website section) unless the package is small and there’s only one vignette repeating the README.
[x] Installation instructions
[ ] Any additional setup required (authentication tokens, etc)
[x] Brief demonstration usage
[x] Direction to more detailed documentation (e.g. your documentation files or website).
[x] If applicable, how the package compares to other similar packages and/or how it relates to other packages
[ ] Citation information

Usability

[x] The documentation is easy to find and understand
[x] The need for the package is clear
[x] All functions have documentation and associated examples for use

Functionality

[x] Installation: Installation succeeds as documented.
[ ] Functionality: Any functional claims of the software been confirmed.
[x] Performance: Any performance claims of the software been confirmed.
[x] Automated tests: Tests cover essential functions of the package and a reasonable range of inputs and conditions. All tests pass on the local machine.
[ ] Continuous Integration: Has continuous integration, such as Travis CI, AppVeyor, CircleCI, and/or others.
[x] Packaging guidelines: The package conforms to the pyOpenSci packaging guidelines.

For packages co-submitting to JOSS

[ ] The package has an obvious research application according to JOSS's definition in their submission requirements.

Note: Be sure to check this carefully, as JOSS's submission requirements and scope differ from pyOpenSci's in terms of what types of packages are accepted.

The package contains a paper.md matching JOSS's requirements with:

[ ] A short summary describing the high-level functionality of the software
[ ] Authors: A list of authors with their affiliations
[ ] A statement of need clearly stating problems the software is designed to solve and its target audience.
[ ] References: with DOIs for all those that have one (e.g. papers, datasets, software).

Final approval (post-review)

[ ] The author has responded to my review and made changes to my satisfaction. I recommend approving this package.

Estimated hours spent reviewing: 2 hours

Review Comments

Great job team! The package seems extremely helpful for beginners who wish to visualize the trend of Covid-19 cases and draw meaningful conclusions. I found the installation and the functions extremely smooth to work with. The README is also very well structured.

For further improvement, I suggest the following changes:

The function descriptions in the README file can include the input variables and their data types so that users have a clear idea of the requirements for the functions.
The plot_spec function does not check for the correctness of the location name. I tried to input the country 'USA' (correct input is 'United States') but the plot does not throw an error. It just does not consider the incorrect input location.
The functions can be more flexible in terms of input data types. For example, you could accept more date formats instead of limiting the input type to YYYY-MM-DD.
Lastly, to amp up the 'wow' factor, you could make the plots interactive. I personally find interactive plots very fascinating and would love to use packages that offer this functionality.

In summary, I really liked the inspiration of the package and would definitely be using it to keep abreast of the Covid-19 cases.

UBC-MDS / software-review-2022