Merge pull request #18 from Qile0317/dev

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

@@ -5,42 +5,42 @@ The goal of this guide is to help you get up and contributing to APackOfTheClone
 1. Filing a bug report in an issue.
 2. Suggesting a change via a pull request.
 
-Please note that ggplot2 is released with a [Contributor Code of Conduct](.github/CODE_OF_CONDUCT.md). By contributing to this project, 
+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 
+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 
+
+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.  
+
+    - 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 
+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 
+(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
@@ -57,8 +57,8 @@ To contribute a change, you follow these steps:
 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. 
+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>
@@ -69,7 +69,7 @@ Pull requests will be evaluated against a seven point checklist:
     need for change.
 
     Also include this motivation in `NEWS` so that when a new release of
-    ggplot2 comes out it's easy for users to see what's changed. Add your
+    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)`.
 

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

R/ApotcData.R

@@ -83,6 +83,14 @@ initializeApotcData <- function(
 # __active.ident__ that is guaranteed to be a factor with unguaranteed level type
 set_meta_ident_col <- function(seurat_obj, alt_ident) {
 
+    if ("__active.ident__" %in% colnames(seurat_obj@meta.data)) {
+		stop(
+			"Due to the current implementation of APackOfTheClones, ",
+			"it uses a temporary column in the metadata called ",
+			"'__active.ident__'. Please rename or remove this column."
+		)
+	}
+
     if (is.null(alt_ident)) {
         seurat_obj@meta.data[["__active.ident__"]] <- seurat_obj@active.ident
         return(seurat_obj)
@@ -117,6 +125,7 @@ addIdentsLabelsColors <- function(apotc_obj, seurat_obj) {
 
 # important function to be ran after setting meta ident col
 # to merge that temporary column into seurat_clusters column
+# removes the __active.ident__ metadata column
 ident_into_seurat_clusters <- function(seurat_obj) {
     idents <- seurat_obj@meta.data[["__active.ident__"]]
     seurat_obj@meta.data[["__active.ident__"]] <- NULL
@@ -241,7 +250,7 @@ match_index <- function(apotc_obj, index) {
 			return(index)
 		}
 		stop(call. = FALSE,
-			"Some or all indices in `", varname, "` ", #FIXME likely wrong varname
+			"Some or all indices in `", varname, "` ",
 			"are out of bounds of the APackOfTheClones Run."
 		)
 	}
@@ -324,6 +333,7 @@ get_unique_clonotypes <- function(x) {
 	unique(unlist(lapply(unname(get_raw_clone_sizes(x)), names)))
 }
 
+# assumes raw clone sizes are not empty
 get_processed_clone_sizes <- function(apotc_obj) {
   raw_tabled_clone_sizes <- get_raw_clone_sizes(apotc_obj)
   processed_sizes <- init_list(get_num_clusters(apotc_obj), list())