Submission: Group 4: Predicting the Shares of News Articles based on Social networks

Submitting authors: Amar Gill, Anshnoor Kaur, Hanyu Dai, Yanxin Liang

Repository: https://github.com/DSCI-310-2024/DSCI-310_predicting-shares_group-4/releases/tag/Milestone-3

Abstract/executive summary:

Use dataset from open source websites UCI Machine Learning Repository: Data Sets to predict the number of shares of a article. We split the data into traing and testing parts, and proceed full model and reduced model to make the results more reliable and efficent enough.

Editor: @ttimbers

Reviewer: Riddha Tuladhar Gurman Gill Cassandra Zhang Fiona Chang

[ ] I agree to abide by DSCI 310's Code of Conduct during the review process.

Data analysis review checklist

Reviewer: FionaC124

Conflict of interest

[x] As the reviewer I confirm that I have no conflicts of interest for me to review this work.

Code of Conduct

[x] I confirm that I read and will adhere to the MDS code of conduct.

General checks

[x] Repository: Is the source code for this data analysis available? Is the repository well organized and easy to navigate?
[x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?

Documentation

[x] Installation instructions: Is there a clearly stated list of dependencies?
[x] Example usage: Do the authors include examples of how to use the software to reproduce the data analysis?
[x] Functionality documentation: Is the core functionality of the data analysis software documented to a satisfactory level?
[x] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Code quality

[x] Readability: Are scripts, functions, objects, etc., well named? Is it relatively easy to understand the code?
[x] Style guidelides: Does the code adhere to well known language style guides?
[x] Modularity: Is the code suitably abstracted into scripts and functions?
[x] Tests: Are there automated tests or manual steps described so that the function of the software can be verified? Are they of sufficient quality to ensure software robsutness?

Reproducibility

[x] Data: Is the raw data archived somewhere? Is it accessible?
[x] Computational methods: Is all the source code required for the data analysis available?
[x] Conditions: Is there a record of the necessary conditions (software dependencies) needed to reproduce the analysis? Does there exist an easy way to obtain the computational environment needed to reproduce the analysis?
[x] Automation: Can someone other than the authors easily reproduce the entire data analysis?

Analysis report

[ ] Authors: Does the report include a list of authors with their affiliations?
[ ] What is the question: Do the authors clearly state the research question being asked?
[x] Importance: Do the authors clearly state the importance for this research question?
[x] Background: Do the authors provide sufficient background information so that readers can understand the report?
[x] Methods: Do the authors clearly describe and justify the methodology used in the data analysis? Do the authors communicate any assumptions or limitations of their methodologies?
[x] Results: Do the authors clearly communicate their findings through writing, tables and figures?
[x] Conclusions: Are the conclusions presented by the authors correct?
[x] References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?
[x] Writing quality: Is the writing of good quality, concise, engaging?

Estimated hours spent reviewing: 1.25

Review Comments:

Some parts of your README could be more detailed in order for viewers to run your code with the least friction. For example, specific instructions for "Then using a CLI (Command line interface), set the release to be your current directory" or a link to Docker download. In the Makefile section, markdown styling could have been used to identify the "make all" and "make clean" commands more easily.
In your CONTRIBUTING documentation, I felt that the process for submitting code is a little vague. For example, after I reach out to a group member about a new feature for the project, do I have to wait for their approval before starting work on a pull request? Or am I just reaching out to notify? Is there an issue that needs to be created to contribute?
Some minor typos or mistakes that could be fixed but don't necessary affect the project on a high level:
- "traing" in README.md Overview
- "Contrubuting" in CONTRIBUTING.md title
- Title left as "Title" in report table of contents

Attribution

This was derived from the JOSE review checklist and the ROpenSci review checklist.

Data analysis review checklist

Reviewer: gurmangill125

Conflict of interest

[x] As the reviewer I confirm that I have no conflicts of interest for me to review this work.

Code of Conduct

[x] I confirm that I read and will adhere to the MDS code of conduct.

General checks

[x] Repository: Is the source code for this data analysis available? Is the repository well organized and easy to navigate?
[x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?

Documentation

[x] Installation instructions: Is there a clearly stated list of dependencies?
[x] Example usage: Do the authors include examples of how to use the software to reproduce the data analysis?
[x] Functionality documentation: Is the core functionality of the data analysis software documented to a satisfactory level?
[x] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Code quality

[x] Readability: Are scripts, functions, objects, etc., well named? Is it relatively easy to understand the code?
[x] Style guidelides: Does the code adhere to well known language style guides?
[x] Modularity: Is the code suitably abstracted into scripts and functions?
[x] Tests: Are there automated tests or manual steps described so that the function of the software can be verified? Are they of sufficient quality to ensure software robsutness?

Reproducibility

[x] Data: Is the raw data archived somewhere? Is it accessible?
[x] Computational methods: Is all the source code required for the data analysis available?
[x] Conditions: Is there a record of the necessary conditions (software dependencies) needed to reproduce the analysis? Does there exist an easy way to obtain the computational environment needed to reproduce the analysis?
[x] Automation: Can someone other than the authors easily reproduce the entire data analysis?

Analysis report

[ ] Authors: Does the report include a list of authors with their affiliations?
[ ] What is the question: Do the authors clearly state the research question being asked?
[ ] Importance: Do the authors clearly state the importance for this research question?
[x] Background: Do the authors provide sufficient background information so that readers can understand the report?
[x] Methods: Do the authors clearly describe and justify the methodology used in the data analysis? Do the authors communicate any assumptions or limitations of their methodologies?
[x] Results: Do the authors clearly communicate their findings through writing, tables and figures?
[x] Conclusions: Are the conclusions presented by the authors correct?
[x] References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?
[x] Writing quality: Is the writing of good quality, concise, engaging?

Estimated hours spent reviewing: 1

Review Comments:

The CONTRIBUTING documentation introduces the process for contributions but leaves room for ambiguity regarding the workflow for proposing new features or changes. It would be beneficial to clarify whether an informal notification is okay or if formal approval is required before proceeding with contributions, such as pull requests, and whether the creation of an issue is a prerequisite for contributing to the project. More clear and detailed documentation would be great.
While the documentation is fundamentally fine, it contains minor errors that suggest areas for improvement in attention to detail. Specifically, there are a few spelling mistakes. For example, the misspelling of "training" as "traing" in the README.md and "Contrubuting" in the CONTRIBUTING.md title. Additionally, the oversight of leaving a placeholder title in the report's table of contents could easily be fixed for a more polished presentation.
The README presents a decent overview of the project, but further details could significantly benefit people viewing the repository. For instance, the section describing the setup with Docker lacks comprehensive guidance for users unfamiliar with Docker or CLI operations. A step-by-step walkthrough, including screenshots or a direct link to Docker installation resources, could mitigate potential setup barriers. Similarly, in the Makefile section, adopting markdown formatting to distinctly highlight command lines like make all and make clean would streamline user interaction by making instructions more accessible and clearer to follow.

Attribution

This was derived from the JOSE review checklist and the ROpenSci review checklist.

Data analysis review checklist

Reviewer: riddhat

Conflict of interest

[x] As the reviewer I confirm that I have no conflicts of interest for me to review this work.

Code of Conduct

[x] I confirm that I read and will adhere to the MDS code of conduct.

General checks

[x] Repository: Is the source code for this data analysis available? Is the repository well organized and easy to navigate?
[x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?

Documentation

[x] Installation instructions: Is there a clearly stated list of dependencies?
[x] Example usage: Do the authors include examples of how to use the software to reproduce the data analysis?
[x] Functionality documentation: Is the core functionality of the data analysis software documented to a satisfactory level?
[ ] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Code quality

[x] Readability: Are scripts, functions, objects, etc., well named? Is it relatively easy to understand the code?
[x] Style guidelides: Does the code adhere to well known language style guides?
[x] Modularity: Is the code suitably abstracted into scripts and functions?
[x] Tests: Are there automated tests or manual steps described so that the function of the software can be verified? Are they of sufficient quality to ensure software robsutness?

Reproducibility

[x] Data: Is the raw data archived somewhere? Is it accessible?
[x] Computational methods: Is all the source code required for the data analysis available?
[x] Conditions: Is there a record of the necessary conditions (software dependencies) needed to reproduce the analysis? Does there exist an easy way to obtain the computational environment needed to reproduce the analysis?
[ ] Automation: Can someone other than the authors easily reproduce the entire data analysis?

Analysis report

[ ] Authors: Does the report include a list of authors with their affiliations?
[x] What is the question: Do the authors clearly state the research question being asked?
[x] Importance: Do the authors clearly state the importance for this research question?
[x] Background: Do the authors provide sufficient background information so that readers can understand the report?
[x] Methods: Do the authors clearly describe and justify the methodology used in the data analysis? Do the authors communicate any assumptions or limitations of their methodologies?
[x] Results: Do the authors clearly communicate their findings through writing, tables and figures?
[x] Conclusions: Are the conclusions presented by the authors correct?
[x] References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?
[x] Writing quality: Is the writing of good quality, concise, engaging?

Estimated hours spent reviewing: 2.5

Review Comments:

I like your project idea! I think your research question in particular is intriguing. I do, however, believe there is room for improvement:

The README file is fairly ambiguous and appears to be missing some important information. Crucially, it does not clearly state or instruct the reader on how to run the analysis nor does it mention how to one might contribute to the project. In particular, the makefile instructions for generating the analysis could be more explicit, maybe by having easily copy-paste-able code for the user to use. Furthermore, adding instructions on how to install the dependencies by providing a link to the docker website would be nice.
In the CODE_OF_CONDUCT.md file, the procedure for reporting and dealing with unacceptable behavior could be improved. In particular, it mentions that an individual should "report any issue to the person in charge" yet does not mention who this person in charge is or how they are chosen.
In R/ folder, clean_data.R and histograms.R should specify the package each function used is from for the sake of reproducibility, just so that if a new package is added to the analysis that contains a function with the same name that the script will run as intended. In particular, histograms.R does not specify the package for any of the ggplot2 functions used (ggplot, aes, geom_histogram) and clean_data.R does not specify the package for the all_of function in line 30. The all_of function is particularly important as I believe that, in the tidyverse package that is imported in the analysis, the packages dplyr, tidyr, and tidyselect all have specifications for an all_of function.

Attribution

This was derived from the JOSE review checklist and the ROpenSci review checklist.

Data analysis review checklist

Reviewer:

Conflict of interest

[x] As the reviewer I confirm that I have no conflicts of interest for me to review this work.

Code of Conduct

[x] I confirm that I read and will adhere to the MDS code of conduct.

General checks

[x] Repository: Is the source code for this data analysis available? Is the repository well organized and easy to navigate?
[x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?

Documentation

[ ] Installation instructions: Is there a clearly stated list of dependencies?
[ ] Example usage: Do the authors include examples of how to use the software to reproduce the data analysis?
[ ] Functionality documentation: Is the core functionality of the data analysis software documented to a satisfactory level?
[ ] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Code quality

[ ] Readability: Are scripts, functions, objects, etc., well named? Is it relatively easy to understand the code?
[x] Style guidelides: Does the code adhere to well known language style guides?
[x] Modularity: Is the code suitably abstracted into scripts and functions?
[x] Tests: Are there automated tests or manual steps described so that the function of the software can be verified? Are they of sufficient quality to ensure software robsutness?

Reproducibility

[x] Data: Is the raw data archived somewhere? Is it accessible?
[x] Computational methods: Is all the source code required for the data analysis available?
[x] Conditions: Is there a record of the necessary conditions (software dependencies) needed to reproduce the analysis? Does there exist an easy way to obtain the computational environment needed to reproduce the analysis?
[ ] Automation: Can someone other than the authors easily reproduce the entire data analysis?

Analysis report

[ ] Authors: Does the report include a list of authors with their affiliations?
[ ] What is the question: Do the authors clearly state the research question being asked?
[x] Importance: Do the authors clearly state the importance for this research question?
[x] Background: Do the authors provide sufficient background information so that readers can understand the report?
[ ] Methods: Do the authors clearly describe and justify the methodology used in the data analysis? Do the authors communicate any assumptions or limitations of their methodologies?
[ ] Results: Do the authors clearly communicate their findings through writing, tables and figures?
[x] Conclusions: Are the conclusions presented by the authors correct?
[x] References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?
[x] Writing quality: Is the writing of good quality, concise, engaging?

Estimated hours spent reviewing:

Review Comments:

The README file does not explain all the details needed to understand how to use the designed project, including a list of clear dependencies. For the Makefile section, it also does not explicitly provide the necessary commands used to generate the report, which may require readers to read the makefile themselves to understand how to use it.
The documentation also does not provide information related to how a third party can contribute to the project. It may lead to further communication costs for people to connect with the authors to be able to contribute to the analysis.
The information about the methodology in the report is not stated in an easy-to-understand way. The pros and cons of the methodology are not listed, which becomes a weakness of the report. Listing the pros and cons of the methodology could be helpful for future improvement, such as the use of another better-suited methodology to improve accuracy and better address the research question.

Attribution

This was derived from the JOSE review checklist and the ROpenSci review checklist.

DSCI-310-2024 / data-analysis-review-2024