Submission: rimgtool (R)

Submitting Author: Ruidan Ni (@rita-ni), Frank Lu (@franklu2014), Kexin Zhao (@Margaret8521) Repository: rimgtool Version submitted: 0.3.0 Editor: Varada Kolhatkar (@kvarada) Reviewer 1: Fanli Zhou (@flizhou) Reviewer 2: Haipeng Zhang (@Zhang-Haipeng) Archive: TBD Version accepted: TBD

Package: rimgtool
Title: Image processing
Version: 0.0.0.9000
Authors@R: 
   c(person(given = "Frank",
           family = "Lu",
           role = c("aut", "cre"),
           email = "franklu@live.ca",
           comment = c(ORCID = "YOUR-ORCID-ID")),
    person(given = "Rita",
           family = "Ni",
           role = c("aut"),
           email = "niruidan@gmail.com"),
    person(given = "Margaret",
           family = "Zhao",
           role = c("aut"),
           email = "margaretzhao@yahoo.com"))
Description: The package can compresses, sharpen, or shrink images.
    The compress function can reduce the byte size of the image, 
    the shrink function reduce image size by removing border pixels, 
    the sharpen function by applying special filters.
License: MIT + file LICENSE
Encoding: UTF-8
LazyData: true
RoxygenNote: 7.0.2
Suggests: 
    testthat (>= 2.1.0),
    covr,
    knitr,
    rmarkdown
URL: https://github.com/UBC-MDS/rimgtool
BugReports: https://github.com/UBC-MDS/rimgtool/issues
VignetteBuilder: knitr

Scope

Please indicate which category or categories from our package fit policies this package falls under: (Please check an appropriate box below. If you are unsure, we suggest you make a pre-submission inquiry.):
- [ ] data retrieval
- [x] data extraction
- [ ] data munging
- [ ] data deposition
- [ ] workflow automataion
- [ ] version control
- [ ] citation management and bibliometrics
- [x] scientific software wrappers
- [ ] database software bindings
- [ ] geospatial data
- [ ] text analysis
Explain how and why the package falls under these categories (briefly, 1-2 sentences):
- Our rimgtool package does not fall specifically into any of the categories, however, it is closest to data extraction and scientific software wrappers. It is intended to allow users to compress, sharpen and shrink an input image, and we do use KMeans from a library and a self-made 2-D convolution.
Who is the target audience and what are scientific applications of this package?
- The target audience should be users who want to perform easy image processing without the understanding of machine learning. This package is not intended for scientific applications.
Are there other R packages that accomplish the same thing? If so, how does yours differ or meet our criteria for best-in-category?
- There are a few existing R packages that perform image manipulation such as magick and imager, which could be used for simplifying high-quantity images. However, these packages are usually very comprehensive and provide many functions to process the image in different ways. There are very few smaller packages available on Github to perform simpler image processing tasks like image shrinking such as this package using seam carving mechanism. Our implementation of image processing is a less sophisticated version of the existing image processing tools, we focus specifically on image compression, shrinking, and sharpening using simpler and easy to understand algorithms.
If you made a pre-submission enquiry, please paste the link to the corresponding issue, forum post, or other discussions, or @tag the editor you contacted.

Technical checks

Confirm each of the following by checking the box.

[x] I have read the guide for authors and rOpenSci packaging guide.

This package:

[x] does not violate the Terms of Service of any service it interacts with.
[ ] has a CRAN and OSI accepted license.
[x] contains a README with instructions for installing the development version.
[x] includes documentation with examples for all functions, created with roxygen2.
[x] contains a vignette with examples of its essential functions and uses.
[x] has a test suite.
[x] has continuous integration, including reporting of test coverage using services such as Travis CI, Coveralls and/or CodeCov.

Publication options

[ ] Do you intend for this package to go on CRAN?
[ ] Do you intend for this package to go on Bioconductor?
[x] Do you wish to automatically submit to the Journal of Open Source Software? If so:

JOSS Options

