From 6e6fa7ce3b6a412e187f377a70042bf817c25f4e Mon Sep 17 00:00:00 2001 From: Matt Smith Date: Mon, 4 Nov 2024 16:14:25 +0000 Subject: [PATCH 1/4] updated roxygen comments and documentation. Moved several functions to internal. --- R/attach.R | 4 +-- R/get-jobs.R | 26 ++++++++++++++++--- R/get-partitions.R | 21 ++++++++++++--- R/slurmtools-package.R | 26 ++++++++++++++++++- man/check_slurm_partitions.Rd | 28 -------------------- man/get_slurm_jobs.Rd | 14 +++++++--- man/get_slurm_partitions.Rd | 12 +++++++-- man/lookup_partitions_by_cpu.Rd | 23 ----------------- man/partition_advice.Rd | 30 --------------------- man/process_slurm_partitions.Rd | 18 ------------- man/run_sinfo.Rd | 14 ---------- man/slurmtools-package.Rd | 21 --------------- man/slurmtools.Rd | 46 +++++++++++++++++++++++++++++++++ 13 files changed, 135 insertions(+), 148 deletions(-) delete mode 100644 man/check_slurm_partitions.Rd delete mode 100644 man/lookup_partitions_by_cpu.Rd delete mode 100644 man/partition_advice.Rd delete mode 100644 man/process_slurm_partitions.Rd delete mode 100644 man/run_sinfo.Rd delete mode 100644 man/slurmtools-package.Rd create mode 100644 man/slurmtools.Rd diff --git a/R/attach.R b/R/attach.R index a30665c..42ac2bc 100644 --- a/R/attach.R +++ b/R/attach.R @@ -34,7 +34,7 @@ slurmtools_options_message <- function() { } #format .onAttach message - msg <- "" + msg <- "\n\n" if (length(set_options)) { msg <- paste0( msg, @@ -59,6 +59,6 @@ slurmtools_options_message <- function() { ) } - msg + paste0(msg, "\n\n") } diff --git a/R/get-jobs.R b/R/get-jobs.R index 8ebfd4a..ccb5362 100644 --- a/R/get-jobs.R +++ b/R/get-jobs.R @@ -1,6 +1,12 @@ utils::globalVariables(c("user_name")) -# Function to parse each job into a tibble row +#' Function to parse each job into a tibble row +#' +#' @param job output from parse_jobs_json +#' +#' @return tibble of parsed jobs +#' @keywords internal +#' @noRd parse_job_to_row <- function(job) { # check options for squeue version # alter parsing based on result @@ -37,6 +43,13 @@ parse_job_to_row <- function(job) { ) } +#' Function to transform squeue --json output into named list +#' +#' @param .json output from squeue --json call +#' +#' @return list of parsed output +#' @keywords internal +#' @noRd parse_jobs_json <- function(.json) { if (!length(.json$jobs)) { empty <- tibble::tibble( @@ -57,9 +70,16 @@ parse_jobs_json <- function(.json) { purrr::list_rbind(purrr::map(.json$jobs, parse_job_to_row)) } -#' get slurm jobs -#' @param user string of user id to filter results by +#' Gets the jobs run on slurm as a tibble +#' +#' @param user optional user name to filter jobs only submitted by user +#' +#' @return a tibble containing the jobs submitted to slurm #' @export +#' +#' @examples \dontrun{ +#' get_slurm_jobs() +#' } get_slurm_jobs <- function(user = NULL){ cmd <- list(cmd = Sys.which("squeue"), args = "--json") diff --git a/R/get-partitions.R b/R/get-partitions.R index 93e8e94..722d5f9 100644 --- a/R/get-partitions.R +++ b/R/get-partitions.R @@ -5,6 +5,8 @@ partition_cache <- new.env(parent = emptyenv()) #' get list of each partition's number of CPUs and memory #' #' @return the raw partition-cpu-memory string output from `sinfo` +#' @keywords internal +#' @noRd run_sinfo <- function() { sinfobin <- Sys.which("sinfo") if (!nzchar(sinfobin)) { @@ -29,9 +31,10 @@ run_sinfo <- function() { #' [process_slurm_partitions()] #' #' @param cache optional argument to forgo caching -#' #' @return the processed table of each partition's #' number of CPUs and memory +#' @keywords internal +#' @noRd lookup_partitions_by_cpu <- function(cache = TRUE) { avail_cpus <- if(cache) { if (is.null(partition_cache[["run_sinfo"]])) { @@ -57,6 +60,8 @@ lookup_partitions_by_cpu <- function(cache = TRUE) { #' #' @return the table such that the default partition will be first #' and will have the asterisk removed +#' @keywords internal +#' @noRd process_slurm_partitions <- function(table){ all_partitions <- table$PARTITION is_default_partition <- grepl('\\*$', x = all_partitions, ) @@ -69,12 +74,16 @@ process_slurm_partitions <- function(table){ return(table) } - -#' get list of partition names for the given cluster +#' Gets the available slurm partitions the user can use. #' #' @param cache optional argument to forgo caching #' +#' @return vector of available partitions #' @export +#' +#' @examples \dontrun{ +#' get_slurm_partitions +#' } get_slurm_partitions <- function(cache = TRUE) { table <- if (cache) { if (is.null(partition_cache[["partition_by_cpu"]])) { @@ -105,6 +114,9 @@ get_slurm_partitions <- function(cache = TRUE) { #' @param cache optional argument to forgo caching #' #' @return string with suggestion upon [check_slurm_partitions()] error +#' +#' @keywords internal +#' @noRd partition_advice <- function(ncpu, partition, avail_cpus_table, cache) { sorted_table <- avail_cpus_table %>% dplyr::filter(CPUS >= ncpu) %>% dplyr::arrange(CPUS, MEMORY) @@ -126,6 +138,9 @@ partition_advice <- function(ncpu, partition, avail_cpus_table, cache) { #' @param partition name of partition requested by user #' @param cache optional argument to forgo caching #' +#' @keywords internal +#' @noRd +#' #' @examples \dontrun{ #' check_slurm_partitions(17, "cpu2mem4gb") #' check_slurm_partitions(3, "cpu2mem4gb") diff --git a/R/slurmtools-package.R b/R/slurmtools-package.R index 79055da..18dbfe3 100644 --- a/R/slurmtools-package.R +++ b/R/slurmtools-package.R @@ -1,4 +1,28 @@ -#' @keywords internal +#' slurmtools: An R package for easily submitting NONMEM jobs to slurm. +#' +#' This package aims to ease the submission and monitoring of NONMEM jobs running +#' on slurm. +#' +#' @section submitting jobs: +#' \itemize{ +#' \item \code{\link{submit_nonmem_model}}: Submits a job to slurm +#' \item \code{\link{generate_nmm_config}}: Generates a NONMEMmonitor config +#' file +#' } +#' +#' @section monitoring jobs: +#' \itemize{ +#' \item \code{\link{get_slurm_jobs}}: Gives a table of submitted jobs to slurm +#' that shows status and other information given with `squeue` +#' } +#' +#' @section slurm partitions: +#' \itemize{ +#' \item \code{\link{get_slurm_partitions}}: Gives a vector of available +#' partitions a user can submit jobs to. +#' } +#' +#' @name slurmtools "_PACKAGE" ## usethis namespace: start diff --git a/man/check_slurm_partitions.Rd b/man/check_slurm_partitions.Rd deleted file mode 100644 index c177890..0000000 --- a/man/check_slurm_partitions.Rd +++ /dev/null @@ -1,28 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/get-partitions.R -\name{check_slurm_partitions} -\alias{check_slurm_partitions} -\title{throws error if the number of requested CPUs exceeds the number of CPUs available in the requested partition} -\usage{ -check_slurm_partitions(ncpu, partition, cache = TRUE) -} -\arguments{ -\item{ncpu}{number of CPUs requested by user} - -\item{partition}{name of partition requested by user} - -\item{cache}{optional argument to forgo caching} -} -\description{ -throws error if the number of requested CPUs exceeds the number of CPUs available in the requested partition -} -\examples{ -\dontrun{ -check_slurm_partitions(17, "cpu2mem4gb") -check_slurm_partitions(3, "cpu2mem4gb") -check_slurm_partitions(5, "cpu4mem32gb") -check_slurm_partitions(5, "cpu4mem32gb") -check_slurm_partitions(100, "cpu32mem128gb") -check_slurm_partitions(2, "cpu2mem4gb") -} -} diff --git a/man/get_slurm_jobs.Rd b/man/get_slurm_jobs.Rd index 7947dc3..ff67530 100644 --- a/man/get_slurm_jobs.Rd +++ b/man/get_slurm_jobs.Rd @@ -2,13 +2,21 @@ % Please edit documentation in R/get-jobs.R \name{get_slurm_jobs} \alias{get_slurm_jobs} -\title{get slurm jobs} +\title{Gets the jobs run on slurm as a tibble} \usage{ get_slurm_jobs(user = NULL) } \arguments{ -\item{user}{string of user id to filter results by} +\item{user}{optional user name to filter jobs only submitted by user} +} +\value{ +a tibble containing the jobs submitted to slurm } \description{ -get slurm jobs +Gets the jobs run on slurm as a tibble +} +\examples{ +\dontrun{ +get_slurm_jobs() +} } diff --git a/man/get_slurm_partitions.Rd b/man/get_slurm_partitions.Rd index 66c5e11..c560ba9 100644 --- a/man/get_slurm_partitions.Rd +++ b/man/get_slurm_partitions.Rd @@ -2,13 +2,21 @@ % Please edit documentation in R/get-partitions.R \name{get_slurm_partitions} \alias{get_slurm_partitions} -\title{get list of partition names for the given cluster} +\title{Gets the available slurm partitions the user can use.} \usage{ get_slurm_partitions(cache = TRUE) } \arguments{ \item{cache}{optional argument to forgo caching} } +\value{ +vector of available partitions +} \description{ -get list of partition names for the given cluster +Gets the available slurm partitions the user can use. +} +\examples{ +\dontrun{ +get_slurm_partitions +} } diff --git a/man/lookup_partitions_by_cpu.Rd b/man/lookup_partitions_by_cpu.Rd deleted file mode 100644 index 3896480..0000000 --- a/man/lookup_partitions_by_cpu.Rd +++ /dev/null @@ -1,23 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/get-partitions.R -\name{lookup_partitions_by_cpu} -\alias{lookup_partitions_by_cpu} -\title{get table of each partition's number of CPUs and memory} -\usage{ -lookup_partitions_by_cpu(cache = TRUE) -} -\arguments{ -\item{cache}{optional argument to forgo caching} -} -\value{ -the processed table of each partition's -number of CPUs and memory -} -\description{ -\itemize{ -\item gets the raw string output from \code{\link[=run_sinfo]{run_sinfo()}} -\item converts to a data frame -\item reorders and removes \code{*} from default partition with -\code{\link[=process_slurm_partitions]{process_slurm_partitions()}} -} -} diff --git a/man/partition_advice.Rd b/man/partition_advice.Rd deleted file mode 100644 index 2fee0f1..0000000 --- a/man/partition_advice.Rd +++ /dev/null @@ -1,30 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/get-partitions.R -\name{partition_advice} -\alias{partition_advice} -\title{get partition suggestions} -\usage{ -partition_advice(ncpu, partition, avail_cpus_table, cache) -} -\arguments{ -\item{ncpu}{number of CPUs requested by user} - -\item{partition}{name of partition requested by user} - -\item{avail_cpus_table}{table of partitions with respective number of CPUs and memory} - -\item{cache}{optional argument to forgo caching} -} -\value{ -string with suggestion upon \code{\link[=check_slurm_partitions]{check_slurm_partitions()}} error -} -\description{ -In a call to \code{submit_slurm_model()}, if the number of requested CPUs exceeds -the number of CPUs available in the requested partition, -\code{\link[=check_slurm_partitions]{check_slurm_partitions()}} errors. \if{html}{\out{
}} -This function follows up with a message providing one or two suggestions for -the partition with the smallest sufficient number of CPUs and least amount -of memory. \if{html}{\out{
}} -If there are no partitions with enough CPUs to accommodate the number -requested, this function's return message clarifies this. -} diff --git a/man/process_slurm_partitions.Rd b/man/process_slurm_partitions.Rd deleted file mode 100644 index 1694d28..0000000 --- a/man/process_slurm_partitions.Rd +++ /dev/null @@ -1,18 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/get-partitions.R -\name{process_slurm_partitions} -\alias{process_slurm_partitions} -\title{manipulate partition table for usability} -\usage{ -process_slurm_partitions(table) -} -\arguments{ -\item{table}{the table created by lookup_partitions_by_cpu} -} -\value{ -the table such that the default partition will be first -and will have the asterisk removed -} -\description{ -manipulate partition table for usability -} diff --git a/man/run_sinfo.Rd b/man/run_sinfo.Rd deleted file mode 100644 index 2200d12..0000000 --- a/man/run_sinfo.Rd +++ /dev/null @@ -1,14 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/get-partitions.R -\name{run_sinfo} -\alias{run_sinfo} -\title{get list of each partition's number of CPUs and memory} -\usage{ -run_sinfo() -} -\value{ -the raw partition-cpu-memory string output from \code{sinfo} -} -\description{ -get list of each partition's number of CPUs and memory -} diff --git a/man/slurmtools-package.Rd b/man/slurmtools-package.Rd deleted file mode 100644 index d8db95f..0000000 --- a/man/slurmtools-package.Rd +++ /dev/null @@ -1,21 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/slurmtools-package.R -\docType{package} -\name{slurmtools-package} -\alias{slurmtools} -\alias{slurmtools-package} -\title{slurmtools: slurm tooling} -\description{ -What the package does (one paragraph). -} -\author{ -\strong{Maintainer}: Devin Pastoor \email{devin@a2-ai.com} - -Authors: -\itemize{ - \item Jenna Elwing \email{jenna@a2-ai.com} - \item Matthew Smith \email{matthews@a2-ai.com} -} - -} -\keyword{internal} diff --git a/man/slurmtools.Rd b/man/slurmtools.Rd new file mode 100644 index 0000000..d503999 --- /dev/null +++ b/man/slurmtools.Rd @@ -0,0 +1,46 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/slurmtools-package.R +\docType{package} +\name{slurmtools} +\alias{slurmtools-package} +\alias{slurmtools} +\title{slurmtools: An R package for easily submitting NONMEM jobs to slurm.} +\description{ +This package aims to ease the submission and monitoring of NONMEM jobs running +on slurm. +} +\section{submitting jobs}{ + +\itemize{ +\item \code{\link{submit_nonmem_model}}: Submits a job to slurm +\item \code{\link{generate_nmm_config}}: Generates a NONMEMmonitor config +file +} +} + +\section{monitoring jobs}{ + +\itemize{ +\item \code{\link{get_slurm_jobs}}: Gives a table of submitted jobs to slurm +that shows status and other information given with \code{squeue} +} +} + +\section{slurm partitions}{ + +\itemize{ +\item \code{\link{get_slurm_partitions}}: Gives a vector of available +partitions a user can submit jobs to. +} +} + +\author{ +\strong{Maintainer}: Devin Pastoor \email{devin@a2-ai.com} + +Authors: +\itemize{ + \item Jenna Elwing \email{jenna@a2-ai.com} + \item Matthew Smith \email{matthews@a2-ai.com} +} + +} From b0347e23784c116947f66ec46d9dd7293f3d7391 Mon Sep 17 00:00:00 2001 From: Matt Smith Date: Mon, 4 Nov 2024 16:15:08 +0000 Subject: [PATCH 2/4] updating version to better track development changes --- DESCRIPTION | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DESCRIPTION b/DESCRIPTION index 34e26e4..4311a60 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: slurmtools Title: slurm tooling -Version: 0.0.0.9000 +Version: 0.0.0.9001 Authors@R: c(person("Devin", "Pastoor", , "devin@a2-ai.com", role = c("aut", "cre")), person("Jenna", "Elwing", email = "jenna@a2-ai.com", role = "aut"), person("Matthew", "Smith", email = "matthews@a2-ai.com", role = "aut")) From 2536d33624d548bd3d11c91f77e4cfa7ac38c5fb Mon Sep 17 00:00:00 2001 From: Matt Smith Date: Mon, 4 Nov 2024 17:14:34 +0000 Subject: [PATCH 3/4] updating pkgdown --- R/{slurmtools-package.R => slurmtools.R} | 1 + _pkgdown.yml | 7 ++----- man/slurmtools.Rd | 2 +- vignettes/model/nonmem/submission-log/slurm-284.out | 1 + 4 files changed, 5 insertions(+), 6 deletions(-) rename R/{slurmtools-package.R => slurmtools.R} (99%) create mode 100644 vignettes/model/nonmem/submission-log/slurm-284.out diff --git a/R/slurmtools-package.R b/R/slurmtools.R similarity index 99% rename from R/slurmtools-package.R rename to R/slurmtools.R index 18dbfe3..447e20e 100644 --- a/R/slurmtools-package.R +++ b/R/slurmtools.R @@ -25,6 +25,7 @@ #' @name slurmtools "_PACKAGE" + ## usethis namespace: start #' @importFrom brio read_file #' @importFrom brio write_file diff --git a/_pkgdown.yml b/_pkgdown.yml index 917fff3..9efbffe 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -36,13 +36,10 @@ reference: - title: Data Processing Functions contents: - submit_nonmem_model + - generate_nmm_config - get_slurm_jobs - get_slurm_partitions - - check_slurm_partitions - - lookup_partitions_by_cpu - - partition_advice - - process_slurm_partitions - - run_sinfo + - slurmtools articles: - title: Vignettes diff --git a/man/slurmtools.Rd b/man/slurmtools.Rd index d503999..1a10beb 100644 --- a/man/slurmtools.Rd +++ b/man/slurmtools.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/slurmtools-package.R +% Please edit documentation in R/slurmtools.R \docType{package} \name{slurmtools} \alias{slurmtools-package} diff --git a/vignettes/model/nonmem/submission-log/slurm-284.out b/vignettes/model/nonmem/submission-log/slurm-284.out new file mode 100644 index 0000000..62010dc --- /dev/null +++ b/vignettes/model/nonmem/submission-log/slurm-284.out @@ -0,0 +1 @@ +Failed to read config.toml: Could not read config.toml: "/cluster-data/user-homes/matthews/Packages/slurmtools/vignettes/model/nonmem/1001.toml", Os { code: 2, kind: NotFound, message: "No such file or directory" } From 2b68b2178701ae9c5d12681388115d06075415a7 Mon Sep 17 00:00:00 2001 From: Matt Smith Date: Mon, 4 Nov 2024 17:24:36 +0000 Subject: [PATCH 4/4] cleaned up pkgdown --- R/slurmtools.R | 1 - _pkgdown.yml | 10 ++++++---- vignettes/model/nonmem/submission-log/slurm-284.out | 1 - vignettes/slack-alerts.Rmd | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) delete mode 100644 vignettes/model/nonmem/submission-log/slurm-284.out diff --git a/R/slurmtools.R b/R/slurmtools.R index 447e20e..18dbfe3 100644 --- a/R/slurmtools.R +++ b/R/slurmtools.R @@ -25,7 +25,6 @@ #' @name slurmtools "_PACKAGE" - ## usethis namespace: start #' @importFrom brio read_file #' @importFrom brio write_file diff --git a/_pkgdown.yml b/_pkgdown.yml index 9efbffe..379c6b0 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -12,17 +12,16 @@ navbar: left: - intro - reference + - articles right: - search - github + - lightswitch components: reference: text: Reference href: reference/index.html - github: - icon: fa-github fa-lg - href: https://github.com/a2-ai/slurmtools - intro: + articles: text: Get Started menu: - text: Running NONMEM @@ -31,6 +30,9 @@ navbar: href: articles/custom-alerts.html - text: Slack Alerts href: articles/slack-alerts.html + github: + icon: fa-github fa-lg + href: https://github.com/a2-ai/slurmtools reference: - title: Data Processing Functions diff --git a/vignettes/model/nonmem/submission-log/slurm-284.out b/vignettes/model/nonmem/submission-log/slurm-284.out deleted file mode 100644 index 62010dc..0000000 --- a/vignettes/model/nonmem/submission-log/slurm-284.out +++ /dev/null @@ -1 +0,0 @@ -Failed to read config.toml: Could not read config.toml: "/cluster-data/user-homes/matthews/Packages/slurmtools/vignettes/model/nonmem/1001.toml", Os { code: 2, kind: NotFound, message: "No such file or directory" } diff --git a/vignettes/slack-alerts.Rmd b/vignettes/slack-alerts.Rmd index 8e87cde..4292a39 100644 --- a/vignettes/slack-alerts.Rmd +++ b/vignettes/slack-alerts.Rmd @@ -1,5 +1,5 @@ --- -title: "Slack-alerts" +title: "Slack notifications with nmm" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Slack notifications with nmm} @@ -146,7 +146,7 @@ submission_nmm ``` ```{r} -slurmtools::get_slurm_jobs() +slurmtools::get_slurm_jobs(user = 'matthews') ``` ![nmm slack alerts](data/images/nmm_slack_notifications.png)