Submission Group 30: chemcalculator (Python)

[Kingslin0810]

Submitting Authors:

• Kingslin Lv (@Kingslin0810 )
• Joyce Wang (@jo4356)
• Allyson Stoll (@datallurgy)

Package Name: chemcalculator One-Line Description of Package: chemcalculator is a python package useful for chemistry for purpose of calculating chemical formular mass in g/mol. Repository Link: chemcalculator Version submitted: 1.0.1 Editor: Florencia D'Andrea (@flor14)

Description

Python package to calculate chemical formula or atomic mass (g/mol), convert moles to grams and grams to moles, and calculate percentage mass for chemical or atom of interest

• compute_mass: This function calculates the mass of the atoms or chemical formula for the input chemical formula.

• moles_grams_converter: This function converts moles to grams and convert grams to moles.

• percent_mass: This function calculates percentage mass for the desired atom or molecule.

  Scope

• Please indicate which category or categories this package falls under:

  • [ ] Data retrieval
  • [ ] Data extraction
  • [ ] Data munging
  • [ ] Data deposition
  • [ ] Reproducibility
  • [ ] Geospatial
  • [ ] Education
  • [ ] 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):

Other category: scientific software wrappers . The package chemcalculator converts between moles and grams, helping researchers or data scientist to perform this widely used conversions fast and without errors.

• Who is the target audience and what are scientific applications of this package?

Data scientists or researchers working with chemistry data.

Are there other Python packages that accomplish the same thing? If so, how does yours differ?

No. This package of basic chemistry calculations is meant to supplement an existing package, ChemPy, which already handles complex calculations for primarily physical/inorganic/analytical chemistry consisting of, but not limited to, the following:

• Solver for equilibria (including multiphase systems)
• Numerical integration routines for chemical kinetics (ODE solver front-end)
• Integrated rate expressions (and convenience fitting routines)
• Relations in Physical chemistry
• Debye-Hückel expressions
• Arrhenius equation
• Einstein-Smoluchowski equation
• Properties, such as : water density as function of temperature, water permittivity as function of temperature and pressure, and water diffusivity as function of temperature

• 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:

  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. 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: "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 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](https://www.pyopensci.org/contributing-guide/open-source-software-peer-review/code-of-conduct.html?highlight=code%20conduct) 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](https://github.com/pyOpenSci/governance/issues/8) ## Editor and Review Templates [Editor and review templates can be found here](https://www.pyopensci.org/contributing-guide/appendices/templates.html)

[khbunyan]

Package Review