- [ ] The package has an **obvious research application** according to [JOSS's definition](https://joss.readthedocs.io/en/latest/submitting.html#submission-requirements). - [ ] The package contains a `paper.md` matching [JOSS's requirements](https://joss.readthedocs.io/en/latest/submitting.html#what-should-my-paper-contain) with a high-level description in the package root or in `inst/`. - [ ] The package is deposited in a long-term repository with the DOI: - (*Do not submit your package separately to JOSS*)

[ ] Do you wish to submit an Applications Article about your package to Methods in Ecology and Evolution? If so:

MEE Options

- [ ] The package is novel and will be of interest to the broad readership of the journal. - [ ] The manuscript describing the package is no longer than 3000 words. - [ ] You intend to archive the code for the package in a long-term repository which meets the requirements of the journal (see [MEE's Policy on Publishing Code](http://besjournals.onlinelibrary.wiley.com/hub/journal/10.1111/(ISSN)2041-210X/journal-resources/policy-on-publishing-code.html)) - (*Scope: Do consider MEE's [Aims and Scope](http://besjournals.onlinelibrary.wiley.com/hub/journal/10.1111/(ISSN)2041-210X/aims-and-scope/read-full-aims-and-scope.html) for your manuscript. We make no guarantee that your manuscript will be within MEE scope.*) - (*Although not required, we strongly recommend having a full manuscript prepared when you submit here.*) - (*Please do not submit your package separately to Methods in Ecology and Evolution*)

Code of conduct

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

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
[x] Vignette(s) demonstrating major functionality that runs successfully locally
[x] Function Documentation: for all exported functions in R help
[x] Examples for all exported functions in R Help that run successfully locally
[x] Community guidelines including contribution guidelines in the README or CONTRIBUTING, and DESCRIPTION with URL, BugReports and Maintainer (which may be autogenerated via Authors@R).

For packages co-submitting to JOSS

[ ] The package has an obvious research application according to JOSS's definition

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).

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: Unit tests cover essential functions of the package and a reasonable range of inputs and conditions. All tests pass on the local machine.
[x] Packaging guidelines: The package conforms to the rOpenSci packaging guidelines

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:

[x] Should the author(s) deem it appropriate, I agree to be acknowledged as a package reviewer ("rev" role) in the package DESCRIPTION file.

Review Comments

First of all, as a photography lover, I really like the theme of your package (and the name! Can't believe it wasn't taken). And congratulations on making it work within a short period. Below I've listed several observations/thoughts of mine while playing around with your package. Please take them with a grain of salt.
1. As a package for image processing, I would expect it to work with image files directly (e.g. takes a .jpg file as input and returns a .jpg file as output). For myself, I found jpeg package to read .jpg files into arrays and OpenImageR package to write arrays back to .jpg files.
2. With limited knowledge of image data in arrays, I find it a bit hard to understand the purpose of compress function (as well as the arguments it requires like 'b - the desired number of bits'). It would be nice for the users if we could provide some non-technical introduction to the purpose of the function.
3. Intuitively, compressing an image usually means to reduce the size (size in kb/MB/GB..) of the image while retaining its quality. So I would suggest considering giving it a different name.
4. For compress function, I had to input b = 2L instead of b = 2 to make it work, which is kind of counter-intuitive.
5. What shrink package does is more like crop. Personally, I feel shrink indicates making the image smaller as a whole. (I'm being very picky here. 😈)
6. When running sharpen function, it prints out [1] "row=3744; col=5616", which I think is not that useful to the user.
7. In the Package Overview section of the README file, numpy seems to be a typo.
8. In the Usage section of the README file, rimgtool.compress(image, 3) appears to be the syntax for python.
9. It'd be nice if we could provide some helper data for the users (or helper image file if we could enhance our package to deal with image files directly).
10. It would be nice to also give visualized examples for compress and shrink. Because without images, we don't actually know whether the functions process the images as desired.
11. FYR, below is my code for running tests. It was fun trying out your package. Thank you! And please let me know if you have any questions!

library(jpeg) # install.packages('jpeg')
library(OpenImageR) # install.packages('OpenImageR')
library(rimgtool) # devtools::install_github("UBC-MDS/rimgtool")

img <- jpeg::readJPEG('img.jpg')
img_compress <- rimgtool::compress(img, 20L)
img_sharpen <- rimgtool::sharpen(img)
img_shrink <- shrink(img, 500, 500)

OpenImageR::writeImage(img_compress, 'img_compress.jpg')
OpenImageR::writeImage(img_sharpen, 'img_sharpen.jpg')
OpenImageR::writeImage(img_shrink, 'img_shrink_500_500.jpg')

Thank you for the feedback. I will respond to your first question and go from there. The idea of this package is for image processing, but we don't want to constrain users from using any image format. Some users might prefer .jepg, like yourself, but there are many other formats might be preferred by other users. That's why we want to leave the flexibility to the users for choosing whatever rendering format they like, and we deal with the core of the image, which is an array.

Just think of Scikit-Learn. Users create their own arrays from .csv, .xlsx, or any sort of input, and the models take in the arrays, do the processing, and return a processed array. This package tries to follow the same procedure as Scikit-Learn and takes in arrays and returns processed arrays.

By the way, I found questions 9 and 10 are contradicting. Since question 10 indicates that an example can be found, questtion 9 is satisfied.

Thank you for the feedback. I will respond to your first question and go from there. The idea of this package is for image processing, but we don't want to constrain users from using any image format. Some users might prefer .jepg, like yourself, but there are many other formats might be preferred by other users. That's why we want to leave the flexibility to the users for choosing whatever rendering format they like, and we deal with the core of the image, which is an array.

Just think of Scikit-Learn. Users create their own arrays from .csv, .xlsx, or any sort of input, and the models take in the arrays, do the processing, and return a processed array. This package tries to follow the same procedure as Scikit-Learn and takes in arrays and returns processed arrays.

@franklu2014 That's a fair point. But still, there are pros and cons to such a decision. I think it's up to you guys to make the call.

By the way, I found questions 9 and 10 are contradicting. Since question 10 indicates that an example can be found, questtion 9 is satisfied.

Not really. Because for one thing, what we have is an image, which won't work as helper data for our package for now (since our package requires array). Secondly, there's no instruction to guide the user/tester to use this image as helper data. It's more like a documentation file that we used in developing the package. (I also wonder if a greyscale image could be used for testing compress function.)

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
[x] Vignette(s) demonstrating major functionality that runs successfully locally
[x] Function Documentation: for all exported functions in R help
[x] Examples for all exported functions in R Help that run successfully locally
[x] Community guidelines including contribution guidelines in the README or CONTRIBUTING, and DESCRIPTION with URL, BugReports and Maintainer (which may be autogenerated via Authors@R).

For packages co-submitting to JOSS

[ ] The package has an obvious research application according to JOSS's definition

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).

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: Unit tests cover essential functions of the package and a reasonable range of inputs and conditions. All tests pass on the local machine.
[x] Packaging guidelines: The package conforms to the rOpenSci packaging guidelines

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:

[x] Should the author(s) deem it appropriate, I agree to be acknowledged as a package reviewer ("rev" role) in the package DESCRIPTION file.

Review Comments

I like your ideas about image processing and enjoined using your package. The package is well written and well organized overall. Just in case it would help, I want to share with you my experience/thoughts while using your package.

New to this package, I was confused about what to pass to your functions at first. I later saw a code example in your vignette page. I would recommend to include examples in your README as well so that they are more noticeable.
The description and inputs of the compress function confused me since I'm not familiar with how images are stored. It would be helpful to give an example showing the input and output for this function.
The shrink function is quite unexpected as it has the name 'shrink' but trims the image instead. I would recommend either change the function name or change its functionality.
The shrink function requires users to pass width and height values that are smaller than those of the original image, but usually users such as myself may forget to check the size of the image. To make life easier, I would recommend switch to proportions as your inputs for desired width and height.
Sorry to be picky, but your README.Rmd and README.md files do not match. I think it would be a good practice to modify your README.Rmd and knit it to get an update-to-date README.md. One advantage of using README.Rmd is that it allows you to show and run code in your README.
In the package overview part of your README, you may intend to say vector but said 'numpy array' instead.
You may want to update your dependencies in README, since the information there does not match with your DESCRIPTION file.

Thank you @Zhang-Haipeng and @flizhou for your valuable feedback. We were unable to address all your feedback due to time constraints, but here is a list of what we improved:

Provided some non-technical explanations of the compress function in the README.md under Usage.
Added examples for compress and sharpen functions in the documentation.
Added new photos for illustration in our README.md.
Changed the function name from shrink to crop.
Fixed the Usage table in README.md and added usage scenarios.
Included helper image files for users to play with directly.
Included both README.Rmd and README.md files in our repo.
Fixed the typos in README.md.

The feedback was extremely helpful, thank you again! You can check our new release here.

UBC-MDS / software-review