Submission: Rmagine

[katieb1]

Submitting Author: Katie Birchard (@katieb1), Brendon Campbell (@brendoncampbell), Sukriti Trehan (@Sukriti1312), Trevor Kwan (@trevorkwan) Package Name: Rmagine One-Line Description of Package: Implements image filtering in R Repository Link: https://github.com/UBC-MDS/Rmagine Version submitted: 1.1.0 Editor: @kvarada
Reviewer 1: @sreejithmunthikodu
Reviewer 2: @merveshin Archive: TBD
Version accepted: TBD

---

Description

• Include a brief paragraph describing what your package does:

  This package includes four main functions that accept an image as input and apply different types of manipulations and provide a new output image as summarized below:

  • Tunnel distortion: produces an image with strong visual distortion intended to create a tunnel or pincushion effect
  • Colour filters: produces an image with different user-specified colour distortions (ex: blue tone)
  • Edge detection: identifies edges by looking at where the image brightness changes sharply, and produces a black and white image highlighting the locations of these edges
  • Vignetting: produces an image with reduced brightness around the periphery compared to the image center

Scope

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

  • [ ] Data retrieval
  • [x] Data extraction
  • [ ] Data munging
  • [ ] Data deposition
  • [ ] Reproducibility
  • [ ] Geospatial
  • [ ] Education
  • [x] Data visualization

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

  The sole purpose of this package is to provide image manipulations by extracting data from an image and applying a filter to that data. Therefore this package falls under both data extraction and data visualization.

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

  The target purpose of this package is for entertainment and image editing. Therefore the target audience is anyone who wishes to add fun and/or artistic filters to their photos.

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

  There are other individual R packages that achieve similar functionality to some of the functions contained in our package, such as imager for colour filtering. However, our package compiles these functions into one cohesive framework.

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.
• [x] 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?
• [ ] 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.

[sreejithmunthikodu]

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

[sreejithmunthikodu]

Review Comments

Installation:

• Installation was smooth without any issues.

From vignette("Rmagine"):

Warning message:
vignette ‘Rmagine’ not found 

• I was not able to access the vignettes locally.
• I was able to access the vignettes from README.md of the package. It is well written and demonstrates how the functions in the package work. My suggestion is to integrate the vignettes in the package documentation.

From help():

• Well documented with all the functions accessible with the help() function locally.

From test():

• All automated tests passed on the local machine. Great work!

From tunnel_filter() :

• The documentation says tunnel_filter function accepts argument k. But the function in the package does not accept k. I suggest modify the function or update the documentation.
• The function worked well with a variety of edge cases. Really good job at handling the exceptions.
• When I used a greyscale image, the function is returning an array of numbers in addition to the distorted image. I am not sure if this is expected. Same result with a .png image.

From colour_filters():

• The function worked well as expected even with a variety of edge cases.

From edge_detection():

• The function worked as expected.

From vignette_filter():

• The function worked as expected in all edge cases except one
• When the strength of 0 was specified, I was expecting the function to return the same image. But it gave an ambiguous error message. I suggest either update the function to handle this or update the error message.

  vignette_filter("1.png", 0)
  Error in vignette_filter("1.png", 0) : 
  Vignette strength can't be negative.

  General Comments:

• It would be better if the user could specify a target file name. If I want to generate many distorted images, for example inside a for loop, as per current implementation the generated image would overwrite the previous one.
• Overall a very good package for image augmentation. I guess if the package is updated with some more functionalities such as crop, rotate, the user could depend on the package to generate tonnes of images. The package could potentially be used for image synthesis for machine learning applications.

[merveshin]

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)

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

Estimated hours spent reviewing: 4 hours

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

In general, I like the functions you implemented. They are easy to understand and use. The documentation is sufficient to start playing with. The structure inside the functions is clear and understandable. The code was clear. Well done.

However, I have a few improvement ideas. I will group them to follow easier:

Documentation and Structure:

In ReadMe, usage information for vignette_filter function is good and helpful to onboard using this package. It could be even better if you put more examples to cover the other three functions.

Usability & Clarity

Some code lines are repeating across functions such as input validation and some lines are repeating within the function like image save statement in color_filter function. Reusing code and referring to one function would make it easier to maintain, test and change in the future. This redundancy applies to test functions too. If you can create a separate function to validate input, the repeatation in test files also can be removed.

For all four functions, it would be better if you give the user an option to pick the destination folder and file name.

For color_filter function, we specify red, green or blue tone filter, I would like to have control over the strength as well. This is just a suggestion, I think this kind of improvements can increase adoption of the library.

Testing

Unit tests are good and covering all lines. Although there are enough test cases for negative tests, the positive test case is not covering what is intended to be tested. There should be at least one happy path test where you run your function and compare it with the expected output. I suggest you store expected images in img folder and check if generated files are actually the same as them. I saw that only image sizes are compared.

Finally, this is more like a question, in all of the functions, you assumed as.array(image) statement will read always RBG image. Is it possible that the given image is already grayscale and looking for the other layer throw an error?

[Sukriti1312]

@sreejithmunthikodu Thanks for the feedback! Here are the suggested changes that we have made:

• The vignette can now be accessed locally
• Altered documentation for tunnel_filter function to remove argument k
• Corrected the error message for vignette_filter to handle strength=0
• Specified target file name to save images so that the issue of overwriting images will be resolved

Link for the latest release with incorporated changes

[Sukriti1312]

@merveshin Thank you for your feedback! Following are the changes that we have made to our package as per your suggestion:

• Applied DRY principle in colour_filters function
• Added strength parameter for colour_filters function
• Specified target file and destination folder for saving images

Link for the latest release with incorporated changes