Merge pull request #20 from Qile0317/main

merge main to cran for v1.2.1

.Rbuildignore

@@ -16,3 +16,5 @@
 ^.idea$
 [.]md$
 [.]yml$
+^\.lintr$
+^cran-comments\.md$

.github/workflows/R-CMD-check.yaml

@@ -1,8 +1,8 @@
 on:
   push:
-    branches: [main, dev, unstable]
+    branches: [main, dev]
   pull_request:
-    branches: [main, dev, unstable]
+    branches: [main, dev]
 
 name: R-CMD-check
 
@@ -21,10 +21,11 @@ jobs:
           - {os: macos-latest,   r: 'release'}
           - {os: windows-latest, r: 'release'}
           - {os: ubuntu-latest,   r: 'release'}
-
-          # check compatibility with older releases
+
+          # check compatibility with oldrel-1
+          - {os: macos-latest,   r: 'oldrel-1'}
+          - {os: windows-latest, r: 'oldrel-1'}
           - {os: ubuntu-latest,   r: 'oldrel-1'}
-          - {os: ubuntu-latest,   r: 'oldrel-2'}
 
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -2,6 +2,7 @@
 .Rhistory
 .RData
 .Ruserdata
+..Rcheck
 inst/doc
 /loc_tesdat
 devnotes.txt
@@ -18,4 +19,7 @@ a.exe
 /Meta/
 .RDataTmp
 .RDataTmp1
-.idea
+.idea
+
+# remove in future
+.lintr

CODE_OF_CONDUCT

@@ -0,0 +1,27 @@
+# Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers 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, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting `qile.yang [at] berkeley.edu`. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The leader(s) is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](contributor-covenant.org), version 1.4, available at <http://contributor-covenant.org/version/1/4>

CODE_OF_CONDUCT.md

@@ -0,0 +1,27 @@
+# Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers 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, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting `qile.yang [at] berkeley.edu`. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The leader(s) is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](contributor-covenant.org), version 1.4, available at <http://contributor-covenant.org/version/1/4>

CONTRIBUTING.md

