Merge pull request #44 from ClavelLab/template

add issue templates and restructure the README

.Rbuildignore

@@ -18,3 +18,4 @@
 ^cran-comments\.md$
 ^CRAN-SUBMISSION$
 ^revdep$
+^CODE_OF_CONDUCT\.md$

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug report
+about: Create a report to help us improve {maldipickr}
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Please provide a minimal [reprex](https://www.tidyverse.org/help/#reprex), possibly using the small datasets included in `{maldipickr}`.
+
+```r
+# Paste here the R code to reproduce the bug
+```
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. Ubuntu, Windows]
+ - R version: (Use the output of `R.version.string`)
+ - `{maldipickr}` version: (Use `installed.packages()["maldipickr", "Version"]`)
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for {maldipickr}
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

CODE_OF_CONDUCT.md

@@ -0,0 +1,126 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at cpauvert [at] ukaachen [dot] de. 
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][https://github.com/mozilla/inclusion].
+
+For answers to common questions about this code of conduct, see the FAQ at
+<https://www.contributor-covenant.org/faq>. Translations are available at <https://www.contributor-covenant.org/translations>.
+
+[homepage]: https://www.contributor-covenant.org

CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing to {maldipickr}
+
+The following is a set of guidelines for contributing to {maldipickr}[^fusen].
+These guidelines are not strict rules. Use your best judgment, and feel free to
+propose changes to this document in a pull request, as long as you are abiding to the
+[Contributor Code of Conduct](https://clavellab.github.io/maldipickr/CODE_OF_CONDUCT.html).
+
+
+**All contribution welcomed** We are open to any contribution, from typos to new features. Thank you for taking this time! We will guide you throughout the process and make you in a safe position to contribute,
+whatever is your level in R programming.
+
+## {maldipickr} uses {fusen} with flat files (.Rmd)
+
+A note on the structure of the R package. We use the [`{fusen}`](https://thinkr-open.github.io/fusen/) package to develop. This means that multiple files of the package in `R/`, `tests/` and `vignettes/` are issued from a flat file (e.g. a `.Rmd` file).
+
+When this is the case, you will see the following warnings on top of the files:
+
+* ```
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/delineate_with_similarity.R
+```
+
+* ```
+# WARNING - Generated by {fusen} from dev/dereplicate-spectra.Rmd: do not edit by hand
+```
+
+This means that you will need to make your changes in the corresponding flat file,
+and then `inflate()` this same flat file.
+We recommend using `fusen::inflate_all()` directly so that it takes into account any modification.
+
+This way of developing is what `{fusen}` is for, if you are new to it, the [illustration on the `{fusen}` documentation is of great help](https://thinkr-open.github.io/fusen).
+
+### The case of README
+
+Changes to the `README.md` file should be done in the flat file `README.Rmd`. However, this file is not built by `{fusen}` but you need to use `devtools::build_readme()`.
+
+## Fixing typos
+
+You can fix typos, spelling mistakes, or grammatical errors in the documentation and vignettes directly using the GitHub web interface, as long as the changes are made in the _source_ file.
+This generally means you'll need to edit [roxygen2 comments](https://roxygen2.r-lib.org/articles/roxygen2.html) in the R code chunks of the vignettes flat files (`.Rmd`) in the `dev/` directory.
+You can find the `.R` file that generates the `.Rd` by reading the comment in the first line.
+
+## Bigger changes
+
+If you want to make a bigger change, it's a good idea to first reach out with an issue using the "Feature request" template for instance.
+
+If you have found a bug, please file an issue that illustrates the bug using the "Bug report" template with a minimal
+[reprex](https://www.tidyverse.org/help/#reprex). Small datasets are included in `{maldipickr}` that can be used to create the reprex.
+
+### Pull request process
+
+* Fork the package and clone onto your computer. If you haven't done this before, we recommend using `usethis::create_from_github("ClavelLab/maldipickr", fork = TRUE)`.
+* Install all development dependences with `devtools::install_dev_deps()`, and then make sure the package passes R CMD check by running `devtools::check()`.
+    If R CMD check doesn't pass cleanly, it's a good idea to ask for help before continuing.
+* Create a Git branch for your pull request (PR). We recommend using `usethis::pr_init("brief-description-of-change")` or `usethis::pr_init("fix-ISSUENUMBER-short-title")` if you are aiming to fix a specific issue.
+
+*   Make your changes
+*   Open the `dev/dev_history.R` file: `rstudioapi::navigateToFile("dev/dev_history.R")`
+Find the "# Dependencies ----" part and run the `attachment::att_amend_desc(...)` as presented there.
+This will update documentation and list of dependencies in `DESCRIPTION` with the ones needed by `{maldipickr}`.
+
+
+* Commit to git, and then create a PR by running `usethis::pr_push()`, and following the prompts in your browser.
+    The title of your PR should briefly describe the change.
+    The body of your PR should contain `Fixes #issue-number`.
+
+*  Summarize your changes to the community by editing the `NEWS.md`. We follow the style described in the [Common Changelog](https://common-changelog.org).
+
+## Code style
+
+* Commit style. Commits should start whenever possible by a verb in lower case, as if the commit title continues the sentence: "Applying this commit will...".
+
+*  New code should follow the tidyverse [style guide](https://style.tidyverse.org). You can use the [styler](https://CRAN.R-project.org/package=styler) package to apply these styles, but please don't restyle code that has nothing to do with your PR.
+
+*  We use [roxygen2](https://cran.r-project.org/package=roxygen2), with [Markdown syntax](https://cran.r-project.org/web/packages/roxygen2/vignettes/rd-formatting.html), for documentation.
+
+*  We use [testthat](https://cran.r-project.org/package=testthat) for unit tests. Contributions with test cases included are easier to accept.
+
+## Code of Conduct
+
+Please note that the fusen project is released with a [Contributor Code of Conduct](https://clavellab.github.io/maldipickr/CODE_OF_CONDUCT.html). By contributing to this project you agree to abide by its terms.
+
+[^fusen]: These guidelines are heavily inspired by the contributing guidelines of the [`{fusen}`](https://github.com/ThinkR-open/fusen) package.

README.Rmd

@@ -22,49 +22,26 @@ knitr::opts_chunk$set(
 [![codecov](https://codecov.io/github/ClavelLab/maldipickr/branch/main/graph/badge.svg?token=JQABKDK2MB)](https://app.codecov.io/github/ClavelLab/maldipickr)
 <!-- badges: end -->
 
-* Are you using the MALDI-TOF[^maldi] Biotyper to identify bacterial isolates? **Yes**
-* Do you want to select representative isolates for further experiments? **Yes**
-* Do you need fast and automated selection decisions that you can retrace? **Yes**
 
-↪ *The [`{maldipickr}`](https://github.com/ClavelLab/maldipickr) package is right for your needs!*
-The documented and tested R functions will help you dereplicate MALDI-TOF
-data and cherry-pick representative spectra of microbial isolates.
+- You are using the MALDI-TOF[^maldi] Biotyper to identify bacterial isolates
+- You want to select representative isolates for further experiments
+- You need fast and automated selection decisions that you can retrace
+
+`{maldipickr}` provides documented and tested R functions that will help you dereplicate MALDI-TOF data and cherry-pick representative spectra of microbial isolates.
+
 
 ## Graphical overview
 
-![Illustration of the data flow when using the R package {maldipickr} to cherry-pick bacterial isolates with MALDI Biotyper. It depicts the two possible approaches using either taxonomic identification reports (left) or spectra data (right)](man/figures/maldipickr-data-flow-portrait.png)
+<a href="https://raw.githubusercontent.com/ClavelLab/maldipickr/main/man/figures/maldipickr-data-flow-portrait.svg"><img src="man/figures/maldipickr-data-flow-portrait.png" align="center" height="250px" width="auto" alt="maldipickr graphical overview" /></a>
+
+Illustration (click for a bigger version) of the data flow when using `{maldipickr}` to cherry-pick bacterial isolates with MALDI Biotyper. It depicts the two possible approaches using either taxonomic identification reports (left) or spectra data (right).
 
 ## Quickstart
 
 How to **cherry-pick bacterial isolates** with MALDI Biotyper:
 
-* [using spectra data](#using-spectra-data)
 * [using taxonomic identification report](#using-taxonomic-identification-report)
-
-### Using spectra data
-
-```{r quickstart_spectra}
-library(maldipickr)
-# Set up the directory location of your spectra data
-spectra_dir <- system.file("toy-species-spectra", package = "maldipickr")
-
-# Import and process the spectra
-processed <- spectra_dir %>%
-  import_biotyper_spectra() %>%
-  process_spectra()
-
-# Delineate spectra clusters using Cosine similarity
-#  and cherry-pick one representative spectra.
-#  The chosen ones are indicated by `to_pick` column
-processed %>%
-  list() %>%
-  merge_processed_spectra() %>%
-  coop::tcosine() %>%
-  delineate_with_similarity(threshold = 0.92) %>%
-  set_reference_spectra(processed$metadata) %>%
-  pick_spectra() %>%
-  dplyr::relocate(name, to_pick)
-```
+* [using spectra data](#using-spectra-data)
 
 
 ### Using taxonomic identification report
@@ -94,6 +71,32 @@ report_tbl %>%
   dplyr::relocate(name, to_pick, bruker_species)
 ```
 
+### Using spectra data
+
+```{r quickstart_spectra}
+library(maldipickr)
+# Set up the directory location of your spectra data
+spectra_dir <- system.file("toy-species-spectra", package = "maldipickr")
+
+# Import and process the spectra
+processed <- spectra_dir %>%
+  import_biotyper_spectra() %>%
+  process_spectra()
+
+# Delineate spectra clusters using Cosine similarity
+#  and cherry-pick one representative spectra.
+#  The chosen ones are indicated by `to_pick` column
+processed %>%
+  list() %>%
+  merge_processed_spectra() %>%
+  coop::tcosine() %>%
+  delineate_with_similarity(threshold = 0.92) %>%
+  set_reference_spectra(processed$metadata) %>%
+  pick_spectra() %>%
+  dplyr::relocate(name, to_pick)
+```
+
+
 
 ## Installation
 
@@ -119,7 +122,20 @@ The comprehensive vignettes will walk you through the package functions and show
 1. [Import spectra data and identification reports from Bruker MALDI Biotyper into R](https://clavellab.github.io/maldipickr/articles/import-data-from-bruker-maldi-biotyper.html).
 2. [Process, dereplicate and cherry-pick representative spectra, from simple to complex design](https://clavellab.github.io/maldipickr/articles/dereplicate-bruker-maldi-biotyper-spectra.html).
 
-## Acknowledgments
+## Troubleshoot
+
+If something unexpected happened when using this package, please first search the [current open or closed issues](https://github.com/ClavelLab/maldipickr/issues?q=is%3Aissue++) to look for similar problems. If you are the first, you are more than welcome to open a new issue using the "Bug report" template with a minimal
+[reprex](https://www.tidyverse.org/help/#reprex).
+
+## Contribute
+
+All contributions are welcome and the [`CONTRIBUTING.md`](https://clavellab.github.io/maldipickr/CONTRIBUTING.html) documents how to participate.
+
+Please note that the [`{maldipickr}`](https://github.com/ClavelLab/maldipickr) package is released with a [Contributor Code of Conduct](https://clavellab.github.io/maldipickr/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.
+
+## Credits
+
+### Acknowledgements
 
 This R package is developed for spectra data generated by the Bruker MALDI Biotyper device. The [`{maldipickr}`](https://github.com/ClavelLab/maldipickr) package is built from a suite of Rmarkdown files using the [`{fusen}`](https://thinkr-open.github.io/fusen/) package by Rochette S (2023). It relies on:
 
@@ -132,6 +148,7 @@ The developers of this package are part of the [Clavel Lab](https://www.ukaachen
 
 The hexagonal logo was created by Charlie Pauvert and uses the [Atkinson Hyperlegible font](https://fonts.google.com/specimen/Atkinson+Hyperlegible/about) font and a color palette generated at [coolors.co](https://coolors.co/cf5c36-f0f0c9-555358).
 
+
 ## References
 
 * Gibb S & Strimmer K (2012). "MALDIquant: a versatile R package for the