• [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
• [ ] 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
• [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
• [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)

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

Estimated hours spent reviewing:

2

Review Comments

Hi Group 30, well done on your package! It's clean, concise, and is very practical for chemists. Overall, I think your project is really well put together. Some particular highlights are; everything being clearly organized, mostly everything required being included and easy to find, and the written documentation being very well organized so it's simple to follow.

I have a few notes for some areas that I think you could explore for improvement:

1. In your "Usage" section, there is a small typo in the example for percent_mass. Right now it says the number 0 instead of the letter O for the second input: percent_mass("H2O", "0"). I think you intended to use the letter O here.
2. I think moles_grams_converter() might actually be performing the reverse of what is intended here.
   • Based on your "read the docs" your function should be converting grams to moles, but it's actually converting moles to grams in the above example.
   • The docstring for this function tells me that the "convert_to" variable is what the function is converting my "mass" value to, ie the final units of the output value. So, if we input 0.05555 (assuming that's grams) and use "moles" as the convert_to input, it should result in 0.0030835 mols, as 0.05555 grams is equivalent to 0.0030835 mols. However the result is 1.00.
   • This would be correct if we were converting from moles not converting to moles, as 0.05555 moles = 1.00 gram.
   • The translation code is working properly, but convert_to should be convert_from.
3. A few small grammatical errors in the README description:
   • "chemcalculator is a python package useful for chemistry for THE purpose of calculating chemical formular mass in g/mol."
   • "Another property of Avogadro’s number is that the mass of one mole of a substance is equal to that substance’s molecular weight." Avogadro’s number is not defined - is this a synonym for mols? I'm not a chemist so I could be missing something that is common knowledge here.
4. The badges for codecov and docs look great, but there is no ci-cd badge in the README. Please add so there is confirmation of the workflow's passing without having to go into the actions tab.
5. I would suggest removing branches that are no longer needed, such as "ci-cd" and "update_README". Keeps the repo cleaner.

In addition to those 5 comments, there are some missed check boxes above that you could review as well, some are not applicable for your project such as the JOSS section. I downloaded your repo and ran the pytests on my machine, and everything passed. Read the docs, and your workflow was reviewed and everything looked good there as well. Again, great work team, I really enjoyed reading through this. Thank you.

[jo4356]

@khbunyan Thank you for the detailed review! We have fixed the moles_grams_converter() not behaving as desired in https://github.com/UBC-MDS/chemcalculator/commit/f9adc339806ca2dcc514c6120a30dbce9eacdac5 and https://github.com/UBC-MDS/chemcalculator/commit/7546f8befe566824c22cc7e9c7b3d72a2dde3220

[thayeylolu]

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

• [ ] 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

• [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

• [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

  ---

  Review Comments

All in all, I believe this is an awesome job. I have very little recommendations, observations and suggestion.

1. I observed that all the functions and tests are written in one file . I would recommend separating it in the future to avoid merge conflicts and easy expansion of functions in the future.

2. As @khbunyan mentioned, there are some typos in the Readme.md

3. on line 91 of this script, I observed that the parameter's description is missing a full-stop (I believe this package is following the numpy docstyle)

4. In the enforcement section, of this page Here your contact email address appears twice. I suggest you make it appear once. Same for this page Here

5. I also observed you list just three contributors but your contributors list on your github home page has four.

[berkaybulut]

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
• [ ] 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)
• [ ] 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
• [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:

• [X] A short summary describing the high-level functionality of the software
• [X] Authors: A list of authors with their affiliations
• [X] A statement of need clearly stating problems the software is designed to solve and its target audience.
• [X] 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:

---

Review Comments

Hello group 30, congratulations on your repository. It is a unique repo that is focused on chemists in python space, and it is one of the first that I have come across something like this. I think your repository is well organized and easy to understand. It is well put together and simple to follow.

I have a few comments that you can work on to improve further.

1. You functions are all in in one file, it can be improved to separate them for future ease of upgradability.
2. There are some typos in Readme.md as mentioned by @thayeylolu and @khbunyan
3. In your helper.py file the __check_chemical_format() function is missing a full stop typo in parameter description - according to numpy docstyle.

Great work to everyone - let me know if you have any questions!

[jo4356]

@thayeylolu Thanks for your review! To address your comment about contributor numbers, we only have 3 contributors. Two of the accounts listed as contributors belongs to the same person.

[helingogo]

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
• [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
• [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: 1.5

---

Review Comments

Congratulation on the completion of your project and the 100% code coverage! The repo is well organized and clean. The topic is explained well so that I can easily understand even though I am from business background. Most parts look pretty good. Following are some problems and suggestions:

1. The result I have for compute_mass("H2O") is 18.013, which is different from what you demonstrate in readme and documentation.

2. I think it is better to put outcome or result in Usage part both in readme file and in documentation so that the users would know whether they download and use the package correctly.

3. Also, elements for functions to be filled can be added and explained in the documentation and users would understand what the function does better. For example, users may need and want to know the third element of moles_grams_converter("H2O", 0.05555, **"moles"**) is converting from or converting to.

4. Dependencies can be added in readme file and documentation file.

5. You can also separate the test file into several ones like what has been done for functions.

It is a pleasure to look through your repo. Congrats again! Let me know if you have any question.