@@ -0,0 +1,104 @@
+# Contributing to APackOfTheClones Development
+
+The goal of this guide is to help you get up and contributing to APackOfTheClones as quickly as possible. Note that this guide is a modified version of ggplot2's github `contributing.md`. The guide is divided into two main pieces:
+
+1. Filing a bug report in an issue.
+2. Suggesting a change via a pull request.
+
+Please note that APackOfTheClones is released with a [Contributor Code of Conduct](.github/CODE_OF_CONDUCT.md). By contributing to this project,
+you agree to abide by its terms.
+
+## Bug Reports
+
+When filing a bug report via [github issues](https://github.com/Qile0317/APackOfTheClones/issues), the most important thing is to include a minimal
+reproducible example if possible, so that the problem can be verified quickly, and then figure out how to fix it. There are three things you need to include to make your example reproducible: required packages, data, code.
+
+1.  **Packages** should be loaded at the top of the script, so it's easy to
+    see which ones the example needs.
+
+2.  The easiest way to include **data** is to use `dput()` to generate the R code
+    to recreate it. For example, to recreate the `mtcars` dataset in R,
+    I'd perform the following steps:
+
+       1. Run `dput(mtcars)` in R
+       2. Copy the output
+       3. In my reproducible script, type `mtcars <- ` then paste.
+
+    However, as this package intends to work with Seurat objects that tend to get massive, and the data privacy may be an issue, it is recommended to try and reproduce the bug on a potentially modified version of the example seurat object included in this package with ```data("combined_pbmc")```.
+
+3.  Spend a little bit of time ensuring that your **code** is easy for others to
+    read:
+
+    - make sure you've used spaces and your variable names are concise, but
+      informative
+
+    - use comments to indicate where your problem lies
+
+    - do your best to remove everything that is not related to the problem. 
+     The shorter your code is, the easier it is to understand.
+
+You can check you have actually made a reproducible example by starting up a
+fresh R session and pasting your script in.
+
+(Unless you've been specifically asked for it, please don't include the output
+of `sessionInfo()`. Although if you feel the issue is for sure related to versioning, go ahead.)
+
+## Pure Feature Requests
+
+Use github issues to file pure enhancements/feature requests, and describe in as much detail as possible what functionality/optimizations could be made for which functions, and potentially pseudocode or actual code for the implementation. Additionally motivate with why it would be a positive contribution for this package.
+
+## Pull requests
+
+To contribute a change, you follow these steps:
+
+1. Create a branch in git and make your changes.
+2. Push branch to github and issue pull request (PR).
+3. Discuss the pull request.
+4. Iterate until either the PR is accepted or decided that it's not
+   a good fit.
+
+Each of these steps are described in more detail below. This might feel
+overwhelming the first time you get set up, but it gets easier with practice.
+If you get stuck at any point, please reach out for help to the contributors.
+
+If you're not familiar with git or github, please start by reading <http://r-pkgs.had.co.nz/git.html>
+
+Pull requests will be evaluated against a seven point checklist:
+
+1.  __Motivation__. Your pull request should clearly and concisely motivate the
+    need for change.
+
+    Also include this motivation in `NEWS` so that when a new release of
+    APackOfTheClones comes out it's easy for users to see what's changed. Add your
+    item at the top of the file and use markdown for formatting. The
+    news item should end with `(@yourGithubUsername, #the_issue_number)`.
+
+2.  __Only related changes__. Before you submit your pull request, please
+    check to make sure that you haven't accidentally included any unrelated
+    changes. These make it harder to see exactly what's changed, and to
+    evaluate any unexpected side effects.
+
+    Each PR corresponds to a git branch, so if you expect to submit
+    multiple changes make sure to create multiple branches. If you have
+    multiple changes that depend on each other, start with the first one
+    and don't submit any others until the first one has been processed.
+
+3.  __Use the coding style of this package__. Maintaining a consistent style across the whole code base makes it much easier to jump into the code. If you're modifying existing code, a separate pull request to change the style would be greatly appreciated. In general, this would be a breaking change if it is an externally exported function, which ideally should be avoided.
+
+4.  If you're adding new parameters or a new function, you'll also need
+    to document them with [roxygen](https://github.com/klutometis/roxygen).
+    Make sure to re-run `devtools::document()` on the code before submitting.
+
+5.  If fixing a bug or adding a new feature to a non-graphical function,
+    please add a [testthat](https://github.com/r-lib/testthat) unit test.
+
+6.  If fixing a bug in the visual output, please add a visual test with
+    ```expect_doppelganger()```, but try as much as possible to reduce
+    the svg snapshot size by minimizing the number of individual polygons
+    displayed.
+
+7.  If you're adding a new graphical feature, please add a short example
+    to the appropriate function.
+
+This seems like a lot of work but don't worry if your pull request isn't perfect.
+A pull request ("PR") is a process, that require review and approval before merging.

DESCRIPTION

@@ -1,8 +1,15 @@
 Package: APackOfTheClones
 Type: Package
 Title: Visualization of Clonal Expansion for Single Cell Immune Profiles
-Version: 1.2.0
-Authors@R: c(person("Qile", "Yang", email = "qile.yang@berkeley.edu", role = c("cre","aut","cph")))
+Version: 1.2.1
+Authors@R: c(
+    person(
+        "Qile",
+        "Yang",
+        email = "qile.yang@berkeley.edu",
+        role = c("cre","aut","cph"),
+        comment = c(ORCID = "0009-0005-0148-2499")
+    ))
 Maintainer: Qile Yang <qile.yang@berkeley.edu>
 Description: Visualize clonal expansion via circle-packing. 'APackOfTheClones' extends 'scRepertoire' to produce a publication-ready visualization of clonal expansion at a single cell resolution, by representing expanded clones as differently sized circles. The method was originally implemented by Murray Christian and Ben Murrell in the following immunology study: Ma et al. (2021) <doi:10.1126/sciimmunol.abg6356>.
 BugReports: https://github.com/Qile0317/APackOfTheClones/issues/
@@ -12,7 +19,7 @@ License: MIT + file LICENSE
 Encoding: UTF-8
 Language: en-US
 LazyData: false
-Suggests: 
+Suggests:
     cowplot,
     covr,
     knitr,
@@ -23,21 +30,20 @@ Suggests:
     vdiffr
 Config/testthat/edition: 3
 Imports:
+    assertthat,
     dplyr,
     ggforce,
     ggplot2,
-    grDevices,
     hash,
     lifecycle,
-    magrittr,
     methods,
     Rcpp,
     rlang,
     Seurat,
     SeuratObject
-RoxygenNote: 7.3.1
+RoxygenNote: 7.3.2
 URL: https://qile0317.github.io/APackOfTheClones/
-LinkingTo: 
+LinkingTo:
     Rcpp
 Roxygen: list(markdown = TRUE)
 VignetteBuilder: knitr

NAMESPACE

@@ -20,5 +20,7 @@ export(renameApotcRun)
 export(showCloneHighlight)
 export(vizAPOTC)
 importFrom(Rcpp,sourceCpp)
-importFrom(magrittr,"%>%")
+importFrom(assertthat,assert_that)
+importFrom(assertthat,validate_that)
+importFrom(dplyr,"%>%")
 useDynLib(APackOfTheClones, .registration = TRUE)

NEWS.md

@@ -1,3 +1,19 @@
+# APackOfTheClones 1.2.1
+
+## Additions
+
+- Add code of conduct and contributing guidelines in the package source code.
+- Add `assertthat` in imports.
+
+## Changes
+
+- The main change in this patch is a minor alteration in the circle packing algorithm that should result in packings acting slightly more consistent across different physical systems. This may result in slightly different circle placements in the clonal expansion plot, but the overall structure should remain the same. This is pretty much only noticeable in the case of extremely small testing datasets, which is why this is a patch version. However, it is very possible that the same seurat object will produce a slightly different packing than before.
+- updated citation information upon calling `citation("APackOfTheClones")`: the package as of this patch version is undergoing review in the [journal of open source software](https://joss.theoj.org/papers/eb9d2b2fc3ffb1d440bd7120b66f1f71).
+- Updated the `combined_pbmc` dataset to be up-to-date with the latest version of `Seurat`.
+- Spelling & minor fixes / updates to various functions, documentation.
+- Removed package startup deprecation message for returning users of version `0.1.x`.
+- Removed the explicit `magrittr` dependency.
+
 # APackOfTheClones 1.2.0
 
 ## Additions

R/APOTCPlot.R

@@ -4,14 +4,14 @@
 #' `r lifecycle::badge("stable")`
 #'
 #' Given a seurat object with an 'apotc' (APackOfTheClones) object
-#' from running [RunAPOTC], this function will read the information and return
+#' from running [RunAPOTC()], this function will read the information and return
 #' a customizable ggplot2 object of the clonal expansion with a circle size
 #' legend. If the user is unhappy about certain aspects of the plot, many
 #' parameters can be adjusted with the [AdjustAPOTC] function.
 #'
 #' The specific APackOfTheClones run to be plotted can be identified in two
 #' ways: either by inputting the `run_id` associated with the run that was
-#' either defined / auto-generated during [RunAPOTC], or by inputting the
+#' either defined / auto-generated during [RunAPOTC()], or by inputting the
 #' `reduction_base`, `clonecall`, `extra_filter` and any other keyword arguments
 #' that corresponded to the run. Its heavily recommended to use the `run_id`.
 #' If none of these parameters are inputted, the function defaults to returning
@@ -20,7 +20,7 @@
 #' @inheritParams RunAPOTC
 #'
 #' @param seurat_obj A seurat object that has been integrated with clonotype
-#' data and has had a valid run of [RunAPOTC].
+#' data and has had a valid run of [RunAPOTC()].
 #' @param show_shared The output of [getSharedClones] can be inputted here,
 #' and the resulting plot will overlay lines between clone circles if that
 #' clonotype is common between clusters. Note that the input ***must*** be

R/APackOfTheClones-package.R

@@ -2,7 +2,8 @@
 "_PACKAGE"
 
 ## usethis namespace: start
-#' @importFrom magrittr %>%
+#' @importFrom assertthat assert_that validate_that
+#' @importFrom dplyr %>%
 #' @importFrom Rcpp sourceCpp
 #' @useDynLib APackOfTheClones, .registration = TRUE
 ## usethis namespace: end

R/AdjustAPOTC.R

@@ -6,9 +6,9 @@
 #' `r lifecycle::badge("stable")`
 #'
 #' If the user is unsatisfied with the clonal expansion plot that
-#' was generated from `RunAPOTC` and `APOTCPlot`, this function has a range of
+#' was generated from [RunAPOTC()] and [APOTCPlot()], this function has a range of
 #' arguments to modify the data and/or parameters of the visualization. Note
-#' that some of the arguments may conflict with eachother.
+#' that some of the arguments may conflict with each other.
 #'
 #' @inheritParams RunAPOTC
 #'

R/ApotcClonalNetwork.R

@@ -1,6 +1,3 @@
-# TODO matrix/heatmap visualization for number of shared clones
-# TODO somehow take into account sizes of shared clones
-
 #' @title Compute a list of clonotypes that are shared between seurat clusters
 #'
 #' @description
@@ -15,7 +12,7 @@
 #'
 #' If `run_id` is inputted, then the function will attempt to get the shared
 #' clonotypes from the corresponding APackOfTheClones run generated from
-#' [RunAPOTC]. Otherwise, it will use the filtering / subsetting parameters
+#' [RunAPOTC()]. Otherwise, it will use the filtering / subsetting parameters
 #' to generate the shared clones.
 #'
 #' @inheritParams RunAPOTC
@@ -197,19 +194,6 @@ filter_top_by_cluster <- function(clone_sizes, top_clones) {
     })
 }
 
-# # TODO - there needs to be a 4 way intersection
-# filter_min_clones_if_needed <- function(
-#     clone_sizes, min_size, min_size_per_cluster
-# ) {
-#     clone_sizes %>% filter_clonesize_2way_if_need(
-
-#     )
-# }
-
-# filter_min_clones <- function(clone_sizes, min_size) { # integer or float in (0,1)
-
-# }
-
 get_raw_shared_clones <- function(clustered_clone_sizes, zero_indexed = FALSE) {
 
     if (is_list_of_empty_tables(clustered_clone_sizes)) return(list())
@@ -263,7 +247,7 @@ filter_shared_if_needed <- function(
 }
 
 filter_top_shared <- function(shared_clones, raw_clone_sizes, top) {
-    
+
     if (is.null(top) || is_empty(shared_clones)) return(shared_clones)
 
     filter_top_shared_w_clone_table(
@@ -435,7 +419,7 @@ process_link_width <- function(apotc_obj, link_width, verbose) {
 }
 
 estimate_link_width <- function(apotc_obj) {
-    3 * get_clone_scale_factor(apotc_obj) #TODO improve
+    3 * get_clone_scale_factor(apotc_obj) # TODO improve
 }
 
 # internal dispatch function to get a dataframe of line connections