diff --git a/.Rbuildignore b/.Rbuildignore index 44d35d5..6790fd0 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -18,3 +18,4 @@ ^cran-comments\.md$ ^CRAN-SUBMISSION$ ^revdep$ +^CODE_OF_CONDUCT\.md$ diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..de7f493 --- /dev/null +++ b/.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. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..6a26081 --- /dev/null +++ b/.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. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..51e62fa --- /dev/null +++ b/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 +. + +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 +. Translations are available at . + +[homepage]: https://www.contributor-covenant.org diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..9382712 --- /dev/null +++ b/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. diff --git a/README.Rmd b/README.Rmd index a34fcce..7b4b958 100644 --- a/README.Rmd +++ b/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) -* 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) +maldipickr graphical overview + +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 diff --git a/README.md b/README.md index 3c91a92..5affab8 100644 --- a/README.md +++ b/README.md @@ -14,70 +14,31 @@ developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.re [![codecov](https://codecov.io/github/ClavelLab/maldipickr/branch/main/graph/badge.svg?token=JQABKDK2MB)](https://app.codecov.io/github/ClavelLab/maldipickr) -- Are you using the MALDI-TOF[^1] 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[^1] 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 -
- - -
+maldipickr graphical overview + +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 -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) -#> # A tibble: 6 × 7 -#> name to_pick membership cluster_size SNR peaks is_reference -#> -#> 1 species1_G2 FALSE 1 4 5.09 21 FALSE -#> 2 species2_E11 FALSE 2 2 5.54 22 FALSE -#> 3 species2_E12 TRUE 2 2 5.63 23 TRUE -#> 4 species3_F7 FALSE 1 4 4.89 26 FALSE -#> 5 species3_F8 TRUE 1 4 5.56 25 TRUE -#> 6 species3_F9 FALSE 1 4 5.40 25 FALSE -``` +- [using spectra data](#using-spectra-data) ### Using taxonomic identification report @@ -123,6 +84,40 @@ report_tbl %>% #> # bruker_hash , bruker_log ``` +### Using spectra data + +``` r +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) +#> # A tibble: 6 × 7 +#> name to_pick membership cluster_size SNR peaks is_reference +#> +#> 1 species1_G2 FALSE 1 4 5.09 21 FALSE +#> 2 species2_E11 FALSE 2 2 5.54 22 FALSE +#> 3 species2_E12 TRUE 2 2 5.63 23 TRUE +#> 4 species3_F7 FALSE 1 4 4.89 26 FALSE +#> 5 species3_F8 TRUE 1 4 5.56 25 TRUE +#> 6 species3_F9 FALSE 1 4 5.40 25 FALSE +``` + ## Installation `{maldipickr}` is available on the @@ -153,7 +148,30 @@ and showcase how to: 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 diff --git a/man/figures/maldipickr-data-flow-portrait.png b/man/figures/maldipickr-data-flow-portrait.png index e2d1fc1..a9b0451 100644 Binary files a/man/figures/maldipickr-data-flow-portrait.png and b/man/figures/maldipickr-data-flow-portrait.png differ diff --git a/man/figures/maldipickr-data-flow-portrait.svg b/man/figures/maldipickr-data-flow-portrait.svg new file mode 100644 index 0000000..54fe971 --- /dev/null +++ b/man/figures/maldipickr-data-flow-portrait.svg @@ -0,0 +1,3 @@ + + + image/svg+xml maldipickr image/svg+xml
process
spectra
named list of three objects
  • List of n processed spectra signals
  • List of n peaks m/z and intensities
  • Table of peak detection metadata
read
biotyper
report
delineate
with
identification
table
Up to ten identifications
per n spectra
identification report
pick
spectra
additional
metadata
merge
processed
spectra
intensity matrix
  • n rows as n spectra
  • p columns as p peaks
delineate
with
similarity
similarity matrix
n rows and n columns
as n spectra
clusters table
n rows as n spectra
with cluster membership
cherry-pick table
n spectra are labeled
as to be picked
for each cluster
START
END
Import
check
spectra
remove
spectra
raw spectra
List m MALDIquant
MassSpectrum objects
filtered raw spectra
List n MALDIquant
MassSpectrum objects
import
biotyper
spectra
Process
Filter identifications
using log score threshold
with R functions
Compute cosine similarity using {coop} function
Dereplicate
Legend
Input files
Data flow
Cherry-pick
or
Part of {maldipickr} package
spectra
membership
A
1
B
1
C
2
Example: 
Two clusters (AB) and (C)
Example: 
Pick A and C
raw spectra
acqu
files
csv
files
spectra data steps
identification steps
common steps
data type
features
maldipickr
function
input
output
\ No newline at end of file