[REVIEW]: dcTensor: An R package for discrete matrix/tensor decomposition

editorialbot commented 1 year ago

Submitting author: !--author-handle-->@kokitsuyuzaki@diehlpk<!--end-editor-- Reviewers: @dekuenstle, @CeciliaCoelho Archive: 10.5281/zenodo.8275544

Status

Status badge code:

HTML: <a href="https://joss.theoj.org/papers/41a68242a41f762bd768ff44fc3b6b97"><img src="https://joss.theoj.org/papers/41a68242a41f762bd768ff44fc3b6b97/status.svg"></a>
Markdown: [![status](https://joss.theoj.org/papers/41a68242a41f762bd768ff44fc3b6b97/status.svg)](https://joss.theoj.org/papers/41a68242a41f762bd768ff44fc3b6b97)

Reviewers and authors:

Please avoid lengthy details of difficulties in the review thread. Instead, please create a new issue in the target repository and link to those issues (especially acceptance-blockers) by leaving comments in the review thread below. (For completists: if the target issue tracker is also on GitHub, linking the review thread in the issue or vice versa will create corresponding breadcrumb trails in the link target.)

Reviewer instructions & questions

@dekuenstle & @CeciliaCoelho, your review will be checklist based. Each of you will have a separate checklist that you should update when carrying out your review. First of all you need to run this command in a separate comment to create the checklist:

@editorialbot generate my checklist

The reviewer guidelines are available here: https://joss.readthedocs.io/en/latest/reviewer_guidelines.html. Any questions/concerns please let @diehlpk know.

✨ Please start on your review when you are able, and be sure to complete your review in the next six weeks, at the very latest ✨

Checklists

📝 Checklist for @dekuenstle

📝 Checklist for @CeciliaCoelho

editorialbot commented 1 year ago

Hello humans, I'm @editorialbot, a robot that can help you with some common editorial tasks.

For a list of things I can do to help you, just type:

@editorialbot commands

For example, to regenerate the paper pdf after making changes in the paper's md or bib files, type:

@editorialbot generate pdf

editorialbot commented 1 year ago

Software report:

github.com/AlDanial/cloc v 1.88  T=0.03 s (2398.1 files/s, 189715.9 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
R                               46            289            266           2983
Rmd                              7            226            432            265
Markdown                         6             60              0            203
TeX                              2             23             21            140
YAML                             1             11             13             45
Dockerfile                       1              1              2              4
-------------------------------------------------------------------------------
SUM:                            63            610            734           3640
-------------------------------------------------------------------------------

gitinspector failed to run statistical information for the repository

editorialbot commented 1 year ago

Wordcount for paper.md is 567

editorialbot commented 1 year ago

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- None

MISSING DOIs

- 10.1109/icdm.2007.99 may be a valid DOI for title: Binary Matrix Factorization with Applications
- 10.1109/icassp.2007.367106 may be a valid DOI for title: Non-negative Tensor Factorization using Alpha and Beta Divergence
- 10.1109/cvpr.2007.383405 may be a valid DOI for title: Nonnegative Tucker Decomposition
- 10.1038/44565 may be a valid DOI for title: Learning the parts of objects by non-negative matrix factorization
- 10.1186/s13059-019-1900-3 may be a valid DOI for title: Benchmarking principal component analysis for large-scale single-cell RNA-sequencing
- 10.1142/9789812776136_0027 may be a valid DOI for title: Extracting Gene Expression Profiles Common to Colon and Pancreatic Adenocarcinoma using Simultaneous nonnegative matrix factorization
- 10.1093/nar/gks725 may be a valid DOI for title: Discovery of multi-dimensional modules by integrative analysis of cancer genomic data
- 10.1007/978-3-642-15995-4_43 may be a valid DOI for title: Probabilistic Latent Tensor Factorization
- 10.1093/bioinformatics/btv544 may be a valid DOI for title: A non-negative matrix factorization method for detecting modules in heterogeneous omics multi-modal data

INVALID DOIs

- None

editorialbot commented 1 year ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

dekuenstle commented 1 year ago

Review checklist for @dekuenstle

Conflict of interest

[x] I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

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

General checks

[x] Repository: Is the source code for this software available at the https://github.com/rikenbit/dcTensor?
[x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
[x] Contribution and authorship: Has the submitting author (@kokitsuyuzaki) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
[x] Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines
[x] Data sharing: If the paper contains original data, data are accessible to the reviewers. If the paper contains no original data, please check this item.
[x] Reproducibility: If the paper contains original results, results are entirely reproducible by reviewers. If the paper contains no original results, please check this item.
[x] Human and animal research: If the paper contains original data research on humans subjects or animals, does it comply with JOSS's human participants research policy and/or animal research policy? If the paper contains no such data, please check this item.

Functionality

[x] Installation: Does installation proceed as outlined in the documentation?
[x] Functionality: Have the functional claims of the software been confirmed?
[x] Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

[x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
[x] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
[x] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
[x] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
[x] Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
[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

Software paper

[x] Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
[x] A statement of need: Does the paper have a section titled 'Statement of need' that clearly states what problems the software is designed to solve, who the target audience is, and its relation to other work?
[x] State of the field: Do the authors describe how this software compares to other commonly-used packages?
[x] Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
[x] References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

CeciliaCoelho commented 1 year ago

Review checklist for @CeciliaCoelho

Conflict of interest

[x] I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

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

General checks

[x] Repository: Is the source code for this software available at the https://github.com/rikenbit/dcTensor?
[x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
[x] Contribution and authorship: Has the submitting author (@kokitsuyuzaki) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
[x] Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines
[x] Data sharing: If the paper contains original data, data are accessible to the reviewers. If the paper contains no original data, please check this item.
[x] Reproducibility: If the paper contains original results, results are entirely reproducible by reviewers. If the paper contains no original results, please check this item.
[x] Human and animal research: If the paper contains original data research on humans subjects or animals, does it comply with JOSS's human participants research policy and/or animal research policy? If the paper contains no such data, please check this item.

Functionality

[x] Installation: Does installation proceed as outlined in the documentation?
[x] Functionality: Have the functional claims of the software been confirmed?
[x] Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

[x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
[x] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
[x] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
[x] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
[x] Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
[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

Software paper

[x] Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
[x] A statement of need: Does the paper have a section titled 'Statement of need' that clearly states what problems the software is designed to solve, who the target audience is, and its relation to other work?
[x] State of the field: Do the authors describe how this software compares to other commonly-used packages?
[x] Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
[x] References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

dekuenstle commented 1 year ago

The submission presents a highly specialized R package for discrete matrix decomposition algorithms. The package is openly available (MIT-Licence on Github) and distributed according to R-standards on CRAN; the API is simple, and extensive unit tests are available (while it is unclear if they run automatically). However, I have some suggestions for improvement concerning the documentation and the manuscript.

The CRAN documentation provides a good explanation of the input parameters and expected data format as well as references to publications describing the implemented algorithms. Here it would be helpful to have a small summary of the algorithm in the Description field of each function, i.e. describing for what purpose the algorithm is used or how it is different from the others. The only installation instructions on the repository readme are aimed more at developers than end users because they install from Github instead of CRAN. The readme could be a good place to give users and developers separate instructions and add the missing community guidelines. The file LICENSE.md contains an MIT license statement; however, there is another file, LICENSE, with just a header that might be removed. Unit tests are available in the repository, but test coverage and automation are not documented. The Github action workflow "build_test_push.yml", running on push and pull, apparently is not running the test suite–––Test automation should be added or, if already done, documented.

The paper Summary provides a high-level introduction to discrete matrix decomposition. The arguments could profit from a few more explanations. In the first paragraph, introducing matrix decomposition might be inclusive, i.e., explaining that the product of factor matrices reconstruct the original matrix and why this is a non-trivial problem. In the third paragraph, it remains to be seen why there is a demand for tensor decomposition. The Statement of Need justifies the need through the non-existence of algorithm implementations. However, this justification needs more explanation for which problems to solve and for which target community these implementations are needed. Especially it would be relevant to explain the need in applications for algorithms provided in the submitted package but not in related works. This also provides the opportunity to integrate the very short Related Work section into the Statement of Need. While I appreciate the provided code example in the manuscript, it requires further explanations and a more coherent integration in the other sections. The plots should use identical colors and frequency axis to compare original and reconstructed data visually. Many citations and references do not follow the standards, are duplicates ("Zhang, Z. et al. in 2007 (Z. et al. Zhang, 2007)"), are missing Co-authors ("CICHOCK, 2009" should be "Cichock et al., 2009"), or are permuted ("Z. et al. Zhang, 2007"); most of those could be resolved by adding the full list of authors to the Bib file. DOIs should be added to the references, as suggested by the @editorialbot above. Overall, the language in the manuscript should be revised with a focus on rephrasing nested sentences and increasing coherence.

CeciliaCoelho commented 1 year ago

TL;DR

I recommend major revision of the paper and documentation available at the repository.

Overall review

There is evidence of the effort put in the package development however the documentation of the repository is a big downside due to being very small and poor (readme) or scattered in multiple files (example the contribution instructions). Not having instructions of how to use it or information on the examples included in the package in the readme can make users reluctant in trying this package due to the extra time it takes to search for all information they need to use it. This may sound harsh but I think such a nice package should have an equally nice and friendly readme. This will attract more users. Also, the paper is also lacking information and the summary information does not belong to the summary but rather to the statement of need. I advise the authors to check accepted papers and their repositories for a guideline.

Major comments

1 - The summary is too big in comparison to the rest of the documentation. The summary should describe concisely the package that is going to be presented stating what functions are implemented, some key features it contains and the target programming language. Right now the summary presented is more appropriate for the statement of need since it gives a background explanation of the implemented algorithms. The summary should be one paragraph. If the authors need some guidelines to fix the summary they should check accepted JOSS papers. 2 - The statement of need is very incomplete. It is missing a background explanation on the algorithms, what they are for and their applications. Having only a list of names with some references is very limited and at least a paragraph explaining each item should be included. 3 - The repository readme is very poor. It should have a brief explanation at the top stating what the repository has. It can be the summary used in the paper after fixing according to 2. It should clearly state how to use the functions provided and how to run the example code. The readme should also include the contributing.md. All information should be readily available to the users. Again I suggest the authors to check readme files of accepted papers if they need a guideline. 4 - The references need to be fully redone. The names of all the authors need to be written. Only when used in the text "et al." is used. It appears CICHOCK should be Cichocki. 5 - The Example section in the paper should be explained with more detail. Like what is the goal, the description of the problem 6 - The plots in Figure 1 are not consistent and cannot be used for comparison between them since they show different scales

Minor comments

7 - There are 2 license files. Please remove the extra one 8 - In the paper the authors use "I" and "We". Just one should be used in all paper

diehlpk commented 1 year ago

@kokitsuyuzaki please have a look at the comments above.

kokitsuyuzaki commented 1 year ago

Thank you for the review.

@kokitsuyuzaki please have a look at the comments above.

Sorry, I was on a long vacation and will check the review comments from now.

diehlpk commented 1 year ago

@kokitsuyuzaki Can you please let us know if you worked on the comments?

kokitsuyuzaki commented 1 year ago

Yes, I'm working on the comments.

This has been a difficult process due to many comments. Since many of the comments from two reviewers are duplicated, I have combined them as Issues. e.g., https://github.com/rikenbit/dcTensor/issues/8

I will reply to all of them in the next few days.

diehlpk commented 1 year ago

@kokitsuyuzaki just ping me and the reviewers here once you are done.

kokitsuyuzaki commented 1 year ago

I will contact you when all issues are addressed.

kokitsuyuzaki commented 1 year ago

@dekuenstle @CeciliaCoelho

I'm sorry for taking time so long. Now I have addressed all the issues, so please comment them. https://github.com/rikenbit/dcTensor/issues

kokitsuyuzaki commented 1 year ago

@editorialbot generate pdf

editorialbot commented 1 year ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

CeciliaCoelho commented 1 year ago

@editorialbot commands

editorialbot commented 1 year ago

Hello @CeciliaCoelho, here are the things you can ask me to do:


# List all available commands
@editorialbot commands

# Get a list of all editors's GitHub handles
@editorialbot list editors

# Check the references of the paper for missing DOIs
@editorialbot check references

# Perform checks on the repository
@editorialbot check repository

# Adds a checklist for the reviewer using this command
@editorialbot generate my checklist

# Set a value for branch
@editorialbot set joss-paper as branch

# Generates the pdf paper
@editorialbot generate pdf

# Generates a LaTeX preprint file
@editorialbot generate preprint

# Get a link to the complete list of reviewers
@editorialbot list reviewers

CeciliaCoelho commented 1 year ago

@kokitsuyuzaki thank you for addressing my comments. I now recommend acceptance.

dekuenstle commented 1 year ago

@kokitsuyuzaki thank you for the responses and changes. @diehlpk I recommend acceptance, too.

diehlpk commented 1 year ago

@kokitsuyuzaki I am traveling and will take care of the paper next week.

diehlpk commented 1 year ago

@editorialbot check references

editorialbot commented 1 year ago

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1109/icdm.2007.99 is OK
- 10.3390/math9111189 is OK
- 10.1109/icassp.2007.367106 is OK
- 10.1109/cvpr.2007.383405 is OK
- 10.1038/44565 is OK
- 10.1186/s13059-019-1900-3 is OK
- 10.1142/9789812776136_0027 is OK
- 10.1093/nar/gks725 is OK
- 10.1007/978-3-642-15995-4_43 is OK
- 10.1093/bioinformatics/btv544 is OK

MISSING DOIs

- None

INVALID DOIs

- None

diehlpk commented 1 year ago

@editorialbot generate pdf

editorialbot commented 1 year ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

diehlpk commented 1 year ago

@kokitsuyuzaki

[ ] Please generate a new release containing all changes you made during the review. Post the version number here.
[ ] Please upload the release to Zenodo or FigShare and post the DOI here. Please check that the title and authors of the paper match with the archive.

kokitsuyuzaki commented 1 year ago

Thanks, @diehlpk

I tagged the latest version as v1.2.3 and archieved by Zenodo.

The DOI is 10.5281/zenodo.8275544

Please also check these pages. https://github.com/rikenbit/dcTensor/releases/tag/v1.2.3 https://zenodo.org/record/8275544

diehlpk commented 1 year ago

@editorialbot set v1.2.3 as version

editorialbot commented 1 year ago

Done! version is now v1.2.3

diehlpk commented 1 year ago

@editorialbot generate pdf

diehlpk commented 1 year ago

@kokitsuyuzaki it seems the Zenodo entry does not match with the paper.

dcTensor: An R package for discrete matrix/tensor decomposition

kokitsuyuzaki

Yous should use your name and not your GitHub handle.

Can you please fix that?

Note there is no need to generate a new DOI.

editorialbot commented 1 year ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

diehlpk commented 1 year ago

@editorialbot set 10.5281/zenodo.8275544 as archive

editorialbot commented 1 year ago

Done! archive is now 10.5281/zenodo.8275544

kokitsuyuzaki commented 1 year ago

@diehlpk Sorry, I was having trouble mapping GitHub Release and Zenodo and couldn't come up with a solution other than to upgrade to a new version. I modified the author name. https://zenodo.org/record/8275544

diehlpk commented 1 year ago

@kokitsuyuzaki it looks good now.

diehlpk commented 1 year ago

@editorialbot recommend-accept

editorialbot commented 1 year ago

Attempting dry run of processing paper acceptance...

editorialbot commented 1 year ago

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1109/icdm.2007.99 is OK
- 10.3390/math9111189 is OK
- 10.1109/icassp.2007.367106 is OK
- 10.1109/cvpr.2007.383405 is OK
- 10.1038/44565 is OK
- 10.1186/s13059-019-1900-3 is OK
- 10.1142/9789812776136_0027 is OK
- 10.1093/nar/gks725 is OK
- 10.1007/978-3-642-15995-4_43 is OK
- 10.1093/bioinformatics/btv544 is OK

MISSING DOIs

- None

INVALID DOIs

- None

editorialbot commented 1 year ago

:wave: @openjournals/dsais-eics, this paper is ready to be accepted and published.

Check final proof :point_right::page_facing_up: Download article

If the paper PDF and the deposit XML files look good in https://github.com/openjournals/joss-papers/pull/4501, then you can now move forward with accepting the submission by compiling again with the command @editorialbot accept

gkthiruvathukal commented 1 year ago

@editorialbot accept

editorialbot commented 1 year ago

Doing it live! Attempting automated processing of paper acceptance...

editorialbot commented 1 year ago

Ensure proper citation by uploading a plain text CITATION.cff file to the default branch of your repository.

If using GitHub, a Cite this repository menu will appear in the About section, containing both APA and BibTeX formats. When exported to Zotero using a browser plugin, Zotero will automatically create an entry using the information contained in the .cff file.

You can copy the contents for your CITATION.cff file here:

CITATION.cff

``` cff-version: "1.2.0" authors: - family-names: Tsuyuzaki given-names: Koki orcid: "https://orcid.org/0000-0003-3797-2148" doi: 10.5281/zenodo.8275544 message: If you use this software, please cite our article in the Journal of Open Source Software. preferred-citation: authors: - family-names: Tsuyuzaki given-names: Koki orcid: "https://orcid.org/0000-0003-3797-2148" date-published: 2023-08-25 doi: 10.21105/joss.05664 issn: 2475-9066 issue: 88 journal: Journal of Open Source Software publisher: name: Open Journals start: 5664 title: "dcTensor: An R package for discrete matrix/tensor decomposition" type: article url: "https://joss.theoj.org/papers/10.21105/joss.05664" volume: 8 title: "dcTensor: An R package for discrete matrix/tensor decomposition" ```

If the repository is not hosted on GitHub, a .cff file can still be uploaded to set your preferred citation. Users will be able to manually copy and paste the citation.

Find more information on .cff files here and here.

editorialbot commented 1 year ago

🐘🐘🐘 👉 Toot for this paper 👈 🐘🐘🐘

editorialbot commented 1 year ago

🚨🚨🚨 THIS IS NOT A DRILL, YOU HAVE JUST ACCEPTED A PAPER INTO JOSS! 🚨🚨🚨

Here's what you must now do:

Check final PDF and Crossref metadata that was deposited :point_right: https://github.com/openjournals/joss-papers/pull/4509
Wait a couple of minutes, then verify that the paper DOI resolves https://doi.org/10.21105/joss.05664
If everything looks good, then close this review issue.
Party like you just published a paper! 🎉🌈🦄💃👻🤘

Any issues? Notify your editorial technical team...

editorialbot commented 1 year ago

:tada::tada::tada: Congratulations on your paper acceptance! :tada::tada::tada:

If you would like to include a link to your paper from your README use the following code snippets:

Markdown:
[![DOI](https://joss.theoj.org/papers/10.21105/joss.05664/status.svg)](https://doi.org/10.21105/joss.05664)

HTML:
<a style="border-width:0" href="https://doi.org/10.21105/joss.05664">
  <img src="https://joss.theoj.org/papers/10.21105/joss.05664/status.svg" alt="DOI badge" >
</a>

reStructuredText:
.. image:: https://joss.theoj.org/papers/10.21105/joss.05664/status.svg
   :target: https://doi.org/10.21105/joss.05664

This is how it will look in your documentation:

We need your help!

The Journal of Open Source Software is a community-run journal and relies upon volunteer effort. If you'd like to support us please consider doing either one (or both) of the the following:

Volunteering to review for us sometime in the future. You can add your name to the reviewer list here: https://reviewers.joss.theoj.org/join
Making a small donation to support our running costs here: https://numfocus.org/donate-to-joss

openjournals / joss-reviews