From 8f2487d7726c11ee9c616cb589843e4822d661c1 Mon Sep 17 00:00:00 2001 From: lshep Date: Wed, 20 Nov 2024 14:22:47 +0000 Subject: [PATCH] =?UTF-8?q?Deploying=20to=20gh-pages=20from=20@=20Biocondu?= =?UTF-8?q?ctor/pkgrevdocs@6f510ab68e498e0ff557a158b052c77febd9e2d0=20?= =?UTF-8?q?=F0=9F=9A=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- description.html | 3 ++- r-code.html | 30 +++++++++++++++++++++--------- search.json | 2 +- sysdep.html | 7 +++++-- 4 files changed, 29 insertions(+), 13 deletions(-) diff --git a/description.html b/description.html index 44ee8e2..e3adacb 100644 --- a/description.html +++ b/description.html @@ -265,7 +265,8 @@

be included to document the process. If a user facing README is included it is also recommended to document the process there; do not try to install a dependency for a user anywhere in the package (i.e. readme, r code, man pages, -vignette). You may show instructions only in unevaluated sections.

+vignette). You may show instructions only in unevaluated sections. See also +Additional files and dependencies

diff --git a/r-code.html b/r-code.html index d85ac7d..73fbd3a 100644 --- a/r-code.html +++ b/r-code.html @@ -329,16 +329,28 @@

15.2.6.5 Additional files and dependencies

-

Do NOT install anything on a users system.

-

System dependencies, applications, and additionally needed packages should be -assumed already present on the user’s system.

-

If necessary, package maintainers should provide instructions for download and -setup, but should not execute those instructions on behalf of a -user. Complicated or additional system dependency instructions could be part of -the README file and/or INSTALL file. All package -dependencies must actively be on CRAN or Bioconductor.

+

Do NOT install anything on a users system! System dependencies, applications, +and additionally needed packages should be assumed already present on the user’s +system.

+

Direct calls to external commands via +system() or system2() are not ideal so should only be used when there is no +other alternative. For example, if a CRAN or Bioconductor package already +provides the functionality that you are after, you should use that instead.

+

Now if your package absolutely must rely on external software then you +need to make sure that those requirements are listed in +the SystemRequirements field of the DESCRIPTION file of the package. These +requirements should be “reasonable” requirements, that is, trusted software +only, open source, and relatively easy to install.

+

Additionally we ask that the package contains an INSTALL file (in the +top-level folder) that provides instructions for installing the external +software on the 3 major OS that we support: Linux, Windows, and Mac. This +will not only help your users get the external software on their machines, +but it will also help us install it on the build machines if it’s not +already there.

All system and package dependencies should be the latest publically available -version.

+version. All package dependencies must actively be on CRAN or +Bioconductor. Bioconductor will not recognize Remotes in Description and will +not install a lower version of a package or dependency.

diff --git a/search.json b/search.json index 97dbb9a..1d96dc5 100644 --- a/search.json +++ b/search.json @@ -1 +1 @@ -[{"path":"index.html","id":"welcome","chapter":"Welcome","heading":"Welcome","text":"","code":""},{"path":"index.html","id":"intro","chapter":"Welcome","heading":"Introduction","text":"Bioconductor project promotes high-quality, well documented, interoperable software.\nguidelines help achieve objective; meant put undue\nburden package authors, authors difficultly satisfying guidelines\nseek advice bioc-devel mailing list.Package maintainers urged follow guidelines closely possible\ndeveloping Bioconductor packages.General instructions producing R packages can found Writing R\nExtensions manual, available within \n(RShowDoc(\"R-exts\")) R website.Remember minimum requirements package acceptance \npackage still subject guidelines formal technical\nreview trained Bioconductor package reviewer .","code":""},{"path":"index.html","id":"contribute","chapter":"Welcome","heading":"Contribute","text":"book open-source hosted https://github.com/Bioconductor/pkgrevdocs.\nContributions welcome encouraged form forks pull requests.","code":""},{"path":"submission-overview.html","id":"submission-overview","chapter":"Overview","heading":"Overview","text":"following page gives overview submission process along key\nprinciples follow. See also Package Guidelines \npackage specific guidelines requirement \nBioconductor new package submission tracker.","code":""},{"path":"bioconductor-package-submissions.html","id":"bioconductor-package-submissions","chapter":"1 Bioconductor Package Submissions","heading":"1 Bioconductor Package Submissions","text":"IntroductionTypes PackagesPackage Naming PolicyAuthor/Maintainer ExpectationsSubmissionExperiment data packageAnnotation packageWorkflow packageReview ProcessFollowing AcceptanceAdditional Support","code":""},{"path":"bioconductor-package-submissions.html","id":"subintro","chapter":"1 Bioconductor Package Submissions","heading":"1.1 Introduction","text":"submit package Bioconductor package :Address areas high-throughput genomic analysis, e.g., sequencing,\nexpression microarrays, flow cytometry, mass spectrometry,\nimage analysis; see biocViews.Interoperate Bioconductor packages re-using common data\nstructures (see Common Bioconductor Methods Classes) \nexisting infrastructure (e.g., rtracklayer::import() input common\ngenomic files).Adopt software best practices enable reproducible research \nuse, full documentation vignettes (including fully\nevaluated code) well commitment long-term user support\nBioconductor support site.exist CRAN. package can submitted one .Comply Package Guidelines.package depend package (version package)\n(yet) available CRAN Bioconductor. package work\nwhatever current version package publically available.","code":""},{"path":"bioconductor-package-submissions.html","id":"type","chapter":"1 Bioconductor Package Submissions","heading":"1.2 Types of Packages","text":"Bioconductor packages broadly defined four main package types:\nSoftware, Experiment Data,\nAnnotation Workflow.Software Packages. packages contributed users software\npackages. Software packages provide implementation algorithms\n(e.g. statistical analysis), access resources (e.g. biomart, NCBI) \nvisualizations (e.g. volcano plots, pathways plots). Instructions creating\nSoftware packages can found : Package guidelines.Software Packages. packages contributed users software\npackages. Software packages provide implementation algorithms\n(e.g. statistical analysis), access resources (e.g. biomart, NCBI) \nvisualizations (e.g. volcano plots, pathways plots). Instructions creating\nSoftware packages can found : Package guidelines.Annotation packages database-like packages provide\ninformation linking identifiers (e.g., Entrez gene names Affymetrix\nprobe ids) information (e.g., chromosomal location, Gene\nOntology category). also encouraged utilize AnnotationHub \nstorage access large raw data files conversion \nstandard R formats. Instructions adding data AnnotationHub \ndesigning annotation package use AnnotationHub can found :\nCreate Hub Package.Annotation packages database-like packages provide\ninformation linking identifiers (e.g., Entrez gene names Affymetrix\nprobe ids) information (e.g., chromosomal location, Gene\nOntology category). also encouraged utilize AnnotationHub \nstorage access large raw data files conversion \nstandard R formats. Instructions adding data AnnotationHub \ndesigning annotation package use AnnotationHub can found :\nCreate Hub Package.Experiment data packages provide data sets used,\noften software packages, illustrate particular analyses. packages\ncontain curated data experiment, teaching course publication \ncases contain single data set. also encouraged utilize\nExperimentHub storage access larger data files. ExperimentHub \nalso particularly useful hosting collections related data sets.\nInstructions adding data ExperimentHub designing experiment data\npackage use ExperimentHub can found :\nCreate Hub Package.Experiment data packages provide data sets used,\noften software packages, illustrate particular analyses. packages\ncontain curated data experiment, teaching course publication \ncases contain single data set. also encouraged utilize\nExperimentHub storage access larger data files. ExperimentHub \nalso particularly useful hosting collections related data sets.\nInstructions adding data ExperimentHub designing experiment data\npackage use ExperimentHub can found :\nCreate Hub Package.Workflow packages contain vignettes describe \nbioinformatics workflow involves multiple Bioconductor packages. \nvignettes usually extensive vignettes accompany\nsoftware packages. packages need man/ R/ directories \ndata/ directory ideally workflows make use existing data \nBioconductor package. See development section Workflows \ndetails.Workflow packages contain vignettes describe \nbioinformatics workflow involves multiple Bioconductor packages. \nvignettes usually extensive vignettes accompany\nsoftware packages. packages need man/ R/ directories \ndata/ directory ideally workflows make use existing data \nBioconductor package. See development section Workflows \ndetails.See Package Guidelines details package format syntax.","code":""},{"path":"bioconductor-package-submissions.html","id":"naming","chapter":"1 Bioconductor Package Submissions","heading":"1.3 Package Naming Policy","text":"Package naming:Ownership package name. Bioconductor follows CRAN’s\npolicy requiring contributors give right use package name\nBioconductor time submission, Bioconductor team can orphan\npackage allow another maintainer take event \npackage contributor discontinues package maintenance. See Bioconductor’s package\nend--life policy details.Ownership package name. Bioconductor follows CRAN’s\npolicy requiring contributors give right use package name\nBioconductor time submission, Bioconductor team can orphan\npackage allow another maintainer take event \npackage contributor discontinues package maintenance. See Bioconductor’s package\nend--life policy details.Uniqueness package name. Packages named way \nconflict (irrespective case) current past BIOCONDUCTOR package,\ncurrent past CRAN package.Uniqueness package name. Packages named way \nconflict (irrespective case) current past BIOCONDUCTOR package,\ncurrent past CRAN package.See Package naming guidelines guidelines.","code":""},{"path":"bioconductor-package-submissions.html","id":"author","chapter":"1 Bioconductor Package Submissions","heading":"1.4 Author / Maintainer Expectations","text":"Acceptance packages Bioconductor brings ongoing\npackage maintenance responsibilities. Package authors expected :Follow Bioconductor guidelines\ninclude standard guidelines, version numbering,\ncoding style, code performance\nrequirements, memory usage, using\nexisting data classes, requirements described\n.Follow Bioconductor guidelinesThese include standard guidelines, version numbering,\ncoding style, code performance\nrequirements, memory usage, using\nexisting data classes, requirements described\n.Follow release cycle Bioconductor\ntwo releases year, around April October. \nrelease schedule indicate timetables \ndeadlines release. release cycle typically produces two\nversions packages, ‘devel’ ‘release’. important familiar\nbranch concepts. package accepted, \ninitially ‘devel’ branch. current devel branch becomes \nnext release. users expected use release branch, \nimmediately access package next release.\nBug fixes can fixed branches, new features \nadded ‘devel’ branch.Follow release cycle BioconductorThere two releases year, around April October. \nrelease schedule indicate timetables \ndeadlines release. release cycle typically produces two\nversions packages, ‘devel’ ‘release’. important familiar\nbranch concepts. package accepted, \ninitially ‘devel’ branch. current devel branch becomes \nnext release. users expected use release branch, \nimmediately access package next release.\nBug fixes can fixed branches, new features \nadded ‘devel’ branch.Maintain package using version control\nRealize Bioconductor, unlike CRAN, maintains package source code\ngit version control. means make changes \npackage using git. package accepted, receive\ninstructions typical git operations (see \nacceptance section). Package maintenance software\nrelease cycles, including prompt updates software documentation,\nneeded due possible underlying changes R /package\ndependencies.Maintain package using version controlRealize Bioconductor, unlike CRAN, maintains package source code\ngit version control. means make changes \npackage using git. package accepted, receive\ninstructions typical git operations (see \nacceptance section). Package maintenance software\nrelease cycles, including prompt updates software documentation,\nneeded due possible underlying changes R /package\ndependencies.Check Build Reports Fix Issues Promptly\nBioconductor weekly daily build reports package types. \nmaintainers responsibility check build reports respond \nERROR/Warning/Notes produced install, build, check process \npackage. maintainer receive automatic build notifications \npackage starts fail linux BBS-noreply@bioconductor.org;\nmaintainers check emails email address can delivered.Check Build Reports Fix Issues PromptlyBioconductor weekly daily build reports package types. \nmaintainers responsibility check build reports respond \nERROR/Warning/Notes produced install, build, check process \npackage. maintainer receive automatic build notifications \npackage starts fail linux BBS-noreply@bioconductor.org;\nmaintainers check emails email address can delivered.Subscribe bioc-devel mailing list\nBioconductor team communicates developers list.\nalso good channel communicate changes developers.\nAddressing Bioconductor team requests timely manner guarantees \npackage remains available Bioconductor.Subscribe bioc-devel mailing listThe Bioconductor team communicates developers list.\nalso good channel communicate changes developers.\nAddressing Bioconductor team requests timely manner guarantees \npackage remains available Bioconductor.Register use support site\nsupport site official support channel users. Users even\ndevelopers may ask questions regarding package platform.\nsure include packages maintain “Watched Tags”\nsection support site profile. notify questions\nposted regarding package(s).\nimportant promptly respond bug reports questions either \nBioconductor support site post directly developers.\nmaintainers prefer indicate BugReports: field package’s\nDESCRIPTION file. field indicates particular web page submitting\nbug reports questions.Register use support siteThe support site official support channel users. Users even\ndevelopers may ask questions regarding package platform.\nsure include packages maintain “Watched Tags”\nsection support site profile. notify questions\nposted regarding package(s).\nimportant promptly respond bug reports questions either \nBioconductor support site post directly developers.\nmaintainers prefer indicate BugReports: field package’s\nDESCRIPTION file. field indicates particular web page submitting\nbug reports questions.Ensure maintainer email DESCRIPTIONS stays accurate \nreachable. maintainer email DESCRIPTION definitive contact\nBioconductor use. important keep email --date \nensure can contact package failing notify \nimportant upcoming impactful events. email reachable \npackage jeopardy removal.Ensure maintainer email DESCRIPTIONS stays accurate \nreachable. maintainer email DESCRIPTION definitive contact\nBioconductor use. important keep email --date \nensure can contact package failing notify \nimportant upcoming impactful events. email reachable \npackage jeopardy removal.","code":""},{"path":"bioconductor-package-submissions.html","id":"submission","chapter":"1 Bioconductor Package Submissions","heading":"1.5 Submission","text":"Read follow full Contributor Guidelines section.Read follow full Contributor Guidelines section.Submit opening new issue Bioconductor\nContributions repository, following guidelines \nREADME.md file.\nAssuming package GitHub Repository \ndefault branch, add link repository \nissue opening. specify alternative branches; \ndefault branch utilized. default branch must contain package\ncode. files directories applications (Github Actions,\ndevtool, etc) different branch. submitting two\nhighly related packages circular dependent packages please see\n. lighter dependent package can installed without\ndependency submitted first; generally associated data\npackage software package.Submit opening new issue Bioconductor\nContributions repository, following guidelines \nREADME.md file.\nAssuming package GitHub Repository \ndefault branch, add link repository \nissue opening. specify alternative branches; \ndefault branch utilized. default branch must contain package\ncode. files directories applications (Github Actions,\ndevtool, etc) different branch. submitting two\nhighly related packages circular dependent packages please see\n. lighter dependent package can installed without\ndependency submitted first; generally associated data\npackage software package.","code":""},{"path":"bioconductor-package-submissions.html","id":"experPackage","chapter":"1 Bioconductor Package Submissions","heading":"1.6 Experiment Data Packages","text":"Experimental data packages contain data specific particular\nanalysis experiment. often accompany software package \nuse examples vignettes general updated\nregularly. need general subset data workflows \nexamples first check AnnotationHub resource available files\n(e.g., BAM, FASTA, BigWig, etc.) ExperimentHub available processed\nexample data set already included Bioconductor. current files data\nsets appropriate consider associated Experiment Data Package \nutilizes ExperimentHub.associated data package software package,\nplease create separate issue tracker repository\n. Instead, please add data package repository \nissue software package. process \ndocumented . Generally data package submitted first.HubPub package helpful creating template\nhub package. vignette Create Hub Package provides full details.","code":""},{"path":"bioconductor-package-submissions.html","id":"annPackage","chapter":"1 Bioconductor Package Submissions","heading":"1.7 Annotation Packages","text":"Annotation packages contain lightly non-curated data public\nsource updated Bioconductor release (every 6\nmonths). source general annotation one many\norganisms specific particular experiment. \npossible, support select() interface \nAnnotationDbi.Annotation packages posted tracker repository.\nInstead send email packages@bioconductor.org \ndescription proposed annotation package instructions\nsend package provided. Whenever possible Annotation\nPackages use AnnotationHub managing\nfiles.HubPub package helpful creating template\nhub package. vignette Create Hub Package provides full details.","code":""},{"path":"bioconductor-package-submissions.html","id":"workPackage","chapter":"1 Bioconductor Package Submissions","heading":"1.8 Workflow Packages","text":"Workflow packages contain vignettes describe bioinformatics workflow \ninvolves multiple Bioconductor packages. vignettes usually \nextensive vignettes accompany software packages. packages \nneed man/ R/ directories data/ directory ideally workflows make\nuse existing data Bioconductor package. See development section \nWorkflows details","code":""},{"path":"bioconductor-package-submissions.html","id":"whattoexpect","chapter":"1 Bioconductor Package Submissions","heading":"1.9 Review Process","text":"new package initially labeled 1. awaiting moderation.\nBioconductor team member take brief look \npackage, ensure anything malicious \ninappropriate. Packages pass stage labelled\npre-check passed.new package initially labeled 1. awaiting moderation.\nBioconductor team member take brief look \npackage, ensure anything malicious \ninappropriate. Packages pass stage labelled\npre-check passed.moderator add package repository \ngit.bioconductor.org git server, copy SSH keys github\naccount BiocCredentials application application issue labelled\npre-review.\nCHANGES PACKAGE must pushed \ngit.bioconductor.org repository created step. See New package\nworkflow instructions pushing changes git.bioconductor.org\nrepository.moderator add package repository \ngit.bioconductor.org git server, copy SSH keys github\naccount BiocCredentials application application issue labelled\npre-review.CHANGES PACKAGE must pushed \ngit.bioconductor.org repository created step. See New package\nworkflow instructions pushing changes git.bioconductor.org\nrepository.package submitted Bioconductor build\nsystem (BBS). system check package GitHub move \ngit.bioconductor.org git server. Please familiarize \ngit git.bioconductor.org versions (BBS) \nalways use. run R CMD build create ‘tarball’ source code,\nvignettes, man pages. run R CMD check tarball,\nensure package conforms standard R programming best\npractices. Bioconductor chosen utilize custom R CMD check\nenvironment; See R CMD check environment details. Finally, \nbuild system run BiocCheckGitClone() BiocCheck('new-package'=TRUE) ensure \npackage conforms Bioconductor BiocCheck\nstandards. system perform steps using ‘devel’\nversion Bioconductor, three platforms\n(Linux, Mac OS X, Windows). steps complete, link \nbuild report appended new package issue. Avoid surprises \nrunning checks computer, ‘devel’ version\nBioconductor, submitting package.package submitted Bioconductor build\nsystem (BBS). system check package GitHub move \ngit.bioconductor.org git server. Please familiarize \ngit git.bioconductor.org versions (BBS) \nalways use. run R CMD build create ‘tarball’ source code,\nvignettes, man pages. run R CMD check tarball,\nensure package conforms standard R programming best\npractices. Bioconductor chosen utilize custom R CMD check\nenvironment; See R CMD check environment details. Finally, \nbuild system run BiocCheckGitClone() BiocCheck('new-package'=TRUE) ensure \npackage conforms Bioconductor BiocCheck\nstandards. system perform steps using ‘devel’\nversion Bioconductor, three platforms\n(Linux, Mac OS X, Windows). steps complete, link \nbuild report appended new package issue. Avoid surprises \nrunning checks computer, ‘devel’ version\nBioconductor, submitting package.build report indicates problems, modify package \ncommit changes git.bioconductor.org version package \ndescribed new package git workflow. \nproblems understand, seek help \nbioc-devel mailing list.build report indicates problems, modify package \ncommit changes git.bioconductor.org version package \ndescribed new package git workflow. \nproblems understand, seek help \nbioc-devel mailing list.trigger new build, include version bump commit, e.g.,\nVersion: 0.99.0 Version: 0.99.1. Pre-release versions utilize \n0.99.z format. accepted released, package’s version number\nautomatically incremented 1.0.0.trigger new build, include version bump commit, e.g.,\nVersion: 0.99.0 Version: 0.99.1. Pre-release versions utilize \n0.99.z format. accepted released, package’s version number\nautomatically incremented 1.0.0.pre-review process identified larger issues \npackage, label 3e. pending pre-review changes specific flag \npackage issue assigned. Please address pre-review identified\nissues comment back package administrators re-evaluate.pre-review process identified larger issues \npackage, label 3e. pending pre-review changes specific flag \npackage issue assigned. Please address pre-review identified\nissues comment back package administrators re-evaluate.package builds checks without errors (avoidable)\nwarnings, package assigned reviewer. package \nlabelled 2. Review progress.package builds checks without errors (avoidable)\nwarnings, package assigned reviewer. package \nlabelled 2. Review progress.reviewer provide technical review package. \nBioconductor developers users domain expertise encouraged \nprovide additional community commentary. Reviewers add comments \nissue created.reviewer provide technical review package. \nBioconductor developers users domain expertise encouraged \nprovide additional community commentary. Reviewers add comments \nissue created.Please courteous package reviewers always follow \nBioconductor Code Conduct correspondence. Please allow 2-3 weeks\nreviewers assess package.Please courteous package reviewers always follow \nBioconductor Code Conduct correspondence. Please allow 2-3 weeks\nreviewers assess package.Respond issues raised reviewers. must respond \nprimary reviewer, strongly encouraged consider\ncommunity commentary. Typically response involve code\nmodifications; commit default branch git.bioconductor.org. \naddressed concerns, add comment issue created step 2\nexplain response.Respond issues raised reviewers. must respond \nprimary reviewer, strongly encouraged consider\ncommunity commentary. Typically response involve code\nmodifications; commit default branch git.bioconductor.org. \naddressed concerns, add comment issue created step 2\nexplain response.reviewer assess responses, perhaps suggesting \nmodifications clarification. reviewer accept \npackage inclusion Bioconductor, decline . label\n2. review progress replaced 3a. accepted \n3b. declined.reviewer assess responses, perhaps suggesting \nmodifications clarification. reviewer accept \npackage inclusion Bioconductor, decline . label\n2. review progress replaced 3a. accepted \n3b. declined.package accepted, added Bioconductor’s\nnightly ‘devel’ builds. packages ‘devel’ branch repository\n‘released’ user community every six months, \napproximately April October.package accepted, added Bioconductor’s\nnightly ‘devel’ builds. packages ‘devel’ branch repository\n‘released’ user community every six months, \napproximately April October.review process complete, issue created \nclosed. updates package \nBioconductor Git Server.review process complete, issue created \nclosed. updates package \nBioconductor Git Server.Please mindful reviewers volunteers package reviews \nresponsibility Bioconductor team members. like see \nreview process progress updates submitter comments \nreviewer within 2-3 weeks. entire review process typically takes 2\n6 weeks. response 3 4 weeks, package reviewers may\nclose issue updates, changes, /commentary received.","code":""},{"path":"bioconductor-package-submissions.html","id":"afteraccept","chapter":"1 Bioconductor Package Submissions","heading":"1.10 Following Acceptance","text":"Following acceptance package:Packages accepted tracker repository added ‘devel’\nbranch Bioconductor GIT repository, current version\nnumber accepted package.Packages built Bioconductor nightly build\nprocess. -demand builds accepted packages occur. Please see \nbuild reports often different package types built. \nchanges pushed ‘devel’ version package can take 24-28 hours \nappear. See build timings. build successful, package \n‘landing page’ created, package made available users\n‘devel’ branch Bioconductor via BiocManager::install().Changes package (), done version \nBioconductor git server.Developers bump z portion version number every\ntime commit changes package, following \nVersion numbering guidelines. developers don’t\nbump version, changes made package propagate\nBioconductor web site package repository.Devlopers make sure maintainer email DESCRIPTION stays\naccurate reachable.","code":""},{"path":"bioconductor-package-submissions.html","id":"support","chapter":"1 Bioconductor Package Submissions","heading":"1.11 Additional Support","text":"eager enhance quality interoperability \nBioconductor software provide additional support \nrequested package developers. Example areas assistance include\nuse appropriate S4 structures, specific guidance efficient\nimplementation, guidance code structure, critical assessment \npackage documentation structure. Use \nbioc-devel mailing list email\nmaintainer@bioconductor.org obtain additional support.Support Email: maintainer@bioconductor.org","code":""},{"path":"develop-overview.html","id":"develop-overview","chapter":"Overview","heading":"Overview","text":"following chapters go general package development guidelines \nexpected different parts \nBioconductor package.","code":""},{"path":"package-name.html","id":"package-name","chapter":"2 Package name","heading":"2 Package name","text":"package name match GitHub\nrepository name case-sensitive. package name descriptive \nalready exist current package (case-insensitive) \nBioconductor CRAN. Reusing\narchived deprecated package names also strongly discouraged often \nallowed. submission please inquire using legacy package\nname bioc-devel@r-project.org mailing list.easy way check whether name already use check \nfollowing command fails using ‘devel’ version Bioconductor:One also search Bioconductor browsable code\nbase search similar existing names \npackages, functions, classes.addition, avoid package names :easily confused existing package names, function names, class names.Imply temporal (e.g. ExistingPackage2) qualitative\n(e.g. ExistingPackagePlus) relationship.Suggest hate speech, slurs profanity, either implicitly explicitly.Invoke refer historical, ethical, political contexts.Reference well known people, characters, brands, places icons.Also, avoid unwanted meanings foreign languages, name checkers \nwordsafety might used proposed package name.Please consider name package carefully. Bioconductor discourage\nrenaming package acceptance. process renaming package \ndeprecate old named package re-submit newly named package \nreview tracker subject new review. timely process \nundertaken lightly.","code":"\nif (!require(\"BiocManager\")) {\n install.packages(\"BiocManager\")\n}\nBiocManager::install(\"MyPackage\")"},{"path":"general.html","id":"general","chapter":"3 General Bioconductor Package Development","heading":"3 General Bioconductor Package Development","text":"","code":""},{"path":"general.html","id":"version-of-bioconductor-and","chapter":"3 General Bioconductor Package Development","heading":"3.1 Version of Bioconductor and ","text":"Package developers always use devel version Bioconductor \nBioconductor packages developing testing packages contributed.Depending release cycle, using\nBioconductor devel may may involve also using devel version \n. See -using devel version \nBioconductor --date information.","code":""},{"path":"general.html","id":"correctness-space-and-time","chapter":"3 General Bioconductor Package Development","heading":"3.2 Correctness, Space and Time","text":"","code":""},{"path":"general.html","id":"r-cmd-build","chapter":"3 General Bioconductor Package Development","heading":"3.2.1 R CMD build","text":"Bioconductor packages must minimally pass R CMD build (R CMD INSTALL --build) pass R CMD check errors warnings using recent\nR-devel. Authors also try address errors, warnings, notes \narise build check.","code":""},{"path":"general.html","id":"bioccheck","chapter":"3 General Bioconductor Package Development","heading":"3.2.2 BiocCheck","text":"Packages must also pass BiocCheck::BiocCheckGitClone() \nBiocCheck::BiocCheck('new-package'=TRUE) errors warnings. \nBiocCheck package set tests encompass\nBioconductor Best Practices. Every effort made address \nerrors, warnings, notes arise build check.","code":""},{"path":"general.html","id":"error-warning-and-notes","chapter":"3 General Bioconductor Package Development","heading":"3.2.3 ERROR, WARNING, and NOTES","text":"Bioconductor team member assigned review\npackage submission process expect ERROR, WARNINGS, \nNOTES addressed R CMD build, R CMD check, BiocCheck. \nremaining, justification corrected \nexpected.","code":""},{"path":"general.html","id":"file-names","chapter":"3 General Bioconductor Package Development","heading":"3.2.4 File names","text":"use filenames differ case, file systems case-sensitive.","code":""},{"path":"general.html","id":"package-size","chapter":"3 General Bioconductor Package Development","heading":"3.2.5 Package size","text":"source package resulting running R CMD build occupy less 5 MB disk.\npackage includes (e.g. vignettes) screenshots, limit can reached quite quickly. size can reduced (often much 70%) lossy quality-preserving manner using tools pngquant (available command line utility GUI systems).","code":""},{"path":"general.html","id":"check-duration","chapter":"3 General Bioconductor Package Development","heading":"3.2.6 Check duration","text":"package require less 10 minutes run R CMD check ---build-vignettes.\nUsing ---build-vignettes option ensures vignette built .\n1","code":""},{"path":"general.html","id":"memory","chapter":"3 General Bioconductor Package Development","heading":"3.2.7 Memory","text":"Vignette man page examples use 3 GB memory since allocate 32-bit Windows.","code":""},{"path":"general.html","id":"individual-file-size","chapter":"3 General Bioconductor Package Development","heading":"3.2.8 Individual file size","text":"software packages, individual files must <= 5MB.\nrestriction exists even package accepted added \nBioconductor repository. See data section \nadvice packages using large data files.","code":""},{"path":"general.html","id":"undesirable-files","chapter":"3 General Bioconductor Package Development","heading":"3.2.9 Undesirable files","text":"raw package directory contain unnecessary files, system files, \nhidden files .DS_Store, .project, .git, cache files, log files,\n*.Rproj, *., etc. files may present local directory commited \ngit (see .gitignore). files directories \napplications (Github Actions, devtool, etc) ideally different\nbranch submitted Bioconductor version package.","code":""},{"path":"general.html","id":"r-cmd-check-environment","chapter":"3 General Bioconductor Package Development","heading":"3.3 R CMD check environment","text":"possible activate deactivate number options R CMD build R CMD check.\nOptions can set individual environment variables can listed file.\nDescriptions different options available can found .\nBioconductor chosen customize options incoming submission R CMD check.\nfile utilized flags can downloaded GitHub.\nfile can either placed default directory directed can set environment variable R_CHECK_ENVIRON command similar :","code":"export R_CHECK_ENVIRON = "},{"path":"important-bioconductor-package-development-features.html","id":"important-bioconductor-package-development-features","chapter":"4 Important Bioconductor Package Development Features","heading":"4 Important Bioconductor Package Development Features","text":"","code":""},{"path":"important-bioconductor-package-development-features.html","id":"biocviews","chapter":"4 Important Bioconductor Package Development Features","heading":"4.1 biocViews","text":"Packages added Bioconductor Project require biocViews:\nfield DESCRIPTION file. field name “biocViews” \ncase-sensitive must begin lower-case ‘b’.biocViews terms “keywords” used describe given package. \nbroadly divided four categories, representing type \npackages present Bioconductor ProjectSoftwareAnnotation DataExperiment DataWorkflowbiocViews available release devel branches \nBioconductor. devel branch check box tree\nstructure , checked, displays biocViews defined \nused package, addition biocViews use. See also\ndescription section","code":""},{"path":"important-bioconductor-package-development-features.html","id":"biocviews-motivation","chapter":"4 Important Bioconductor Package Development Features","heading":"4.1.1 Motivation","text":"One can use biocViews two broad purposes.researcher might want identify packages \nBioconductor Project related specific purpose.\nexample, one may want look packages related “Copy\nNumber Variants”.researcher might want identify packages \nBioconductor Project related specific purpose.\nexample, one may want look packages related “Copy\nNumber Variants”.development, package contributor can “tag” package\nbiocViews someone looking packages (like \nscenario 1) can easily find package.development, package contributor can “tag” package\nbiocViews someone looking packages (like \nscenario 1) can easily find package.","code":""},{"path":"important-bioconductor-package-development-features.html","id":"biocviews-pkg-devel","chapter":"4 Important Bioconductor Package Development Features","heading":"4.1.2 biocViews during new package development","text":"Visit ‘devel’ biocViews process \nadding biocViews new package. Identify many terms \nappropriate hierarchy. Prefer ‘leaf’ terms end \nhierarchy, inclusive terms. Remember check box\ndisplaying available terms.Please Note:package belong one part Bioconductor Project\n(Software, Annotation Data, Experiment Data, Workflow), choose \nbiocViews category.package belong one part Bioconductor Project\n(Software, Annotation Data, Experiment Data, Workflow), choose \nbiocViews category.biocViews listed package must match exactly (e.g.,\nspelling, capitalization) terms biocViews hierarchy.biocViews listed package must match exactly (e.g.,\nspelling, capitalization) terms biocViews hierarchy.submit new package review , package checked\nbuilt Bioconductor Project. check following \nbiocViews:Package contributor added biocViews.Package contributor added biocViews.biocViews valid.biocViews valid.Package contributor added biocViews one categories.Package contributor added biocViews one categories.receive “RECOMMENDED” direction biocViews\nsubmitted package, can try correcting \nfollowing directions given ask package\nreviewer information.developer thinks biocViews term added current acceptable\nlist, please email bioc-devel@r-project.org requesting new biocView, \nhierarchy term placed, justification new\nterm.","code":""},{"path":"important-bioconductor-package-development-features.html","id":"reusebioc","chapter":"4 Important Bioconductor Package Development Features","heading":"4.2 Common Bioconductor Methods and Classes","text":"strongly recommend reusing existing methods importing data, \nreusing established classes representing data. \nsuggestions importing different file types commonly used\nBioconductor classes. classes functionality also try\nsearching biocViews data type.","code":""},{"path":"important-bioconductor-package-development-features.html","id":"commonimport","chapter":"4 Important Bioconductor Package Development Features","heading":"4.2.1 Importing data","text":"GTF, GFF, BED, BigWig, etc., – rtracklayer ::import()VCF – VariantAnnotation ::readVcf()SAM / BAM – Rsamtools ::scanBam(),\nGenomicAlignments ::readGAlignment*()FASTA – Biostrings ::readDNAStringSet()FASTQ – ShortRead ::readFastq()MS data (XML-based mgf formats) – Spectra ::Spectra(),\nSpectra ::Spectra(source = MsBackendMgf::MsBackendMgf())","code":""},{"path":"important-bioconductor-package-development-features.html","id":"commonclass","chapter":"4 Important Bioconductor Package Development Features","heading":"4.2.2 Common Classes","text":"Rectangular feature x sample data –\nSummarizedExperiment ::SummarizedExperiment()\n(RNAseq count matrix, microarray, …)Genomic coordinates – GenomicRanges ::GRanges()\n(1-based, closed interval)Genomic coordinates multiple samples –\nGenomicRanges ::GRangesList()Ragged genomic coordinates – RaggedExperiment\n::RaggedExperiment()DNA / RNA / AA sequences – Biostrings\n::*StringSet()Gene sets – BiocSet ::BiocSet(),\nGSEABase ::GeneSet(),\nGSEABase ::GeneSetCollection()Multi-omics data –\nMultiAssayExperiment ::MultiAssayExperiment()Single cell data –\nSingleCellExperiment ::SingleCellExperiment()Mass spec data – Spectra ::Spectra()File formats – BiocIO ::`BiocFile-class`general, package accepted show interoperability\ncurrent Bioconductor ecosystem.","code":""},{"path":"important-bioconductor-package-development-features.html","id":"bioc-vignette","chapter":"4 Important Bioconductor Package Development Features","heading":"4.3 Vignette","text":"Every submitted Bioconductor package least one Rmd (preferred) \nRnw vignette, ideally utilizing BiocStyle::html_document output\nrendering. include evaluated R package code detailed\nintroduction/abstract section provides motivation inclusion \nBioconductor appropriate review comparison existing\nBioconductor packages similar functionality scope. See vignette\ndocumentation section details.","code":""},{"path":"readme.html","id":"readme","chapter":"5 The README file","heading":"5 The README file","text":"README files required Bioconductor packages.README file included package Github repository provides installation instructions,\ninstruction also include\nBioconductor installation instructions. See\nBioconductor package installation instructions current Bioconductor\npackage landing page (e.g. GenomicRanges).README.Rmd provided (rather README.md, ) \ninstallation instructions eval=FALSE code chunk.Nowhere code ( code, man pages,\nvignettes, Rmd files) someone try install download system\ndependencies, applications, packages, etc.Developers can provide instructions follow executed assume\nnecessary dependencies, applications, packages already set \nuser’s system. See also INSTALL file system dependencies\nrequirements.","code":""},{"path":"description.html","id":"description","chapter":"6 The DESCRIPTION file","heading":"6 The DESCRIPTION file","text":"DESCRIPTION file must properly formatted.\nfollowing sections review important notes regarding fields \nDESCRIPTION file associated files.","code":""},{"path":"description.html","id":"description-pkg","chapter":"6 The DESCRIPTION file","heading":"6.1 Package","text":"name package. repository name name Package\ndescription match (including case-sensitive).","code":""},{"path":"description.html","id":"description-title","chapter":"6 The DESCRIPTION file","heading":"6.2 Title","text":"brief descriptive title package.","code":""},{"path":"description.html","id":"description-ver","chapter":"6 The DESCRIPTION file","heading":"6.3 Version","text":"Bioconductor packages use x.y.z version scheme.\nSee Version Numbering specifics release\ndevel Bioconductor versioning proceeds. \nfirst submitted Bioconductor, package pre-release version\n0.99.0.following rules apply:x usually 0 packages yet released.y even packages release, odd packages devel.\nGenerally, bump number especially pre-release.z incremented whenever committing changes package.","code":""},{"path":"description.html","id":"description-description","chapter":"6 The DESCRIPTION file","heading":"6.4 Description","text":"description relatively short detailed overview \npackage functionality entails. least three complete sentences.","code":""},{"path":"description.html","id":"description-authors","chapter":"6 The DESCRIPTION file","heading":"6.5 Authors@R","text":"Authors@R field used.\nmaintainer designation (cre Authors@R) required actively\nmaintained email address. email address used contact\nregarding issues arise package future.persons ORCiD identifier provide \nidentifier via element named “ORCID” comment argument person().one person listed Maintainer ensure single point\ncontact. person default commit access git\nrepository git.bioconductor.org. Commit access can given \ndevelopers request bioc-devel mailing list.Another option add collaborators \nGitHub repository. approach enables development many restricts\npush access git.bioconductor.org.","code":"\nperson(\"Lori\", \"Shepherd\",\n email = Lori.Shepherd@roswellpark.org,\n role = c(\"cre\", \"aut\"),\n comment = c(ORCID = \"0000-0002-5910-4010\"))"},{"path":"description.html","id":"description-license","chapter":"6 The DESCRIPTION file","heading":"6.6 License","text":"license field preferably refer standard license (see\nwikipedia) using one ’s\nstandard specifications. ships \nfollowing standard licensesBe specific version applies (e.g., GPL-2).\nLicenses restricting use, e.g., academic non-profit researchers, \nsuitable Bioconductor. Core Bioconductor packages typically\nlicensed Artistic-2.0.specify non-standard license, include file named LICENSE \npackage (containing full terms license) use string file LICENSE License: field.package contain code can redistributed according \npackage license. aware licensing agreements packages \ndepending package. packages open source even \npublicly available.","code":""},{"path":"description.html","id":"description-lazydata","chapter":"6 The DESCRIPTION file","heading":"6.7 LazyData","text":"packages include data, recommend including LazyData: TRUE.\nexperience slows loading packages large\ndata. course exceptions; please provide reasoning included.","code":""},{"path":"description.html","id":"depends-imports-suggests-enhances","chapter":"6 The DESCRIPTION file","heading":"6.8 Depends, Imports, Suggests, Enhances","text":"packages must available via Bioconductor’s biocViews \nCRAN; use Remotes: field supported, hence dependencies \navailable repositories (e.g.  GitHub) \nallowed specify explicit version package.Reuse, rather re-implement duplicate, well-tested functionality \npackages. Make use appropriate existing packages (e.g.,\nbiomaRt,\nAnnotationDbi,\nBiostrings, etc.) classes (e.g.,\nSummarizedExperiment,\nGenomicRanges::GRanges,\nS4Vectors::Rle,\nBiostrings::DNAStringSet, etc.), \navoid duplication functionality available Bioconductor packages.\nSee Common Bioconductor Methods Classes.\nBioconductor reviewers strict point! New packages \ninteroperable existing Bioconductor classes reimplement\nfunctionality especially regards importing/reading data.package can listed Depends:, Imports:, Suggests:,\nEnhances:. Determine placement package based following\nguidelines:Imports: packages provide functions, methods, classes \nused inside package name space. packages listed .Imports: packages provide functions, methods, classes \nused inside package name space. packages listed .Depends: packages provide essential functionality users \npackage, e.g., GenomicRanges package listed Depends:\nfield GenomicAlignments.\nunusual three packages listed Depends:.Depends: packages provide essential functionality users \npackage, e.g., GenomicRanges package listed Depends:\nfield GenomicAlignments.\nunusual three packages listed Depends:.Suggests: packages used vignettes, examples, conditional\ncode.Commonly, annotation experiment packages (e.g., TxDb*) used \nvignette example code included field thus avoiding costly\ndownload. case external one-function required \npackage code, package availability usage can done via:\n(!requireNamespace('suggPKG', quietly = TRUE))\n stop(\"Install 'suggPKG' use function.\")\nsuggPKG::function()Suggests: packages used vignettes, examples, conditional\ncode.Commonly, annotation experiment packages (e.g., TxDb*) used \nvignette example code included field thus avoiding costly\ndownload. case external one-function required \npackage code, package availability usage can done via:Enhances: packages Rmpi parallel enhance \nperformance package, strictly needed \nfunctionality.Enhances: packages Rmpi parallel enhance \nperformance package, strictly needed \nfunctionality.seldom necessary specify specific\nversions dependencies, since Bioconductor release strategy \nstandard installation instructions guarantee constraints. Repositories\nmirrored outside Bioconductor include branches \nBioconductor release, may find useful fully specify versions \nenforce constraints otherwise guaranteed Bioconductor installation\npractices.additional information regarding Depends, Imports, Suggest \npackage placed see Connecting \npackages package\ndependency\nsection Writing R Extensions.","code":"if (!requireNamespace('suggPKG', quietly = TRUE))\n stop(\"Install 'suggPKG' to use this function.\")\nsuggPKG::function()"},{"path":"description.html","id":"description-sysdep","chapter":"6 The DESCRIPTION file","heading":"6.9 SystemRequirements","text":"field listing external software required, \nautomatically installed normal package installation process.installation process non-trivial, top-level INSTALL file \nincluded document process. user facing README included \nalso recommended document process ; try install \ndependency user anywhere package (.e. readme, r code, man pages,\nvignette). may show instructions unevaluated sections.","code":""},{"path":"description.html","id":"description-biocviews","chapter":"6 The DESCRIPTION file","heading":"6.10 biocViews","text":"field required!Specify least two leaf node biocViews.\nMultiple leaf terms encouraged terms must come trunk \npackage type (.e., Software, AnnotationData, ExperimentData, \nWorkflow). biocViews terms case-sensitive.field name “biocViews” case-sensitive must begin lower-case\n‘b’. Please use single line biocViews seperated commas(.e,biocViews: GeneTarget, SingleCell).","code":""},{"path":"description.html","id":"description-bugreport","chapter":"6 The DESCRIPTION file","heading":"6.11 BugReports","text":"encouraged include relevant links \nGitHub reporting issues.","code":""},{"path":"description.html","id":"description-url","chapter":"6 The DESCRIPTION file","heading":"6.12 URL","text":"field directs users source code repositories, additional help\nresources, etc; details provided Writing R Extensions\nmanual, RShowDoc(\"R-exts\").","code":""},{"path":"description.html","id":"description-video","chapter":"6 The DESCRIPTION file","heading":"6.13 Video","text":"field displays links instructional videos.","code":""},{"path":"description.html","id":"description-collate","chapter":"6 The DESCRIPTION file","heading":"6.14 Collate","text":"may necessary order class method definitions appropriately\npackage installation.","code":""},{"path":"description.html","id":"description-bioctype","chapter":"6 The DESCRIPTION file","heading":"6.15 BiocType","text":"required submitting Docker Workflow.\nOtherwise field optionally define type Bioconductor package\nSoftware, ExperimentData, Annotation.","code":""},{"path":"namespace.html","id":"namespace","chapter":"7 The NAMESPACE file","heading":"7 The NAMESPACE file","text":"NAMESPACE file defines functions, classes, methods imported namespace, exported users.following section describe Bioconductor reviewers looking file.","code":""},{"path":"namespace.html","id":"function-names","chapter":"7 The NAMESPACE file","heading":"7.1 Function names","text":"Exported functions use camel case underscoring include .,\nindicates S3 dispatch. Functions starting . exported\nindicates internal function.","code":""},{"path":"namespace.html","id":"imported-functions","chapter":"7 The NAMESPACE file","heading":"7.2 Imported functions","text":"Generally importFrom() encouraged importing entire package.\nHowever, many functions single package, import() can \nacceptable. particular Bioconductor class used extended \nhighly recommended import() full package full class\nfunctionality inherited automatically; exceptions depending \nimplementation necessity.","code":""},{"path":"namespace.html","id":"exported-functions","chapter":"7 The NAMESPACE file","heading":"7.3 Exported functions","text":"Exporting functions exportPattern(\"^[[:alpha:]]+\") strongly\ndiscouraged almost always allowed. Functions generics \nexported individually, clarity control.","code":""},{"path":"news.html","id":"news","chapter":"8 The NEWS file","heading":"8 The NEWS file","text":"NEWS file informs user changes software may impact user\nexpectations. highly recommended developer use plain \nconcise language communicate changes.NEWS file keep track changes, non-technical language, \ncode one release version next. file can reside either\npackage’s top level directory inst/ directory. \none NEWS file per package.following acceptable locations formats:Specifics formatting can found help page ?news.\nBioconductor compiles NEWS files updated packages create\nsemi-annual release announcement.\nNEWS files must include list elements plain text files.version 1.24.0 NEWS file SummarizedExperiment:Note version documented forthcoming release version \npackage. developer, NEWS file running log \nchanges lead next release package.user can read release notes SummarizedExperiment version\n1.24.0 running following:development package re-installation, NEWS file’s\nformatting can checked :function fail directly show output similar \none formatting errors need corrected.\nNote bullet points embedded within first Text field:","code":"CHANGES IN VERSION 1.24.0\n-------------------------\n\nNEW FEATURES\n\n o Add 'checkDimnames' argument to SummarizedExperiment() constructor\n function\n\n o Add showAsCell() method for SummarizedExperiment objects.\n\nSIGNIFICANT USER-VISIBLE CHANGES\n\n o Check the assay dimnames at SummarizedExperiment construction time:\n The SummarizedExperiment() constructor function now raises an error\n if one of the supplied assays has rownames and/or colnames that don't\n match those of the SummarizedExperiment object to construct.\n\nutils::news(package = \"SummarizedExperiment\", Version == \"1.24.0\")\nutils::news(package=\"\")Version: 1.2.0\nDate: 2018-07-15\nText: Made the following significant changes o added a subsetting\n method o added a new field to database\n\nVersion: 1.0.0\nDate: 2018-06-15\nText: Fixed bug. Begin indexing from 1 instead of 2\n\nVersion: 0.99.0\nDate: 2018-05-15\nText: Submitted to Bioconductor"},{"path":"license.html","id":"license","chapter":"9 The LICENSE file","heading":"9 The LICENSE file","text":"license field preferably refer standard license (see\nwikipedia)\nusing one ’s standard specifications.Licenses restricting use, e.g., academic non-profit researchers, \nsuitable Bioconductor. Core Bioconductor packages typically\nlicensed Artistic-2.0.specify non-standard license, include LICENSE file \npackage (containing full terms license) use string file LICENSE License: field. LICENSE file provided match \nLicense field Description fileThe package contain code can redistributed according \npackage license. aware licensing agreements packages \ndepending package. packages open source even \npublicly available.","code":""},{"path":"citation.html","id":"citation","chapter":"10 The CITATION file","heading":"10 The CITATION file","text":"Appropriate citations must included help pages (e.g., see also\nsection) vignettes; aspect documentation different \nscientific endeavor. file inst/CITATION can used specify \npackage cited. option utilized, maintainer can check\nproper formatting CITATION file running\nreadCitationFile(\"inst/CITATION\") WITHOUT package loaded \nlibrary call; must run without error citation accurately\ndisplayed package landing page.Whether CITATION file present, automatically-generated citation\nappear package landing page Bioconductor web site. \noptimal formatting author names (CITATION file present),\nspecify package author maintainer using Authors@R field \ndescribed Writing R Extensions manual.","code":""},{"path":"sysdep.html","id":"sysdep","chapter":"11 The INSTALL file","heading":"11 The INSTALL file","text":"INSTALL file included package. INSTALL file\nutilized specifying external system requirements needed. \nused combination SystemRequirements field Description\nfile. file contain installation instructions\nrequired system dependency.Specifying requirement guarantee Bioconductor agree \ninstall external system requirement. encouraged discuss \nadditional system requirements bioc-devel@r-project.org \ndevelopment.System requirements never exclusive particular\nversion. Maintainers expected package work whatever \ncurrent version external software available.See also third party code","code":""},{"path":"docs.html","id":"docs","chapter":"12 Documentation","heading":"12 Documentation","text":"Package documentation important users understand work code.","code":""},{"path":"docs.html","id":"doc-require","chapter":"12 Documentation","heading":"12.1 Bioconductor documentation minimal requirements:","text":"vignette Rmd Rnw format executable code \ndemonstrates use package accomplish task,vignette Rmd Rnw format executable code \ndemonstrates use package accomplish task,man pages exported functions runnable examples, well\ndocumented data structures especially pre-exiting\nclassman pages exported functions runnable examples, well\ndocumented data structures especially pre-exiting\nclasswell documented datasets data provided data/ inst/extdata/.well documented datasets data provided data/ inst/extdata/.References methods used well similar related projects\npackages also expected.data structures differ similar packages, Bioconductor\nreviewers expect justification . Keep mind\nalways possible extend existing classes.","code":""},{"path":"docs.html","id":"vignettes","chapter":"12 Documentation","heading":"12.2 Vignettes","text":"vignette demonstrates accomplish non-trivial tasks embodying core\nfunctionality package. two common types vignettes.(Recommended) R markdown vignette similar Sweave vignette, uses\nmarkdown instead \\(\\LaTeX\\)\nstructuring text sections resulting HTML output. r BiocStyle::CRANpkg(\"knitr\") package can process Sweave R\nmarkdown vignettes, producing pleasing output. Refer Writing package\nvignettes technical details. See r BiocStyle::Biocpkg(\"BiocStyle\") package convenient way use common\nmacros standard Bioconductor style vignette.(Recommended) R markdown vignette similar Sweave vignette, uses\nmarkdown instead \\(\\LaTeX\\)\nstructuring text sections resulting HTML output. r BiocStyle::CRANpkg(\"knitr\") package can process Sweave R\nmarkdown vignettes, producing pleasing output. Refer Writing package\nvignettes technical details. See r BiocStyle::Biocpkg(\"BiocStyle\") package convenient way use common\nmacros standard Bioconductor style vignette.Sweave vignette .Rnw file contains \\(\\LaTeX\\) chunks code. code chunk starts line\n<<>>=, ends @. chunk evaluated R CMD build,\nprior \\(\\LaTeX\\) compilation PDF document.Sweave vignette .Rnw file contains \\(\\LaTeX\\) chunks code. code chunk starts line\n<<>>=, ends @. chunk evaluated R CMD build,\nprior \\(\\LaTeX\\) compilation PDF document.vignette provides reproducibility: vignette produces results \ncopying corresponding commands \nsession. therefore essential vignette embed executed code. Shortcuts (e.g., using \\(\\LaTeX\\) verbatim\nenvironment, using Sweave eval=FALSE flag, equivalent tricks \nmarkdown) undermine benefit vignettes generally allowed;\nexceptions can made proper justification discretion \nBioconductor reviewers.packages required least one Rmd Rnw vignette. Vignettes go\nvignettes/ directory package. Vignettes often used \nstandalone documents, best practices include informative title, \nprimary author vignette, last modification date vignette, \nlink package landing page. encourage use r BiocStyle::Biocpkg(\"BiocStyle\") formatting html_document \nrendering target. Something like following vignette accomplish\nsuggestion:want write one vignette, may want control\norder displayed package homepage \nbrowseVignettes() function called. Vignettes show \nalphabetical order, may logical ordering without\nspecification. One approach controlling order \nvignettes use number VignettteIndexEntry setting,\ne.g. using numbers 1-9, single digit number \nvignettes, 01-99 ten vignettes. example,\nfirst vignette specify header:best practices requirements writing Bioconductor vignettes \ndetailed following sections.","code":"output:\n BiocStyle::html_document:\n toc: true\n toc_depth: 2\nvignette: >\n %\\VignetteEngine{knitr::rmarkdown}\n %\\VignetteIndexEntry{1. Quick start to MyPackage}\n %\\VignetteEncoding{UTF-8}"},{"path":"docs.html","id":"vignette-introduction","chapter":"12 Documentation","heading":"12.2.1 Introduction","text":"Add “Introduction” section serves abstract introduce \nobjective, models, unique functions, key points, etc distinguish \npackage packages area. requirement \nBioconductor package vignettes. include short motivation \npackage general well motivation inclusion package \nBiconductor. relevant, brief review comparison packages \nsimilar functionality scope provided either Introduction \nseparate dedicated vignette section.","code":""},{"path":"docs.html","id":"installation","chapter":"12 Documentation","heading":"12.2.2 Installation","text":"Add “Installation” section show users download load \npackage Bioconductor.instructions installations instructions \neval=FALSE code chunk. code (\ncode, man pages, vignettes, Rmd files) someone try install download\nsystem dependencies, applications, packages, etc. Developers can provide\ninstructions follow unevaluated code chunks, assume \nnecessary dependencies, applications packages already set user’s\nsystem.","code":""},{"path":"docs.html","id":"table-of-contents","chapter":"12 Documentation","heading":"12.2.3 Table of contents","text":"appropriate, strongly encourage table contents","code":""},{"path":"docs.html","id":"evaluated-code-chunks","chapter":"12 Documentation","heading":"12.2.4 Evaluated code chunks","text":"Non-trivial executable code must!!!Static vignettes acceptable.","code":""},{"path":"docs.html","id":"session-information","chapter":"12 Documentation","heading":"12.2.5 Session information","text":"Include section SessionInfo() end vignette.","code":""},{"path":"docs.html","id":"vignettes-directory-and-intermediate-files","chapter":"12 Documentation","heading":"12.2.6 vignettes/ directory and intermediate files","text":"source vignette file (.Rnw .Rmd) necessary static images\nvignette directory. intermediate files \npresent. include complete processed vignette products well; vignette\ncreated R CMD build package. include types\ndocumentation please use inst/doc appropriately named inst\ndirectory.","code":""},{"path":"docs.html","id":"references","chapter":"12 Documentation","heading":"12.2.7 References","text":"Remember include relevant references methods.","code":""},{"path":"docs.html","id":"man-pages","chapter":"12 Documentation","heading":"12.3 Man pages","text":"See Writing R Extensions section man pages detailed\ninstruction format information documenting package, functions, classes,\ndata sets.help pages comprehensive.","code":""},{"path":"docs.html","id":"package-level-documentation","chapter":"12 Documentation","heading":"12.3.1 Package-level documentation","text":"Bioconductor encourages package man page overview \npackage links main functions. Users able relevant\npage display ?","code":""},{"path":"docs.html","id":"functions-and-classes","chapter":"12 Documentation","heading":"12.3.2 Functions and classes","text":"exported functions classes need man page. Man pages\ndescribing new classes must detailed structure type \ninformation stored.","code":""},{"path":"docs.html","id":"data-man","chapter":"12 Documentation","heading":"12.3.3 Data","text":"Data man pages must include provenance information data structure information.","code":""},{"path":"docs.html","id":"examples","chapter":"12 Documentation","heading":"12.3.4 Examples","text":"man pages runnable examples.use donttest dontrun discouraged generally allowed;\nexceptions can made proper justification discretion \nBioconductor reviewers.option used also preferable use donttest instead \ndontrun; donttest requires valid code \ndontrun .","code":""},{"path":"docs.html","id":"doc-inst-script","chapter":"12 Documentation","heading":"12.4 The inst/script/ directory","text":"scripts directory can vary.importantly data included inst/extdata/ directory, \nrelated script must present directory documenting clearly \ndata generated source information.include source URLs key information regarding filtering processing.can executable code, sudo code, text description.Users able download able roughly reproduce file \nobject present data.","code":""},{"path":"docs.html","id":"other-doc","chapter":"12 Documentation","heading":"12.5 Other","text":"types documentation (e.g. static files, jupyter notebooks, etc.) can \nprovided inst subdirectories substitute \nBioconductor documentation requirements listed .","code":""},{"path":"data.html","id":"data","chapter":"13 Package data","heading":"13 Package data","text":"developing software package, excellent practice give \ncomprehensive illustration methods package using existing\nexperiment data package, annotation data\ndata ExperimentHub AnnotationHub,\nsubmitting new data resources .existing data available applicable, new smaller dataset \nneeded examples package, data can included either separate\ndata package (larger amounts data) within package (smaller\ndatasets).Bioconductor Build system support git-lfs. current\noption storing large data. Large data sets must included \nExperimentHub. See additional information Create \nHub Package.","code":""},{"path":"data.html","id":"experiment-data-package","chapter":"13 Package data","heading":"13.1 Experiment Data Package","text":"Experimental data packages contain data specific particular analysis \nexperiment. often accompany software package use examples \nvignettes general updated regularly. need general subset\ndata workflows examples first check AnnotationHub\nresource available files (e.g., BAM, FASTA, BigWig, etc.) \nExperimentHub processed predefined\nBioconductor class structures.Bioconductor strongly encourages creating experiment data package \nutilizes ExperimentHub AnnotationHub\n(See Create Hub Package) traditional package encapsulates \ndata also acceptable pre-approval bioc-devel\nmailing list.See Package Submission guidelines \nsubmission procedures submitting related circular dependent\npackages please read related package submission procedure","code":""},{"path":"data.html","id":"adding-data-to-existing-package","chapter":"13 Package data","heading":"13.2 Adding Data to Existing Package","text":"Bioconductor strongly encourages use existing datasets, \navailable data can included directly package use examples\nfound man pages, vignettes, tests package. good\nreference Hadley Wickham package data.However, mentioned DESCRIPTION file chapter,\nBioconductor encourage using LazyData: True despite \nrecommendation article.Note. might modify usage section @usage data(\"mydata\")key points summarized following sections.","code":""},{"path":"data.html","id":"exported-data-and-the-data-directory","chapter":"13 Package data","heading":"13.2.1 Exported Data and the data/ directory","text":"Data data/ exported user readily available.\nmade available session use data().\nrequire documentation concerning creation source information.\noften .RData file created save() types acceptable well, see ?data().Please remember compress data.packages need use documented data within function, recommend\ncreating environment holding data avoid polluting \nglobal environment using data().create new empty environment. Extract data within \nenvironment finally extract data object environment using\ndouble brackets.","code":"\ndata_env <- new.env(parent = emptyenv())\ndata(\"mydata\", envir = data_env, package = \"mypackage\")\nmydata <- data_env[[\"mydata\"]]"},{"path":"data.html","id":"raw-data-and-the-instextdata-directory","chapter":"13 Package data","heading":"13.2.2 Raw Data and the inst/extdata/ directory","text":"often desirable show workflow involves parsing loading raw files.\nBioconductor recommends finding existing raw data already provided \nanother package hubs previously stated.However, applicable, raw data files included \ninst/extdata directory. Files type often accessed utilizing\nsystem.file(). Bioconductor requires documentation files \ninst/script/ directory. See data documentation.","code":""},{"path":"data.html","id":"internal-data","chapter":"13 Package data","heading":"13.2.3 Internal data","text":"Rarely, package may require parsed data used internal \nexported user. R/sysdata.rda often best place include\ntype data. Proper documentation data required.","code":""},{"path":"data.html","id":"other-data","chapter":"13 Package data","heading":"13.2.4 Other data","text":"Downloads files external data web avoided.necessary, minimum files cached.\nSee BiocFileCache Bioconductor recommended package\ncaching files. maintainer creates caching directory, \nutilize standard caching directories tools::R_user_dir(package, =\"cache\"). allowed download write files users\nhome directory, working directory, installed package directory. Files \ncached stated BiocFileCache (preferred) R_user_dir \ntempdir()/tempfile() files persistent. Please also see\nsections querying web resources file\ndownloads.","code":""},{"path":"tests.html","id":"tests","chapter":"14 Unit tests","heading":"14 Unit tests","text":"Unit tests simple write, easily invoked, confer large\nbenefits throughout software development process, early stage\nexploratory code, late stage maintenance long-established\nproject. Unit testing often becomes indispensable give\ntry. explain write unit tests, run ,\nwoven standard Bioconductor build process.\nhope unit tests become standard part software\ndevelopment, integral part Bioconductor package.recommend either RUnit, tinytest, testthat packages \nCRAN write unit tests. RUnit R implementation agile\nsoftware development ‘XUnit’ tools (see also JUnit, PyUnit) \ntries encourage, respective language, rapid development \nrobust useful software. tinytest lightweight (zero-dependency) \neasy--use unit testing framework. testthat also draws inspiration \n‘XUnit’ family testing packages, well many innovative ruby\ntesting libraries, like rspec, testy, bacon cucumber.","code":""},{"path":"tests.html","id":"tests-motivation","chapter":"14 Unit tests","heading":"14.1 Motivation","text":"bother unit testing?Imagine need function divideBy taking two arguments,\nmight define like :develop function likely test \nvariety ways, using different arguments, checking results,\neventually satisfied performs properly. Unless\nadopt sort software testing protocol, however, tests\nunlikely become integral part code. may \nscattered across different files, may exist re-runnable\ncode file , just ad hoc command-line function calls \nsometimes remember make.far better approach, propose, use lightweight,\nformalized unit testing. requires conventions\npractices:Store test functions standard directory.Use simple functions RUnit, tinytest, testthat packages \ncheck results.Run tests routine part development process.RUnit test divideBy:equivalent test using tinytest:equivalent test using testthat:Adopting practices cost little. developers\nfind practices simplify shorten development time. \naddition, create executable contract — concise \nverifiable description code supposed . \nexperienced unit-testing programmer create test function\naccompany every function, method class write. (don’t\nlet scare . Even adding single test package \nworthwhile, reasons explained .)Developers often rebel unit tests recommended ,\ncalculating creating unit tests existing code \nlengthy tedious job, productivity suffer.Unit tests, however, best written develop code, rather\npackage written. Replace informal testing\nlightweight formal practices, see \nimmediate long-term productivity increase.Consider every unit software (every function, method, \nclass) designed job, return specific outputs \nspecific inputs, cause specific side effects. unit test\nspecifies behaviors, provides single mechanism — one\ntest functions residing one files, within \nstandard directory structure — ensure target\nfunction, method class job. assurance, \nprogrammer (collaborators) can , confidence, proceed\nuse larger program. bug appears, new features\nneeded added, one adds new tests existing collection.\ncode becomes progressively powerful, robust, yet\nremains easily automatically validated.proponents suggest benefits unit testing extend\n: code design improves. argue \noperational definition function tests encourages\nclean design, ‘separation concerns’, sensible handling \nedge cases.Finally, unit testing can adopted piecemeal. Add single test\npackage, even test minor feature, \nusers benefit. Add tests go, bugs arise,\nnew features added, find puzzling code\nwrote months . Soon, unit testing part \nstandard practice, package increasingly\ncomplete set tests.","code":"divideBy <- function(dividend, divisor) {\n if (divisor == 0)\n return(NA)\n dividend / divisor\n}test_divideBy <- function() {\n checkEquals(divideBy(4, 2), 2)\n checkTrue(is.na(divideBy(4, 0)))\n checkEqualsNumeric(divideBy(4, 1.2345), 3.24, tolerance=1.0e-4)\n}expect_equal(divideBy(4, 2), 2)\nexpect_true(is.na(divideBy(4, 0)))\nexpect_equal(divideBy(4, 1.2345), 3.24, tolerance=1.0e-4)test_that(\"divideBy works properly\", {\n expect_equal(divideBy(4, 2), 2)\n expect_true(is.na(divideBy(4, 0)))\n expect_equal(divideBy(4, 1.2345), 3.24, tolerance = 1.0e-4)\n})"},{"path":"tests.html","id":"which-tests","chapter":"14 Unit tests","heading":"14.2 Deciding Which Test Framework To Use","text":"RUnit, tinytest, testthat robust testing solutions great tools\npackage development, choose use package largely comes\npersonal preference. However brief list strengths \nweaknesses .","code":""},{"path":"tests.html","id":"runit-strengths","chapter":"14 Unit tests","heading":"14.2.1 RUnit Strengths","text":"Longer history (first release 2005)Direct analog xUnit projects languages.need learn small set check functions.Used extensively Bioconductor (210 Bioconductor packages, overall 339 circa May 2015), particularly \ncore packages.","code":""},{"path":"tests.html","id":"runit-weaknesses","chapter":"14 Unit tests","heading":"14.2.2 RUnit Weaknesses","text":"RUnit development activity since 2010, active maintainer.Need manually source package test code run interactively.difficult setup run natively (although see\nBiocGenerics:::testPackage() handles ).","code":""},{"path":"tests.html","id":"tinytest-strengths","chapter":"14 Unit tests","heading":"14.2.3 tinytest Strengths","text":"Easy setup use; tests written scriptsTests can run interactively well via R CMD checkTest results can treated data","code":""},{"path":"tests.html","id":"tinytest-weaknesses","chapter":"14 Unit tests","heading":"14.2.4 tinytest Weaknesses","text":"Minimally necessary functionality available","code":""},{"path":"tests.html","id":"testthat-strengths","chapter":"14 Unit tests","heading":"14.2.5 Testthat Strengths","text":"Active development 39 contributors.Greater variety test functions available, including partial matching \ncatching errors, warnings messages.Easy setup devtools::use_testthat().Integrates devtools::test() automatically reload package source \nrun tests development.Test failures errors informative RUnit.number different reporting functions available, including visual\nreal-time test results.Used extensively CRAN (546 CRAN packages, overall 598 circa May 2015).","code":""},{"path":"tests.html","id":"testthat-weaknesses","chapter":"14 Unit tests","heading":"14.2.6 Testthat Weaknesses","text":"Test code slightly verbose equivalent RUnit tests.available less time (since 2009).","code":""},{"path":"tests.html","id":"runit-usage","chapter":"14 Unit tests","heading":"14.3 RUnit Usage","text":"","code":""},{"path":"tests.html","id":"adding-tests-for-your-code","chapter":"14 Unit tests","heading":"14.3.1 Adding Tests For Your Code","text":"Three things required:Create file containing functions style test_dividesBy\nfunction want test, using RUnit-provided check\nfunctions.Add small (idiosyncratic) files directories.Make sure RUnit BiocGenerics packages \navailable.Steps two three explained conventions build\nprocess.RUnit check methods:typical test function, can see test_divideBy, \ninvoke one program’s functions methods, call \nappropriate RUnit check function make sure result \ncorrect. RUnit reports failures, , enough\ncontext track error.RUnit can test exception (error) occurs withbut often convenient test specific exceptions, e.g., \nwarning “unusual condition” generated function f <- function() { warning(\"unusual condition\"); 1 } withuse error=... test specific errors.","code":"checkEquals(expression-A, expression-B)\ncheckTrue(condition)\ncheckEqualsNumeric(a, b, tolerance)checkException(expr, msg)obs <- tryCatch(f(), warning=conditionMessage)\ncheckIdentical(\"unusual condition\", obs)"},{"path":"tests.html","id":"conventions","chapter":"14 Unit tests","heading":"14.3.2 Conventions for the Build Process","text":"Writing unit tests easy, though Bioconductor package must \nset properly R CMD check MyPackage finds run \ntests. take pains describe exactly things \nset , going behind scenes. (See next\nsection simple technique use \nwant test small part code).standard command R CMD check MyPackage sources runs R\nfiles found MyPackage/tests/ directory. Historically, \nsometimes still, R package developers place test code \ninvention style one files tests directory.RUnit added already-existing structure practice\n2005, additions can confusing, beginning \nindirect way test functions found executed. (\nfollow steps well. Post [bioc-devel][] \nrun difficulty.)two steps:Create file MyPackage/tests/runTests.R contents:\nBiocGenerics:::testPackage(\"MyPackage\")Create file MyPackage/tests/runTests.R contents:Create number files MyPackage/inst/unitTests/ \nunit test functions. can put tests one file \ndirectory, distributed among multiple files. files\nmust follow naming convention specified regular\nexpression:\npattern=\"^test_.*\\\\.R$\"\nexample, therefore, good choice \nMyPackage/inst/unitTests/test_divideBy.R dividesBy\nfunction one several home-brewed arithmetic functions \nwrote, provide tests, descriptive filename\n(practice always recommend) might \nMyPackage/inst/unitTests/test_homeBrewArithmetic.RCreate number files MyPackage/inst/unitTests/ \nunit test functions. can put tests one file \ndirectory, distributed among multiple files. files\nmust follow naming convention specified regular\nexpression:example, therefore, good choice \nMyPackage/inst/unitTests/test_divideBy.R dividesBy\nfunction one several home-brewed arithmetic functions \nwrote, provide tests, descriptive filename\n(practice always recommend) might \nMyPackage/inst/unitTests/test_homeBrewArithmetic.R","code":"BiocGenerics:::testPackage(\"MyPackage\")pattern=\"^test_.*\\\\.R$\""},{"path":"tests.html","id":"r-unit-during-develoment","chapter":"14 Unit tests","heading":"14.3.3 Using Tests During Development","text":"run tests. developing class, debugging\nmethod function, probably want run just one test \ntime, earlier version package \ninstalled, making local exploratory\nchanges. Assuming followed directory structure naming\nconventions recommended , current working directory \ninst, :failed test reported like :","code":"R CMD check MyPackagelibrary(RUnit)\nlibrary(MyPackage)\n\nsource('../R/divideBy.R')\nsource('unitTests/test_divideBy.R')\ntest_divideBy()\n[1] TRUEError in checkEquals(divideBy(4, 2), 3) : Mean relative difference: 0.5"},{"path":"tests.html","id":"summary-the-minimal-setup","chapter":"14 Unit tests","heading":"14.3.4 Summary: the minimal setup","text":"minimal Bioconductor unitTest setup requires one-line addition \nMyPackage/DESCRIPTION fileand two files, MyPackage/tests/runTests.R:MyPackage/inst/unitTests/test_divideBy.R:Remember unitTests/test_XXXX.R file, files, can \nname(s), long start test_.","code":"Suggests: RUnit, BiocGenericsBiocGenerics:::testPackage(\"MyPackage\")test_divideBy <- function() {\n checkEquals(divideBy(4, 2), 2)\n checkTrue(is.na(divideBy(4, 0)))\n checkEqualsNumeric(divideBy(4, 1.2345), 3.24, tolerance=1.0e-4)\n}"},{"path":"tests.html","id":"testthat-usage","chapter":"14 Unit tests","heading":"14.4 Testthat Usage","text":"Hadley Wickham, primary author testthat comprehensive chapter \nTesting testthat R packages book. also article\ntestthat: Get Started Testing R-Journal.easiest way setup testthat infrastructure package using\ndevtools::use_testthat().can automatically reload code tests re-run using\ndevtools::test().","code":""},{"path":"tests.html","id":"conversion-from-runit-to-testthat","chapter":"14 Unit tests","heading":"14.4.1 Conversion from RUnit to testthat","text":"existing RUnit project like convert using\ntestthat need change following things package\nstructure.devtools::use_testthat() can used setup testthat testing structure.Test files stored tests/testthat rather inst/unitTests \nstart test. Richard Cotton’s\nrunittotesthat package\ncan used programmatically convert RUnit tests testthat format.need add Suggests: testthat DESCRIPTION file rather \nSuggests: RUnit, BiocGenerics.","code":""},{"path":"tests.html","id":"conversion-from-runit-to-tinytest","chapter":"14 Unit tests","heading":"14.4.2 Conversion from RUnit to tinytest","text":"Test files placed inst/tinytest directory names \ntest_FILE.R.Remove RUnit function shells extract function bodies single\nscript.Include tinytest.R file tests folder runs:Add Suggests: testthat DESCRIPTION file.","code":"if (requireNamespace(\"tinytest\", quietly = TRUE))\n tinytest::test_package(\"PACKAGE\")"},{"path":"tests.html","id":"test-coverage","chapter":"14 Unit tests","heading":"14.5 Test Coverage","text":"Test coverage\nrefers percentage package code\ntested unit tests. Packages higher coverage\nlower chance containing bugs.tests taking long achieve full test coverage, see long tests.\nimplementing long tests highly recommend reaching \nbioconductor team bioc-devel mailing list ensure\nproper use justification.","code":""},{"path":"tests.html","id":"additional-resources","chapter":"14 Unit tests","heading":"14.6 Additional Resources","text":"web resources worth reading:Unit Testing WikipediaAn informal accountTest-driven developmentAgile software developmentTesting testthattestthat: Get Started Testing","code":""},{"path":"r-code.html","id":"r-code","chapter":"15 R code","heading":"15 R code","text":"Everyone coding style formats. however best\npractice guidelines Bioconductor reviewers look . can robust, fast efficient programming\nlanguage often coding practices result less ideal use \nresources.section review key points, suggestions, best practices \naid package review process assist making code \nrobust efficient.","code":""},{"path":"r-code.html","id":"rcode-license","chapter":"15 R code","heading":"15.1 License","text":"contain code can distributed license specified (see also\nDESCRIPTION file).","code":""},{"path":"r-code.html","id":"r-code-development","chapter":"15 R code","heading":"15.2 R Code Development","text":"","code":""},{"path":"r-code.html","id":"rcode-reuse","chapter":"15 R code","heading":"15.2.1 Re-use of functionality, classes, and generics","text":"Avoid re-implementing functionality classes (see also\nDESCRIPTION file).\nMake use appropriate existing packages (e.g.,\nbiomaRt,\nAnnotationDbi,\nBiostrings,\nGenomicRanges) classes (e.g.,\nSummarizedExperiment,\nBiobase::AnnotatedDataFrame,\nGenomicRanges:;GRanges,\nBiostrings::DNAStringSet) avoid duplication functionality\navailable Bioconductor packages. See\nalso Common Bioconductor Methods Classes.encourages interoperability simplifies package development.\nnew representation needed, see class development section.\ngeneral, Bioconductor insist interoperability Common\nClasses acceptance.Developers make effort re-use generics fit generic\ncontract proposed class-method pair .e., behavior method\naligns originally proposed behavior generic. Specifically,\nbehavior can one return value class across\nmethods. method behavior can also performant conceptual transformation\nprocedure across classes described generic.\nBiocGenerics lists commonly used generics \nBioconductor. One example generic method implementation \nrowSums generic corresponding method within \nDelayedArray package. generic contract returns \nnumeric vector length rows adhered across classes\nincluding DelayedMatrix class. Re-using generics reduces amount \nnew generics consolidating existing operations avoids mistake \nintroducing “new” generic name. Generic name collisions may\nmask masked previous definitions ways hard diagnose.\nrecently, recommend use conflicted \nidentify namespace collisions.problems, e.g., performance parsing particular\nfile type, ask input developers \nbioc-devel mailing list. Common disadvantages \n‘implementing ’ introduction non-standard data\nrepresentations (e.g., neglecting translate coordinate systems file\nformats Bioconductor objects) user bewilderment. Therefore, case,\nrecommend use standard file format classes inheriting \nBiocIO’s BiocFile class packages \nrtracklayer BiocIO.","code":""},{"path":"r-code.html","id":"naming-functions","chapter":"15 R code","heading":"15.2.2 Naming of packages, functions, and classes","text":"See section package naming. concepts also\napply function names, class names, etc.Avoid names :easily confused existing package names, function names, class names.Imply temporal (e.g. ExistingPackage2) qualitative\n(e.g. ExistingPackagePlus) relationship.Suggest hate speech, slurs profanity, either implicitly explicitly.Invoke refer historical, ethical, political contexts.Reference well known people, characters, brands, places icons.","code":""},{"path":"r-code.html","id":"rcode-method-development","chapter":"15 R code","heading":"15.2.3 Methods development","text":"encourage maintainers create new methods classes exported within\npackages. discourage generation methods external classes,\n.e., classes outside package NAMESPACE. can\npotentially cause method name collisions (.e., two methods defined \nobject different packages) pollute methods environment\nexternal classes. New methods established classes can also cause\nconfusion among users given new method class definition \nseparate packages.","code":""},{"path":"r-code.html","id":"rcode-file-names","chapter":"15 R code","heading":"15.2.4 File names","text":"Filename extension R code ‘.R’. Use prefix\n‘methods-’ S4 class methods, e.g., ‘methods-coverage.R’. Generic\ndefinitions can listed single file, ‘AllGenerics.R’, \nclass definitions ‘AllClasses.R’.Filename extension man pages ‘.Rd’.","code":""},{"path":"r-code.html","id":"class-development","chapter":"15 R code","heading":"15.2.5 Class development","text":"Remember re-use common Bioconductor methods classes\nimplementing new representations. encourages\ninteroperability simplifies package development.","code":""},{"path":"r-code.html","id":"class-names","chapter":"15 R code","heading":"15.2.5.1 Class Names","text":"Use CamelCaps: initial upper case, alternate case words.","code":""},{"path":"r-code.html","id":"class-design","chapter":"15 R code","heading":"15.2.5.2 Class design","text":"Bioconductor prefers use S4 classes S3 class. Please use S4\nrepresentation designing new classes. , can emphasize enough \nreuse existing class structure possible. existing class\nstructure sufficient, also encouraged look extending \ncontaining existing Bioconductor class.data requires new representation function, carefully\ndesign S4 class generic package developers \nsimilar needs able re-use hard work, users\nrelated packages able seamlessly use data\nstructures. hesitate ask Bioc-devel mailing list \nadvice.class define, implement use ‘constructor’ object\ncreation. constructor usually plain-old-function (rather ,\ne.g., generic methods). provides documented \nuser-friendly arguments, allowing developer-friendly\nimplementation. Use constructor throughout code,\nexamples, vignette.Implement show() method effectively convey information \nusers without overwhelming detail.Accessors (simple functions return components object)\nrather direct slot access (using @) help isolate \nimplementation class interface. Generally @ \nused accessor, code use \naccessor. accessor need exported class \nuser need business accessing parts data\nobject. Plain-old-functions (rather generic + method) often\nsufficient accessors; ’s often useful employ (consistently) \nlightweight name mangling scheme (e.g., starting accessor method\nname 2 3 letter acronym package) avoid name\ncollisions similarly named functions packages.following layout sometimes used organize classes \nmethods; approaches possible acceptable.class definitions R/AllClasses.RAll generic function definitions R/AllGenerics.RMethods defined file named generic function. \nexample, show methods go R/show-methods.R.Collate: field DESCRIPTION file may necessary order\nclass method definitions appropriately package\ninstallation.","code":""},{"path":"r-code.html","id":"function-development","chapter":"15 R code","heading":"15.2.6 Function development","text":"","code":""},{"path":"r-code.html","id":"rcode-function-names","chapter":"15 R code","heading":"15.2.6.1 Functions Names","text":"Function names follow following conventions:Use camelCase: initial lower case, alternate case words.use ‘.’ (S3 class system, (x) x class dispatch .).Prefix non-exported functions ‘.’.","code":""},{"path":"r-code.html","id":"functional-programming-and-length","chapter":"15 R code","heading":"15.2.6.2 Functional Programming and Length","text":"Guiding principle: Smaller functions easier read, test, debug reuse.Avoid large chunks repeated code. code repeated \ngenerally good indication helper function implemented.Avoid large chunks repeated code. code repeated \ngenerally good indication helper function implemented.Excessively long functions also avoided. Write small functions.Excessively long functions also avoided. Write small functions.best function one job needs . \nalso best function job lines code possible.\nfind writing great long functions extend \nscreen, probably take moment split smaller\nhelper functions.best function one job needs . \nalso best function job lines code possible.\nfind writing great long functions extend \nscreen, probably take moment split smaller\nhelper functions.Nesting functions avoiding. unnecessarily increases main\nfunction length makes main function harder read. Helper functions\ninternal functions avoid nested include end \nfile seperate file (e.g. internal.R, helpers.R, utils.R)Nesting functions avoiding. unnecessarily increases main\nfunction length makes main function harder read. Helper functions\ninternal functions avoid nested include end \nfile seperate file (e.g. internal.R, helpers.R, utils.R)","code":""},{"path":"r-code.html","id":"function-arguments","chapter":"15 R code","heading":"15.2.6.3 Function arguments","text":"Argument names functions descriptive well documented.Arguments generally default values.Check arguments validity check stopifnot","code":""},{"path":"r-code.html","id":"variable-names","chapter":"15 R code","heading":"15.2.6.4 Variable names","text":"Use camelCase: initial lowercase, alternate case words.","code":""},{"path":"r-code.html","id":"rcode-sysdep","chapter":"15 R code","heading":"15.2.6.5 Additional files and dependencies","text":"install anything users system.System dependencies, applications, additionally needed packages \nassumed already present user’s system.necessary, package maintainers provide instructions download \nsetup, execute instructions behalf \nuser. Complicated additional system dependency instructions part \nREADME file /INSTALL file. package\ndependencies must actively CRAN Bioconductor.system package dependencies latest publically available\nversion.","code":""},{"path":"r-code.html","id":"rcode-namespaces","chapter":"15 R code","heading":"15.2.6.6 Namespaces","text":"Import symbols used packages “base”. Except \ndefault packages (base, graphics, stats, etc.) overly\ntedious, fully enumerate imports.Export symbols useful end users. Fully enumerate exports.","code":""},{"path":"r-code.html","id":"coding-style","chapter":"15 R code","heading":"15.2.7 Coding Style","text":"may seem arbitrary, consistent coding style helps \nunderstand, evaluate, debug code easier. optional, \nhighly encouraged.","code":""},{"path":"r-code.html","id":"indentation","chapter":"15 R code","heading":"15.2.7.1 Indentation","text":"Use 4 spaces indenting. tabs.lines longer 80 characters.","code":""},{"path":"r-code.html","id":"use-of-space","chapter":"15 R code","heading":"15.2.7.2 Use of space","text":"Always use space comma. : , b, c.space around “=” using named arguments functions. :\nsomefunc(=1, b=2)Space around binary operators: == b.","code":""},{"path":"r-code.html","id":"rcode-comments","chapter":"15 R code","heading":"15.2.7.3 Comments","text":"Use “##” start full-line comments.Indent level surrounding code.Comments clarification, notes, documentation .leave commented code chunks utilizedCommenting TODO’s avoided published package code","code":""},{"path":"r-code.html","id":"additonal-style-and-formatting-references","chapter":"15 R code","heading":"15.2.7.4 Additonal style and formatting references","text":"formatR package assists formatting.formatR package assists formatting.Hadley Wickhams’s R Style Guide.Hadley Wickhams’s R Style Guide.","code":""},{"path":"r-code.html","id":"r-code-best-practices-and-guidelines","chapter":"15 R code","heading":"15.3 R Code Best Practices and Guidelines","text":"Many common coding syntax issues flagged R CMD check \nBiocCheck() (see R CMD check\ncheatsheet BiocCheck vignette. Every\neffort made clear ERROR, WARNING, NOTEs produced \nchecks.","code":""},{"path":"r-code.html","id":"code-syntax-and-efficiency","chapter":"15 R code","heading":"15.3.1 Code syntax and efficiency","text":"Use vapply() instead sapply(), use various apply functions instead loops. See section vectorize.Use seq_len() seq_along() instead 1:.... See section avoid 1:n style iterationsUse TRUE FALSE instead T F.Use numeric indices lower level interfaces (e.g., internal subset ops) computational efficiency.Use named indices higher level interfaces (e.g., function arguments) robustness.Use () instead class() == class() !=.Use system2() instead system().use set.seed() internal code.use browser() internal code.Avoid use <<-.Avoid use direct slot access @ slot(). Accessor methods created utilizedUse packages ExperimentHub AnnotationHub instead downloading external data unsanctioned providers GitHub, <* class=“fa fa-dropbox” aria-hidden=“true”> Dropbox, etc. general, data utlilized packages downloaded trusted public databases. See also section web querying file caching.Use <- instead = assigning variables except function arguments.","code":""},{"path":"r-code.html","id":"cyclomatic-complexity","chapter":"15 R code","heading":"15.3.2 Cyclomatic Complexity","text":"metric developed Thomas J. McCabe, cyclomatic complexity describes \ncontrol-flow program. higher value, complex code \nsaid .BiocCheck example , series control-flow statements\ncheck multiple conditions return value \nconditions true. function hasValueSection checking \ndocumentation contains ‘value’ Rd tag .e., return section \ndocumentation.can see, code quite complex, creating statements \nspecific conditions. measured cyclomatic complexity given \ncyclocomp package value 16.Let’s re-write function reduce complexity use base character\nvector representation.internalizing base character vector representation code, \nsuccessive functions operate representation. gives us code\nless complex easier understand maintain complexity\nmetric value 2.Note. Switches based docType outside function filter\nmanpage input instead.","code":"\nhasValueSection <- function(manpage) {\n rd <- tools::parse_Rd(manpage)\n type <- BiocCheck:::docType(rd)\n if (identical(type, \"data\"))\n return(TRUE)\n tags <- tools:::RdTags(rd)\n if (\"\\\\usage\" %in% tags && (!\"\\\\value\" %in% tags))\n return(FALSE)\n value <- NULL\n if (\"\\\\value\" %in% tags)\n value <- rd[grep(\"\\\\value\", tags)]\n if (\"\\\\usage\" %in% tags && (!\"\\\\value\" %in% tags)) {\n values <- paste(unlist(value), collapse='')\n test <- (is.list(value[[1]]) && length(value[[1]]) == 0) ||\n nchar(gsub(\" \", \"\", values)) == 0\n if (test)\n return(FALSE)\n }\n TRUE\n}\nlibrary(cyclocomp)\ncyclocomp(hasValueSection)\n#> [1] 16\nhasValueSection2 <- function(manpage) {\n rd <- tools::parse_Rd(manpage)\n tags <- tools:::RdTags(rd)\n value <- rd[grepl(\"\\\\value\", tags)]\n value <- unlist(value, recursive = FALSE)\n value <- Filter(function(x) attr(x, \"Rd_tag\") != \"COMMENT\", value)\n values <- paste(value, collapse='')\n nzchar(trimws(values)) && length(value)\n}\ncyclocomp(hasValueSection2)\n#> [1] 2"},{"path":"r-code.html","id":"end-user-messages","chapter":"15 R code","heading":"15.3.2.1 End-User messages","text":"Use functions message(), warning() error(), instead \ncat() function (except customized show() methods). paste0() \ngenerally used methods except collapsing multiple values\nvariable.message() communicates diagnostic messages (e.g., progress \nlengthy computations) code evaluation.warning() communicates unusual situations handled code.stop() indicates error condition.cat() print() used displaying object user show method.","code":""},{"path":"r-code.html","id":"graphic-device","chapter":"15 R code","heading":"15.3.2.2 Graphic Device","text":"Use dev.new() start graphics drive necessary. Avoid using x11()\nX11(), can called machines access X\nserver.","code":""},{"path":"r-code.html","id":"web-querying-and-file-caching","chapter":"15 R code","heading":"15.3.2.3 Web Querying and File caching","text":"Files downloaded cached.\nPlease use BiocFileCache.\nmaintainer creates caching directory, utilize standard\ncaching directories tools::R_user_dir(package, =\"cache\"). \nallowed download write files users home directory, working\ndirectory, installed package directory. Files cached stated\nBiocFileCache (preferred) R_user_dir tempdir()/tempfile()\nfiles persistent.Please also follow guiding principles Appendix section Querying Web\nResources, applicable.","code":""},{"path":"r-code.html","id":"robust-and-efficient-r-code","chapter":"15 R code","heading":"15.4 Robust and Efficient R Code","text":"R can robust, fast efficient programming language, \ncoding practices can unfortunate. suggestions.","code":""},{"path":"r-code.html","id":"guiding-principles","chapter":"15 R code","heading":"15.4.1 Guiding Principles","text":"primary principle make sure code correct. Use\nidentical() .equal() ensure correctness, \nunit tests ensure consistent results across code revisions.primary principle make sure code correct. Use\nidentical() .equal() ensure correctness, \nunit tests ensure consistent results across code revisions.Write robust code. Avoid efficiencies easily handle\nedge cases 0 length NA values.Write robust code. Avoid efficiencies easily handle\nedge cases 0 length NA values.Know stop trying efficient. code takes \nfraction second evaluate, sense trying \nimprovement. Use system.time() package like\nmicrobenchmark quantify performance gains.Know stop trying efficient. code takes \nfraction second evaluate, sense trying \nimprovement. Use system.time() package like\nmicrobenchmark quantify performance gains.","code":""},{"path":"r-code.html","id":"reuse-existing-functionality-and-classes","chapter":"15 R code","heading":"15.4.2 Reuse Existing Functionality and Classes","text":"Emphasized good measure! Reuse existing import/export methods,\nfunctionality, classes whenever possible.","code":""},{"path":"r-code.html","id":"vectorize","chapter":"15 R code","heading":"15.4.3 Vectorize","text":"Many R operations performed whole object, just elements \nobject (e.g., sum(x) instead x[1] + x[2] + x[2] + ...). \nparticular, relatively situations require explicit loop.Vectorize, rather iterate (loops, lapply(), apply() \ncommon iteration idioms R). single call y <- sqrt(x) \nvector x length n example vectorized function. \ncall y <- sapply(x, sqrt) loop (seq_along(x)) y[] <- sqrt(x[]) iterative version \ncall, avoided. Often, iterative calculations can \nvectorized “hidden” body loopand can ‘hoisted’ loopOften principle can applied repeatedly, iterative\nloop becomes lines vectorized function calls.","code":"for (i in seq_len(n)) {\n ## ...\n tmp <- foo(x[i])\n y <- tmp + ## ...\n}tmp <- foo(x)\nfor (i in seq_len(n)) {\n ## ...\n y <- tmp[i] + ##\n}"},{"path":"r-code.html","id":"pre-allocate-and-fill-if-iterations-are-necessary","chapter":"15 R code","heading":"15.4.4 ‘Pre-allocate and fill’ if iterations are necessary","text":"Preallocate--fill (usually via lapply() vapply()) rather\ncopy--append. creating vector list results, use\nlapply() (create list) vapply() (create vector)\nrather loop. instance,manages memory allocation x compactly represents \ntransformation performed. loop might appropriate \niteration side effects (e.g., displaying plot) \ncalculation one value depends previous value. creating \nvector loop, always pre-allocate resultNever adopt strategy ‘copy--append’pattern copies current value x time \nloop, making n^2 / 2 total copies, scale poorly even \ntrivial computations:","code":"n <- 10000\nx <- vapply(seq_len(n), function(i) {\n ## ...\n}, integer(1))x <- integer(n)\nif (n > 0) x[1] <- 0\nfor (i in seq_len(n - 1)) {\n ## x[i + 1] <- ...\n}not_this <- function(n) {\n x <- integer()\n for (i in seq_len(n))\n x[i] = i\n x\n}> system.time(not_this(1000)\n user system elapsed\n 0.004 0.000 0.004\n> system.time(not_this(10000))\n user system elapsed\n 0.169 0.000 0.168\n> system.time(not_this(100000))\n user system elapsed\n 22.827 1.120 23.936"},{"path":"r-code.html","id":"avoid-1n-style-iterations","chapter":"15 R code","heading":"15.4.5 Avoid 1:n style iterations","text":"Write seq_len(n) seq_along(x) rather 1:n \n1:length(x). protects case n length(x)\n0 (often occurs unexpected ‘edge case’ real code) \nnegative.","code":""},{"path":"r-code.html","id":"parallel-recommendations","chapter":"15 R code","heading":"15.4.6 Parallel Recommendations","text":"recommend using BiocParallel. provides \nconsistent interface user supports major parallel computing\nstyles: forks processes single computer, ad hoc clusters,\nbatch schedulers cloud computing. default, BiocParallel\nchooses parallel back-end appropriate OS supported\nacross Unix, Mac Windows. Coding requirements BiocParallel\n:Use lapply()-style iteration instead explicit loops.FUN argument bplapply() must self-contained\nfunction; symbols used function default R\npackages, packages require()’ed function, passed \narguments.Allow user specify BiocParallel back-end. \ninvoking bplapply() without specifying BPPARAM; user can\noverride default choice BiocParallel::register().information see BiocParallel vignette.implementing package development, minimal number cores (1 2)\nset default.","code":""},{"path":"other-than-Rcode.html","id":"other-than-Rcode","chapter":"16 Fortran / C / C++ / Python / Third-Party Code","heading":"16 Fortran / C / C++ / Python / Third-Party Code","text":"package contains C Fortran code, adhere standards \nmethods described System foreign language interfaces\nsection Writing R Extensions manual.","code":""},{"path":"other-than-Rcode.html","id":"makevars","chapter":"16 Fortran / C / C++ / Python / Third-Party Code","heading":"16.1 Makevars","text":"Make judicious use Makevars Makefile files within package.\noften required (See Configure cleanup section Writing R Extensions manual).","code":""},{"path":"other-than-Rcode.html","id":"fortran","chapter":"16 Fortran / C / C++ / Python / Third-Party Code","heading":"16.2 Fortran","text":"Consider utilizing dotCall64 CRAN package.","code":""},{"path":"other-than-Rcode.html","id":"ccode","chapter":"16 Fortran / C / C++ / Python / Third-Party Code","heading":"16.3 C / C++","text":"Rcpp CRAN package allows seamless integration C++ R, \ncross-platform. package affords many benefits \nR C interface make C++ appealing language, \neliminating many pitfalls programming R interface.package well documented, extensive repository \nworking examples many tasks: Rcpp Gallery.","code":""},{"path":"other-than-Rcode.html","id":"python","chapter":"16 Fortran / C / C++ / Python / Third-Party Code","heading":"16.4 Python","text":"basilisk package required integrate python R packages. \nreticulate alternative, developer must make strong argument \nbasilisk used.","code":""},{"path":"other-than-Rcode.html","id":"third-party-code","chapter":"16 Fortran / C / C++ / Python / Third-Party Code","heading":"16.5 Other","text":"Use external libraries whose functionality redundant libraries\nalready supported strongly discouraged. cases external library\ncomplex, author may need supply pre-built binary versions \nplatforms.including third-party code package maintainer assumes responsibility \nmaintenance code. Part maintenance responsibility includes\nkeeping code date bug fixes updates released \nmainline third-party project.","code":""},{"path":"shiny.html","id":"shiny","chapter":"17 Shiny apps","heading":"17 Shiny apps","text":"Shiny apps can submitted Bioconductor software packages documented tested functions within packages.","code":""},{"path":"shiny.html","id":"code-organisation","chapter":"17 Shiny apps","heading":"17.1 Code organisation","text":"Shiny apps divided two parts:User interface (UI)ServerShiny apps submitted Bioconductor must store code UI server code R/ directory package.bulk package code implemented directly within shinyApp() function call.\nInstead, internal package functions developed produce return individual components UI server sides Shiny app.Shiny apps can also written using shiny modules allow \nbetter code organisation re-usability.recommend following file naming scheme source files:Place internal functions create observers – e.g., shiny::observeEvent() – files named observers_*.R.\nobservers reacting Shiny server input object, reactive values stored lists reactive values (e.g., shiny::reactiveValues()).Place internal functions create UI elements – e.g., shiny::checkboxInput() – files named interface_*.R.Place internal functions update Shiny server output object files named outputs_*.R.Place internal functions perform miscellaneous processing steps files named utils_*.R.","code":""},{"path":"shiny.html","id":"running-app","chapter":"17 Shiny apps","heading":"17.2 Running app","text":"Functions package return Shiny apps, launch .words, function shiny::runApp() found anywhere package source code.\nInstead, users left call function, using Shiny app objects returned package functions options control app run (e.g., launch.browser = TRUE).instance, package source code look follows:user’s code look follows:","code":"\nbuild_app <- function(...) {\n ui <- .build_ui(...)\n server <- .build_server(...)\n app <- shinyApp(ui = ui, server = server)\n}\napp <- build_app(...)\nshiny::runApp(app, ...)"},{"path":"shiny.html","id":"building-the-package","chapter":"17 Shiny apps","heading":"17.3 Building the package","text":"Packages shiny apps built using standard R CMD build\ncommand. package structure follow standard R package structure,\nShiny app code stored R/ directory.:optional app.R file can added base directory package \nlaunch Shiny app using shiny::runApp() main shiny app deployment\nfunction.","code":"MyShinyPackage/\n|-- app.R\n|-- DESCRIPTION\n|-- NAMESPACE\n|-- R/\n| |-- interface_*.R\n| |-- observers_*.R\n| |-- outputs_*.R\n| |- server_*.R\n| └- utils.R\n|-- tests/\n|-- vignettes/\n|-- man/\n|-- inst/\n[...]"},{"path":"shiny.html","id":"testing","chapter":"17 Shiny apps","heading":"17.4 Testing","text":"plain non-reactive functions package testable using\nstandard unit testing tools (e.g., testthat).use # nocov start # nocov end allowed ignore part code tested using traditional unit tests (e.g., observeEvent).instance:Use files setup-*.R subdirectory tests/testthat/ generate objects used repeatedly input unit tests.recommended use shinytest2 package \ntest visual computational aspects Shiny apps.","code":"\n# nocov start\nobserveEvent(input$example_input, {\n # \n})\n# nocov end"},{"path":"shiny.html","id":"documentation","chapter":"17 Shiny apps","heading":"17.5 Documentation","text":"Man pages documenting functions return Shiny apps use interactive() function demonstrate usage app.instance, typical ‘Example’ section man page look follows:Although optional, highly recommend documenting internal functions \npackages contain Shiny apps. recommend way visible\ndevelopers users:using roxygen2, use tag @keywords internal\nRoxygen block. keep documentation package \nremove help page index. may want increase visibility \ninternal documentation linking help pages within package\n(e.g., within “developers” section).example:Alternatively (though less common), prefix manual pages INTERNAL_*\nadd man/.gitignore.set name Rd document, use @name tag Roxygen block:Additionally, vignette shiny app package might include screenshots, either generated manually programmatically.\ngenerated manually, developers can use tools pngquant (available command line utility GUI systems) reduce size (70%) without much loss quality.\nProgrammatically generated screenshots can realized means Webshot2 package, using webshot2::appshot() function.","code":"\nlibrary(MyShinyPackage)\n\napp <- build_app(...)\n\nif (interactive()) {\n shiny::runApp(app, ...)\n}\n#' @keywords internal\n.build_app <- function(...) {\n ...\n}\n#' @name INTERNAL_build_app\n.build_app <- function(...) {\n ...\n}"},{"path":"shiny.html","id":"review","chapter":"17 Shiny apps","heading":"17.6 Review","text":"reviewing shiny app package, reviewer check package\nfollows guidelines outlined document.highly recommend reviewers use shinytest2\npackage test visual computational aspects Shiny app \naddition standard unit tests plain functions.Reviewers also check package documentation complete \naccurate, package passes BiocCheck \naddition R CMD build check.user experience important. Reviewers ensure app \nresponsive user interface intuitive easy--use. app\ncrash hang user interacts .Errors warnings handled gracefully visible \nintelligible user. recommend using\nshinytoastr display error, warning, info\nmessages user.","code":""},{"path":"non-software.html","id":"non-software","chapter":"18 Non-Software Packages","heading":"18 Non-Software Packages","text":"packages contributed users software packages. However, \ninstances package types submitted. following sections \ngo specifics look non-software type packages.","code":""},{"path":"non-software.html","id":"annotation-and-experiment-data-packages","chapter":"18 Non-Software Packages","heading":"18.1 Annotation and Experiment data packages","text":"Annotation packages database-like packages provide information linking\nidentifies (e.g., Entrez gene names Affymetrix probe ids) \ninformation (e.g., chromosomal location, Gene Ontology category).Experiment data packages provide data sets used, often software\npackages, illustrate particular analyses. packages contain curated\ndata experiment, teaching course publication cases\ncontain single data set.look similar requirements software packages, importantly \nproper documentation data included within package. Traditional\nAnnotation Experiment packages ideal; AnnotationHub \nExperimentHub interfaces packages desirable.","code":""},{"path":"non-software.html","id":"annotationexperiment-hub-packages","chapter":"18 Non-Software Packages","heading":"18.2 Annotation/Experiment Hub packages","text":"light weight packages related resources added \nAnnotationHub \nExperimentHub. package minimally contain\nresource metadata, man pages describing resources, vignette. \nmay also contain supporting R function author wants provide. \npackages similar Annotation Experiment data packages except\ndata stored provided Bioconductor Microsoft Azure Data Lakes\npublicly accessibly sites (ensembl, AWS S3 buckets, etc) instead \npackage .information creating hub packages well contents\nCreate Hub Package vignette within \nHubPub Bioconductor package.","code":""},{"path":"non-software.html","id":"workflow-packages","chapter":"18 Non-Software Packages","heading":"18.3 Workflow packages","text":"Workflow packages contain vignettes describe bioinformatics workflow\ninvolves multiple Bioconductor packages. vignettes usually \nextensive vignettes accompany software packages. packages \nneed man/ R/ directories data/ directory ideally\nworkflows make use existing data Bioconductor package.Existing WorkflowsWorkflow vignettes may deal larger data sets /computationally intensive\ntypical Bioconductor package vignettes. reason, automated builder \nproduces vignettes time limit (contrast Bioconductor package\nbuilding system time package building takes long). \nexpected majority vignette code chunks evaluated.","code":""},{"path":"non-software.html","id":"submit-workflow","chapter":"18 Non-Software Packages","heading":"18.3.1 How do I write and submit a workflow vignette?","text":"Write package name workflow. workflow vignette\nwritten Markdown, using rmarkdown package included \nvignette directory. may include one vignette please use\nuseful identifying names.Write package name workflow. workflow vignette\nwritten Markdown, using rmarkdown package included \nvignette directory. may include one vignette please use\nuseful identifying names.package need man/ R/ directories data/ directory \nideally workflows make use existing data Bioconductor repository \nweb; workflow package contain large data files.package need man/ R/ directories data/ directory \nideally workflows make use existing data Bioconductor repository \nweb; workflow package contain large data files.DESCRIPTION file, include line “BiocType: Workflow”. Please also\ninclude detailed Description field DESCRIPTION file. DESCRIPTION\nfile contain biocViews Workflow\nbranch. think new term relevant please reach \nlori.shepherd@roswellpark.org.DESCRIPTION file, include line “BiocType: Workflow”. Please also\ninclude detailed Description field DESCRIPTION file. DESCRIPTION\nfile contain biocViews Workflow\nbranch. think new term relevant please reach \nlori.shepherd@roswellpark.org.Submit package GitHub submission tracker formal\nreview. Please also indicate tracker issue package \nworkflow.Submit package GitHub submission tracker formal\nreview. Please also indicate tracker issue package \nworkflow.Workflows git version controlled. package accepted \nadded git repository git@git.bioconductor.org instructions \nsent gaining access maintainence.Workflows git version controlled. package accepted \nadded git repository git@git.bioconductor.org instructions \nsent gaining access maintainence.","code":""},{"path":"non-software.html","id":"consistent-formatting","chapter":"18 Non-Software Packages","heading":"18.3.2 Consistent formatting","text":"effort standardize workflow vignette format, strongly\nencouraged use either BiocStyle formatting \nutilize BiocWorkflowTools. following header\nshows use BiocStyle vignette:\noutput:\n BiocStyle::html_documentIn effort standardize workflow vignette format, strongly\nencouraged use either BiocStyle formatting \nutilize BiocWorkflowTools. following header\nshows use BiocStyle vignette:following also include\n- author affiliations\n- date representing workflow vignette modifiedThe following also includeThe first section versioning information. R version,\nBioconductor version, package version visible.\nfollowing example achieved:first section versioning information. R version,\nBioconductor version, package version visible.\nfollowing example achieved:example start workflow vignette:following taken example header variants workflow package:","code":"output:\n BiocStyle::html_document- author affiliations\n- a date representing when the workflow vignette has been modified\n \n

\n**R version**: `r R.version.string`\n
\n**Bioconductor version**: `r BiocManager::version()`\n
\n**Package version**: `r packageVersion(\"annotation\")`\n<\/p>\n \n\n \n– – –\ntitle: Annotating Genomic Variants\nauthor: \n–name: Valerie Obenchain\n affiliation: Fred Hutchinson Cancer Research Center, 1100 Fairview Ave. N., P.O. Box 19024, Seattle, WA, USA 98109–1024\ndate: 11 April 2018\nvignette: >\n %\\VignetteIndexEntry{Annotating Genomic Variants}\n %\\VignetteEngine{knitr::rmarkdown}\noutput: \n BiocStyle::html_document\n– – –\n\n\n# Version Info\n```{r, echo=FALSE, results=\"hide\", warning=FALSE}\nsuppressPackageStartupMessages({library('variants')})\n```\n

\n**R version**: `r R.version.string`\n
\n**Bioconductor version**: `r BiocManager::version()`\n
\n**Package version**: `r packageVersion(\"variants\")`\n<\/p>\n\n\n \n"},{"path":"non-software.html","id":"tidying-package-loading-output","chapter":"18 Non-Software Packages","heading":"18.3.3 Tidying package loading output","text":"workflows load number packages want\noutput loading packages clutter workflow\ndocument. ’s solve markdown; can\nsomething similar Latex.First, set code chunk evaluated echoed, whose\nresults hidden. also set warning=FALSE sure \noutput chunk ends document:can set another code chunk echoed,\nalmost contents. second invocation library()\nproduce output since package already loaded:","code":"```{r, echo=FALSE, results=\"hide\", warning=FALSE}\nsuppressPackageStartupMessages({\nlibrary(GenomicRanges)\nlibrary(GenomicAlignments)\nlibrary(Biostrings)\nlibrary(Rsamtools)\nlibrary(ShortRead)\nlibrary(BiocParallel)\nlibrary(rtracklayer)\nlibrary(VariantAnnotation)\nlibrary(AnnotationHub)\nlibrary(BSgenome.Hsapiens.UCSC.hg19)\nlibrary(RNAseqData.HNRNPC.bam.chr14)\n})\n``````{r}\nlibrary(GenomicRanges)\nlibrary(GenomicAlignments)\nlibrary(Biostrings)\nlibrary(Rsamtools)\nlibrary(ShortRead)\nlibrary(BiocParallel)\nlibrary(rtracklayer)\nlibrary(VariantAnnotation)\nlibrary(AnnotationHub)\nlibrary(BSgenome.Hsapiens.UCSC.hg19)\nlibrary(RNAseqData.HNRNPC.bam.chr14)\n```"},{"path":"non-software.html","id":"citations","chapter":"18 Non-Software Packages","heading":"18.3.4 Citations","text":"manage citations workflow document,\nspecify bibliography file document metadata header.can use citation keys form [@label] cite entry identifier “label”.Normally, want end document section header “References” similar, bibliography appended.details see rmarkdown documentation.","code":"bibliography: references.bib"},{"path":"gitignore.html","id":"gitignore","chapter":"19 The .gitignore file","heading":"19 The .gitignore file","text":"Bioconductor requires Git repository submission.certain system files tracked repository \nunacceptable include. files can remain local system \nexcluded Git repository possible including \n.gitignore file.following files checked BiocCheck flagged unacceptable:one .gitignore file top level package\ndirectory.","code":"\nhidden_file_ext = c(\n \".renviron\", \".rprofile\", \".rproj\", \".rproj.user\", \".rhistory\",\n \".rapp.history\", \".o\", \".sl\", \".so\", \".dylib\", \".a\", \".dll\",\n \".def\", \".ds_store\", \"unsrturl.bst\", \".log\", \".aux\", \".backups\",\n \".cproject\", \".directory\", \".dropbox\", \".exrc\", \".gdb.history\",\n \".gitattributes\", \".gitmodules\", \".hgtags\", \".project\", \".seed\",\n \".settings\", \".tm_properties\"\n)"},{"path":"conclusion.html","id":"conclusion","chapter":"20 Conclusion","heading":"20 Conclusion","text":"exercise Build Bioconductor Package RStudio may also helpful.Remember every Bioconductor package goes formal review\nprocess may still receive technical feedback assigned\nBioconductor reviewer.overview submission process may found previous\nsection package may submitted \nGitHub package submission repository.Thank reading guidelines, welcome Bioconductor\ncommunity users developers!","code":""},{"path":"package-maintenance.html","id":"package-maintenance","chapter":"Overview","heading":"Overview","text":"section offers useful tools help pages continued maintenance \ndevelopment packages already existing Bioconductor.","code":""},{"path":"git-version-control.html","id":"git-version-control","chapter":"21 Git Version Control","heading":"21 Git Version Control","text":"Bioconductor project maintained Git source control\nsystem. Package maintainers update packages pushing changes\ngit repositories.chapter contains several sections cover typical scenarios\nencountered adding maintaining Bioconductor package.","code":""},{"path":"git-version-control.html","id":"essential-work-flow","chapter":"21 Git Version Control","heading":"21.1 Essential work flow","text":"minimal workflow checkout, update, commit, push changes \nrepository. Using BiocGenerics example:requires Bioconductor knows SSH keys use \nestablish identity.Two useful commands areIf repository already cloned, work flow make sure\n‘devel’ branch, pull changes, introduce\nedits.","code":"git clone git@git.bioconductor.org:packages/BiocGenerics\ncd BiocGenerics\n## add a file, e.g., `touch README`\n## edit file, e.g., `vi DESCRIPTION`\nBiocGenerics$ git commit README DESCRIPTION\nBiocGenerics$ git pushBiocGenerics$ git diff # review changes prior to commit\nBiocGenerics$ git log # review recent commitsBiocGenerics$ git checkout devel\nBiocGenerics$ git pull\n## add, edit, commit, and push as above"},{"path":"git-version-control.html","id":"where-to-commit-changes","chapter":"21 Git Version Control","heading":"21.2 Where to Commit Changes","text":"New features bug fixes introduced devel branch GIT\nrepository.make extensive changes see Fix bugs devel release.Bug fixes can ported current release branch. Use\ncherry-pick identify commmit(s) like port. E.g.,\nrelease 3.6, porting recent commit devel","code":"BiocGenerics$ git checkout devel\nBiocGenerics$ git pull\n## edit 'R/foo.R' and commit on devel\nBiocGenerics$ git commit R/foo.R #\n[devel c955179] your commit message\n1 file changed, 10 insertions(+), 3 deletions(-)\nBiocGenerics$ git pushBiocGenerics$ git checkout RELEASE_3_6\nBiocGenerics$ git cherry-pick devel\nBiocGenerics$ git push"},{"path":"git-version-control.html","id":"checks-and-version-bumps","chapter":"21 Git Version Control","heading":"21.3 Checks and version bumps","text":"commit pushed Bioconductor repository build \ncheck without errors warningsEach commit, either release devel, include bump \nz portion x.y.z package versioning scheme.Builds occur per day, take approximately 24 hours. See \nbuild report git commits captured recent build\n(upper left corner)","code":"BiocGenerics$ cd ..\nR CMD build BiocGenerics\nR CMD check BiocGenerics_1.22.3.tar.gz"},{"path":"git-version-control.html","id":"annotation-packages","chapter":"21 Git Version Control","heading":"21.4 Annotation packages","text":"Traditional Annotation packages stored GIT due size \nannotation files. update existing Annotation package please send email\nmaintainer@bioconductor.org. member Bioconductor team \ncontact receive updated package.Newer annotation packages can stored GIT requirement use \nAnnotationHub server hosted data. larger sized\nfiles included directly package. contribute new Annotation\npackage please contact hubs@bioconductor.org guidance read \ndocumentation Create Hub Package.Currently direct updates annotation packages, even stored git, \nsupported. wish updated annotation package, make required\nchanges push git.bioconductor.org. send email \nhubs@bioconductor.org maintainer@bioconductor.org requesting package propagated.","code":""},{"path":"git-version-control.html","id":"subversion-to-git-transition","chapter":"21 Git Version Control","heading":"21.5 Subversion to Git Transition","text":"essential steps transitioning SVN git summarized\ninNew package workflow: update GitHub repository \npackage acceptance.Create new GitHub repository existing package.Maintain Bioconductor-repository existing\npackage.","code":""},{"path":"git-version-control.html","id":"new-package-workflow","chapter":"21 Git Version Control","heading":"21.5.1 New package workflow","text":"Goal: developed package GitHub, following \nBioconductor new package Contributions README guidelines,\nsubmitted Bioconductor, package \nmoderated. part moderation process, package reviewed\nadded repository Bioconductor git server.review process, package authors must push changes\ninclude version number ‘bump’ Bioconductor git\nrepository. causes package built checked Linux,\nmacOS, Windows operating systems, forms basis \nreview process.document, package authors learn best practices \npushing Bioconductor git repository.SSH keys. part initial moderation step,\nBioconductor use SSH ‘public key’ keys available \nhttps://github.com/<-github-id>.keys.\nreview process , additional SSH keys can added\ncontact information edited using BiocCredentials\napplication.SSH keys. part initial moderation step,\nBioconductor use SSH ‘public key’ keys available \nhttps://github.com/<-github-id>.keys.review process , additional SSH keys can added\ncontact information edited using BiocCredentials\napplication.Configure “remotes” local git repository. need\npush future changes package Bioconductor git\nrepository issue new build package.\nAdd remote named upstream package’s local git\nrepository using:\n git remote add upstream git@git.bioconductor.org:packages/<-REPOSITORY-NAME>.git\nCheck updated remotes repository; ’ll\nsee origin remote pointing github.com, upstream remote\npointing bioconductor.org\n $ git remote -v\n\n origin (fetch)\n origin (push)\n upstream git@git.bioconductor.org:packages/<-REPOSITORY-NAME>.git (fetch)\n upstream git@git.bioconductor.org:packages/<-REPOSITORY-NAME>.git (push)\nNOTE: package developer, must use SSH protocol (\ncommand) gain read/write access package \nBioconductor git repository.Configure “remotes” local git repository. need\npush future changes package Bioconductor git\nrepository issue new build package.Add remote named upstream package’s local git\nrepository using:Check updated remotes repository; ’ll\nsee origin remote pointing github.com, upstream remote\npointing bioconductor.orgNOTE: package developer, must use SSH protocol (\ncommand) gain read/write access package \nBioconductor git repository.Add commit changes local repository. \nreview process likely need update package. \nlocal repository first making sure repository \n--date github.com git.bioconductor.org\nrepositories.\n git fetch --\n\n ## merge changes Bioc (upstream remote git@git.bioconductor.org)\n git merge upstream/devel\n\n ## merge changes GitHub (origin remote)\n git merge origin/devel\nNote. GitHub default branch main, replace devel \nmain:\n ## merge changes GitHub (origin remote)\n git merge origin/main\nMake changes package devel branch commit \nlocal repository\n git add \n git commit -m \"\"Add commit changes local repository. \nreview process likely need update package. \nlocal repository first making sure repository \n--date github.com git.bioconductor.org\nrepositories.Note. GitHub default branch main, replace devel \nmain:Make changes package devel branch commit \nlocal repository‘Bump’ package version. package version number \nformat ‘major.minor.patch’. Initial package submissions \nversion number 0.99.0, indicated Version field \nDESCRIPTION file. Increment patch version number 1, e.g., \n0.99.1, 0.99.2, …, 0.99.9, 0.99.10, …\nBumping version number pushing essential. ensures\npackage built across platforms.\nRemember add commit changes local repository.‘Bump’ package version. package version number \nformat ‘major.minor.patch’. Initial package submissions \nversion number 0.99.0, indicated Version field \nDESCRIPTION file. Increment patch version number 1, e.g., \n0.99.1, 0.99.2, …, 0.99.9, 0.99.10, …Bumping version number pushing essential. ensures\npackage built across platforms.Remember add commit changes local repository.Push changes Bioconductor GitHub repositories. Push\nchanges local repository Bioconductor \nGitHub repositories.\n ## push BioC (upstream remote git@git.bioconductor.org)\n git push upstream devel\n\n ## push GitHub (origin remote)\n git push origin devel\nNote. GitHub default branch main, replace devel \nmain:\n ## push Bioc (upstream remote git@git.bioconductor.org)\n git push upstream main:devel\n\n ## push GitHub (origin remote)\n git push origin mainPush changes Bioconductor GitHub repositories. Push\nchanges local repository Bioconductor \nGitHub repositories.Note. GitHub default branch main, replace devel \nmain:Check updated build report. push \ngit.bioconductor.org included version bump, ’ll receive \nemail directing visit issue github.com,\nhttps://github.com/Bioconductor/Contributions/issues/; comment\nalso posted issue indicating build started.\nseveral minutes second email comment indicate \nbuild completed, build report \navailable. comment includes link build report. Follow\nlink see whether changes necessary.Check updated build report. push \ngit.bioconductor.org included version bump, ’ll receive \nemail directing visit issue github.com,\nhttps://github.com/Bioconductor/Contributions/issues/; comment\nalso posted issue indicating build started.several minutes second email comment indicate \nbuild completed, build report \navailable. comment includes link build report. Follow\nlink see whether changes necessary.See scenarios working Bioconductor GitHub repositories, particular:\nMaintain GitHub Bioconductor repositories.\nFix bugs devel release.\nResolve merge conflicts.\nSee scenarios working Bioconductor GitHub repositories, particular:Maintain GitHub Bioconductor repositories.Fix bugs devel release.Resolve merge conflicts.","code":" git remote add upstream git@git.bioconductor.org:packages/.git $ git remote -v\n\n origin (fetch)\n origin (push)\n upstream git@git.bioconductor.org:packages/.git (fetch)\n upstream git@git.bioconductor.org:packages/.git (push) git fetch --all\n\n ## merge changes from Bioc (upstream remote at git@git.bioconductor.org)\n git merge upstream/devel\n\n ## merge changes from GitHub (origin remote)\n git merge origin/devel ## merge changes from GitHub (origin remote)\n git merge origin/main git add \n git commit -m \"\" ## push to BioC (upstream remote at git@git.bioconductor.org)\n git push upstream devel\n\n ## push to GitHub (origin remote)\n git push origin devel ## push to Bioc (upstream remote at git@git.bioconductor.org)\n git push upstream main:devel\n\n ## push to GitHub (origin remote)\n git push origin main"},{"path":"git-version-control.html","id":"maintain-github-bioc","chapter":"21 Git Version Control","heading":"21.5.2 Create a new GitHub repository for an existing Bioconductor package","text":"Goal: maintainer, ’d like create new GitHub\nrepository existing Bioconductor repository, \nuser community can engage development package.Create new GitHub account don’t one.Create new GitHub account don’t one.Set remote access GitHub via SSH Https. Please check\n-remote-url---use \nadd public key GitHub account.Set remote access GitHub via SSH Https. Please check\n-remote-url---use \nadd public key GitHub account.submitted keys, can login \nBiocCredentials application check correct\nkeys file Bioconductor.submitted keys, can login \nBiocCredentials application check correct\nkeys file Bioconductor.Create new GitHub repo account, name\nexisting Bioconductor package.\nuse “BiocGenerics” example scenario.\n\npressing ‘Create repository’ button, ignore \ninstructions GitHub provides, follow rest \ndocument.Create new GitHub repo account, name\nexisting Bioconductor package.use “BiocGenerics” example scenario.pressing ‘Create repository’ button, ignore \ninstructions GitHub provides, follow rest \ndocument.local machine, clone empty repository GitHub.\nUse https URL (replace GitHub username)\ngit clone https://github.com//BiocGenerics.git\nSSH URL\ngit clone git@github.com:/BiocGenerics.gitOn local machine, clone empty repository GitHub.Use https URL (replace GitHub username)SSH URLAdd remote cloned repository.\nChange current working directory local repository\ncloned previous step.\ncd BiocGenerics\ngit remote add upstream git@git.bioconductor.org:packages/BiocGenerics.gitAdd remote cloned repository.Change current working directory local repository\ncloned previous step.Fetch content remote upstream,\ngit fetch upstreamFetch content remote upstream,Merge upstream origin’s devel branch,\ngit merge upstream/devel\nNOTE: error fatal: refusing merge unrelated histories, repository cloned step 4 \nempty. Either clone empty repository, see\nSync existing repositories.Merge upstream origin’s devel branch,NOTE: error fatal: refusing merge unrelated histories, repository cloned step 4 \nempty. Either clone empty repository, see\nSync existing repositories.Push changes origin devel,\n git push origin devel\nNOTE: Run command git config --global push.default matching always push local branches remote branch \nname, allowing use git push origin rather git push origin devel.Push changes origin devel,NOTE: Run command git config --global push.default matching always push local branches remote branch \nname, allowing use git push origin rather git push origin devel.(Optional) Add branch GitHub,\n## Fetch updates\ngit fetch upstream\n\n## Checkout new branch RELEASE_3_6, upstream/RELEASE_3_6\ngit checkout -b RELEASE_3_6 upstream/RELEASE_3_6\n\n## Push updates remote origin's new branch RELEASE_3_6\ngit push -u origin RELEASE_3_6(Optional) Add branch GitHub,Check GitHub repository confirm devel (\noptionally RELEASE_3_6) branches present.Check GitHub repository confirm devel (\noptionally RELEASE_3_6) branches present.GitHub repository established follow\nPush GitHub Bioconductor maintain repository\nGitHub Bioconductor.GitHub repository established follow\nPush GitHub Bioconductor maintain repository\nGitHub Bioconductor.","code":"git clone https://github.com//BiocGenerics.gitgit clone git@github.com:/BiocGenerics.gitcd BiocGenerics\ngit remote add upstream git@git.bioconductor.org:packages/BiocGenerics.gitgit fetch upstreamgit merge upstream/devel git push origin devel## Fetch all updates\ngit fetch upstream\n\n## Checkout new branch RELEASE_3_6, from upstream/RELEASE_3_6\ngit checkout -b RELEASE_3_6 upstream/RELEASE_3_6\n\n## Push updates to remote origin's new branch RELEASE_3_6\ngit push -u origin RELEASE_3_6"},{"path":"git-version-control.html","id":"maintain-bioc-only","chapter":"21 Git Version Control","heading":"21.5.3 Maintain a Bioconductor-only repository for an existing package","text":"Goal: Developer wishes maintain Bioconductor repository\nwithout using GitHub.","code":""},{"path":"git-version-control.html","id":"clone-and-setup-the-package-on-your-local-machine.","chapter":"21 Git Version Control","heading":"21.5.3.1 Clone and setup the package on your local machine.","text":"Make sure SSH access Bioconductor\nrepository; sure submit SSH public key \ngithub id Bioconductor.Make sure SSH access Bioconductor\nrepository; sure submit SSH public key \ngithub id Bioconductor.Clone package local machine,\n git clone git@git.bioconductor.org:packages/\nNOTE: clone https get read+write\naccess.Clone package local machine,NOTE: clone https get read+write\naccess.View existing remotes\n git remote -v\ndisplay\n origin git@git.bioconductor.org:packages/.git (fetch)\n origin git@git.bioconductor.org:packages/.git (push)\nindicates git repository one remote\norigin, Bioconductor repository.View existing remoteswhich displayThis indicates git repository one remote\norigin, Bioconductor repository.work flows, origin remote renamed \nupstream. may convenient make change \nrepository\n git remote rename origin upstream\nconfirm git remote -v now associates upstream\nrepository name git@git.bioconductor.org.work flows, origin remote renamed \nupstream. may convenient make change \nrepositoryand confirm git remote -v now associates upstream\nrepository name git@git.bioconductor.org.","code":" git clone git@git.bioconductor.org:packages/ git remote -v origin git@git.bioconductor.org:packages/.git (fetch)\n origin git@git.bioconductor.org:packages/.git (push) git remote rename origin upstream"},{"path":"git-version-control.html","id":"commit-changes-to-your-local-repository","chapter":"21 Git Version Control","heading":"21.5.3.2 Commit changes to your local repository","text":"making changes repository, make sure pull\nchanges updates Bioconductor repository. \nneeded avoid conflicts.\n git pullBefore making changes repository, make sure pull\nchanges updates Bioconductor repository. \nneeded avoid conflicts.Make required changes, add commit changes \ndevel branch.\n git add \n git commit -m \"informative commit message\"Make required changes, add commit changes \ndevel branch.(Alternative) changes non-trivial, create new branch\ncan easily abandon false starts. Merge final\nversion onto devel\n git checkout -b feature--feature\n ## add commit branch. change complete...\n git checkout devel\n git merge feature--feature(Alternative) changes non-trivial, create new branch\ncan easily abandon false starts. Merge final\nversion onto devel","code":" git pull git add \n git commit -m \"My informative commit message\" git checkout -b feature-my-feature\n ## add and commit to this branch. When the change is complete...\n git checkout devel\n git merge feature-my-feature"},{"path":"git-version-control.html","id":"push-your-local-commits-to-the-bioconductor-repository","chapter":"21 Git Version Control","heading":"21.5.3.3 Push your local commits to the Bioconductor repository","text":"Push commits Bioconductor repository make \navailable user community.\nPush changes devel branch using:\n git checkout devel\n git push upstream develPush commits Bioconductor repository make \navailable user community.Push changes devel branch using:Make sure valid version bump changes propagate users.","code":" git checkout devel\n git push upstream devel"},{"path":"git-version-control.html","id":"optional-merge-changes-to-the-current-release-branch","chapter":"21 Git Version Control","heading":"21.5.3.4 (Optional) Merge changes to the current release branch","text":"Merging devel release branch avoided. Select bug fixes \ncherry-picked devel release. See section Bug Fixes Release Devel","code":""},{"path":"git-version-control.html","id":"more-scenarios-for-repository-creation","chapter":"21 Git Version Control","heading":"21.6 More scenarios for repository creation","text":"Sync existing GitHub repository Bioconductor.Create local repository private use.","code":""},{"path":"git-version-control.html","id":"sync-existing-repositories","chapter":"21 Git Version Control","heading":"21.6.1 Sync an existing GitHub repository with Bioconductor","text":"Goal: Ensure local, Bioconductor, GitHub\nrepositories sync.Clone GitHub repository local machine. Change \ndirectory containing repository.Clone GitHub repository local machine. Change \ndirectory containing repository.Configure “remotes” GitHub clone.\n git remote add upstream git@git.bioconductor.org:packages/<-REPOSITORY>.gitConfigure “remotes” GitHub clone.Fetch updates (Bioconductor GitHub) remotes. may\nsee “warning: common commits”; addressed \nresolving conflicts, .\n git fetch --allFetch updates (Bioconductor GitHub) remotes. may\nsee “warning: common commits”; addressed \nresolving conflicts, .Make sure devel branch.\n git checkout develMake sure devel branch.Merge updates GitHub (origin) remote\n git merge origin/develMerge updates GitHub (origin) remoteMerge updates Bioconductor (upstream) remote\n git merge upstream/devel\nUsers git version >= 2.9 see error message (“fatal:\nrefusing merge unrelated histories”) need use\n git merge --allow-unrelated-histories upstream/develMerge updates Bioconductor (upstream) remoteUsers git version >= 2.9 see error message (“fatal:\nrefusing merge unrelated histories”) need useResolve merge conflicts necessary.Resolve merge conflicts necessary.resolving conflicts committing changes, look duplicate\ncommits (e.g., git log --oneline | wc returns twice many\ncommits SVN) consider following steps \nforce Bioconductor devel GitHub devel.resolving conflicts committing changes, look duplicate\ncommits (e.g., git log --oneline | wc returns twice many\ncommits SVN) consider following steps \nforce Bioconductor devel GitHub devel.Push Bioconductor GitHub repositories.\n git push upstream devel\n git push origin develPush Bioconductor GitHub repositories.Repeat release branch, replacing devel name \nrelease branch, e.g., RELEASE_3_6. may necessary \ncreate release branch local repository.\n git checkout RELEASE_3_6\n git merge upstream/RELEASE_3_6\n git merge origin/RELEASE_3_6\n git push upstream RELEASE_3_6\n git push origin RELEASE_3_6\nNOTE: syncing release branch first time,\nmake local copy RELEASE_X_Y branch, \n git checkout -b upstream/\nFollowing one time local checkout, may switch \nRELEASE_X_Y devel git checkout . \nuse command get local copy release branch, \nget message,\n(HEAD detached origin/RELEASE_X_Y)\nRemember devel current release branch \nBioconductor repositories can updated.Repeat release branch, replacing devel name \nrelease branch, e.g., RELEASE_3_6. may necessary \ncreate release branch local repository.NOTE: syncing release branch first time,\nmake local copy RELEASE_X_Y branch, byFollowing one time local checkout, may switch \nRELEASE_X_Y devel git checkout . \nuse command get local copy release branch, \nget message,Remember devel current release branch \nBioconductor repositories can updated.","code":" git remote add upstream git@git.bioconductor.org:packages/.git git fetch --all git checkout devel git merge origin/devel git merge upstream/devel git merge --allow-unrelated-histories upstream/devel git push upstream devel\n git push origin devel git checkout RELEASE_3_6\n git merge upstream/RELEASE_3_6\n git merge origin/RELEASE_3_6\n git push upstream RELEASE_3_6\n git push origin RELEASE_3_6 git checkout -b upstream/(HEAD detached from origin/RELEASE_X_Y)"},{"path":"git-version-control.html","id":"create-local-repository","chapter":"21 Git Version Control","heading":"21.6.2 Create a local repository for private use","text":"Goal: user (package developer) like modify\nfunctions package meet needs. GitHub\nrepository package.Clone package Bioconductor repository. end\nuser, write access repository, use \nhttps protocol\n git clone https://git@git.bioconductor.org/packages/Clone package Bioconductor repository. end\nuser, write access repository, use \nhttps protocolMake changes local repository. Commit changes \nlocal repository. best practice might modify changes new\nbranch\n git checkout -b feature--feature\n ## modify\n git commit --m \"feature: new feature\"\nmerge feature onto branch corresponding \nrelease use, e.g.,\n git checkout \n git merge feature--featureMake changes local repository. Commit changes \nlocal repository. best practice might modify changes new\nbranchand merge feature onto branch corresponding \nrelease use, e.g.,Rebuild (create vignette help pages) reinstall \npackage local machine running parent directory \nExamplePackage\n R CMD build ExamplePackage\n R CMD INSTALL ExamplePackage_.tar.gzRebuild (create vignette help pages) reinstall \npackage local machine running parent directory \nExamplePackageThe package changes available local R\ninstallation.package changes available local R\ninstallation.","code":" git clone https://git@git.bioconductor.org/packages/ git checkout -b feature-my-feature\n ## modify\n git commit -a -m \"feature: a new feature\" git checkout \n git merge feature-my-feature R CMD build ExamplePackage\n R CMD INSTALL ExamplePackage_.tar.gz"},{"path":"git-version-control.html","id":"scenarios-for-code-update","chapter":"21 Git Version Control","heading":"21.7 Scenarios for code update:","text":"Pull upstream changes, e.g., introduced core team.Push GitHub Bioconductor repositories.Resolve merge conflicts.Abandon changes.Fix bugs devel release.Resolve duplicate commits","code":""},{"path":"git-version-control.html","id":"pull-upstream-changes","chapter":"21 Git Version Control","heading":"21.7.1 Pull upstream changes","text":"Goal: Bioconductor repository updated core\nteam. want fetch commits Bioconductor, merge \nlocal repository, push GitHub.NOTE: always good idea fetch updates \nBioconductor making changes. help prevent\nmerge conflicts.steps update devel branch.Make sure appropriate branch.\n git checkout develMake sure appropriate branch.Fetch content Bioconductor\n git fetch upstreamFetch content BioconductorMerge upstream appropriate local branch\n git merge upstream/devel\nGet help Resolve merge conflicts occur.Merge upstream appropriate local branchGet help Resolve merge conflicts occur.also maintain GitHub repository, push changes GitHub’s\n(origin) devel branch\n git push origin develIf also maintain GitHub repository, push changes GitHub’s\n(origin) devel branchTo pull updates current RELEASE_X_Y branch, replace devel\nRELEASE_X_Y lines .See instructions Sync existing repositories \nchanges Bioconductor GitHub repositories.","code":" git checkout devel git fetch upstream git merge upstream/devel git push origin devel"},{"path":"git-version-control.html","id":"push-to-github-bioc","chapter":"21 Git Version Control","heading":"21.7.2 Push to GitHub and Bioconductor repositories","text":"Goal: everyday development, commit changes \nlocal repository devel branch, wish push commits \nGitHub Bioconductor repositories.NOTE: See Pull upstream changes best practices \ncommitting local changes.assume already GitHub repository right setup\npush Bioconductor’s git server\n(git@git.bioconductor.org). please see FAQ’s get\naccess follow instructions \nMaintain GitHub Bioconductor repositories. use clone\nBiocGenerics package following example.assume already GitHub repository right setup\npush Bioconductor’s git server\n(git@git.bioconductor.org). please see FAQ’s get\naccess follow instructions \nMaintain GitHub Bioconductor repositories. use clone\nBiocGenerics package following example.check remotes set properly, run command inside\nlocal machine’s clone.\ngit remote -v\nproduce result ( GitHub\nusername):\norigin git@github.com:/BiocGenerics.git (fetch)\norigin git@github.com:/BiocGenerics.git (push)\nupstream git@git.bioconductor.org:packages/BiocGenerics.git (fetch)\nupstream git@git.bioconductor.org:packages/BiocGenerics.git (push)check remotes set properly, run command inside\nlocal machine’s clone.produce result ( GitHub\nusername):Make commit changes devel branch\n git checkout devel\n ## edit files, etc.\n git add \n git commit -m \"informative commit message describing change\"Make commit changes devel branch(Alternative) changes elaborate, best practice \nuse local branch development.\n git checkout devel\n git checkout -b feature--feature\n ## multiple rounds edit, add, commit\nMerge local branch devel feature ‘complete’.\n git checkout devel\n\n # Pull upstream changes merging\n # http://bioconductor.org/developers/-/git/pull-upstream-changes/\n\n git merge feature--feature(Alternative) changes elaborate, best practice \nuse local branch development.Merge local branch devel feature ‘complete’.Push updates GitHub’s (origin) devel branch\n git push origin develPush updates GitHub’s (origin) devel branchNext, push updates Bioconductor’s (upstream) devel branch\ngit push upstream develNext, push updates Bioconductor’s (upstream) devel branchConfirm changes, e.g., visiting GitHub web page repository.Confirm changes, e.g., visiting GitHub web page repository.","code":"git remote -vorigin git@github.com:/BiocGenerics.git (fetch)\norigin git@github.com:/BiocGenerics.git (push)\nupstream git@git.bioconductor.org:packages/BiocGenerics.git (fetch)\nupstream git@git.bioconductor.org:packages/BiocGenerics.git (push) git checkout devel\n ## edit files, etc.\n git add \n git commit -m \"My informative commit message describing the change\" git checkout devel\n git checkout -b feature-my-feature\n ## multiple rounds of edit, add, commit git checkout devel\n\n # Pull upstream changes before merging\n # http://bioconductor.org/developers/how-to/git/pull-upstream-changes/\n\n git merge feature-my-feature git push origin develgit push upstream devel"},{"path":"git-version-control.html","id":"resolve-merge-conflicts","chapter":"21 Git Version Control","heading":"21.7.3 Resolve merge conflicts","text":"Goal: Resolve merge conflicts branch push GitHub \nBioconductor repositories.know merge conflict see something like\n:\n git merge upstream/devel\n Auto-merging DESCRIPTION\n CONFLICT (content): Merge conflict DESCRIPTION\n Automatic merge failed; fix conflicts commit result\nmerge conflict occurs package developer makes \nchange, also collaborator Bioconductor core team\nmember makes change file (case \nDESCRIPTION file).\ncan avoid ? Pull upstream changes \ncommitting changes. words, fetch merge remote\nbranches push.know merge conflict see something like\n:merge conflict occurs package developer makes \nchange, also collaborator Bioconductor core team\nmember makes change file (case \nDESCRIPTION file).can avoid ? Pull upstream changes \ncommitting changes. words, fetch merge remote\nbranches push.spite conflicts, need fix . See\nfile conflict,\n git status\nshow something like :\n branch devel\n branch ahead 'origin/devel' 1 commit.\n (use \"git push\" publish local commits)\n un-merged paths.\n (fix conflicts run \"git commit\")\n (use \"git merge --abort\" abort merge)\n\n Un-merged paths:\n (use \"git add ...\" mark resolution)\n\n modified: DESCRIPTION\n\n changes added commit (use \"git add\" /\"git commit -\")spite conflicts, need fix . See\nfile conflict,show something like :Open file favorite editor. Conflicts look like:\n <<<<<<< HEAD\n Version: 0.23.2\n =======\n Version: 0.23.3\n >>>>>>> upstream/devel\nEverything <<<< ===== refers HEAD, .e \ncurrent change. everything ===== >>>>> refers\nremote/branch shown , .e upstream/devel.\nwant keep accurate change, deleting \nnecessary. case, keep latest version:\n Version: 0.23.3Open file favorite editor. Conflicts look like:Everything <<<< ===== refers HEAD, .e \ncurrent change. everything ===== >>>>> refers\nremote/branch shown , .e upstream/devel.want keep accurate change, deleting \nnecessary. case, keep latest version:Add commit file change.\n git add DESCRIPTION\n git commit -m \"Fixed conflicts version change\"Add commit file change.Push GitHub Bioconductor repositories,\ngit push origin devel\ngit push upstream develPush GitHub Bioconductor repositories,","code":" git merge upstream/devel\n Auto-merging DESCRIPTION\n CONFLICT (content): Merge conflict in DESCRIPTION\n Automatic merge failed; fix conflicts and then commit the result git status On branch devel\n Your branch is ahead of 'origin/devel' by 1 commit.\n (use \"git push\" to publish your local commits)\n You have un-merged paths.\n (fix conflicts and run \"git commit\")\n (use \"git merge --abort\" to abort the merge)\n\n Un-merged paths:\n (use \"git add ...\" to mark resolution)\n\n both modified: DESCRIPTION\n\n no changes added to commit (use \"git add\" and/or \"git commit -a\") <<<<<<< HEAD\n Version: 0.23.2\n =======\n Version: 0.23.3\n >>>>>>> upstream/devel Version: 0.23.3 git add DESCRIPTION\n git commit -m \"Fixed conflicts in version change\"git push origin devel\ngit push upstream devel"},{"path":"git-version-control.html","id":"extra-resources","chapter":"21 Git Version Control","heading":"21.7.3.1 Extra Resources","text":"Resolving merge conflict using command lineBased : Resolving merge conflict","code":""},{"path":"git-version-control.html","id":"abandon-changes","chapter":"21 Git Version Control","heading":"21.7.4 Abandon changes","text":"Goal: want start fresh failing resolve conflicts\nissue. intend go nuclear, please contact \nbioc-devel@bioconductor.org mailing list.","code":""},{"path":"git-version-control.html","id":"force-bioconductor-devel-to-github-devel","chapter":"21 Git Version Control","heading":"21.7.4.1 Force Bioconductor devel to GitHub devel","text":"One way can ignore work make new branch replacing\nlocal GitHub repository devel branch \nBioconductor devel branch.Note: works haven’t pushed change causing \nissue Bioconductor repository.Note: references commits current devel (e.g., GitHub\nissues) invalidated.Checkout new branch, e.g., devel_backup, tracking set \ntrack Bioconductor devel branch upstream/devel.\n git checkout -b devel_backup upstream/develCheckout new branch, e.g., devel_backup, tracking set \ntrack Bioconductor devel branch upstream/devel.Rename branches currently local\nmachine. First, rename devel devel_deprecated. Second,\nrename devel_backup devel. process called \nclassic Switcheroo.\n git branch -m devel devel_deprecated\n git branch -m devel_backup develRename branches currently local\nmachine. First, rename devel devel_deprecated. Second,\nrename devel_backup devel. process called \nclassic Switcheroo.now “force push” changes GitHub\n(origin) devel branch.\n git push -f origin develYou now “force push” changes GitHub\n(origin) devel branch.(Optional) commits devel_deprecated\nbranch like ported new devel\nbranch. Git special feature called cherry-pick\nTake look commit want cherry-pick new\ndevel branch, using git log devel_deprecated, copy correct\ncommit id, use:\n git cherry-pick \nPush cherry-picked changes GitHub Bioconductor\nrepositories.(Optional) commits devel_deprecated\nbranch like ported new devel\nbranch. Git special feature called cherry-pickTake look commit want cherry-pick new\ndevel branch, using git log devel_deprecated, copy correct\ncommit id, use:Push cherry-picked changes GitHub Bioconductor\nrepositories.","code":" git checkout -b devel_backup upstream/devel git branch -m devel devel_deprecated\n git branch -m devel_backup devel git push -f origin devel git cherry-pick "},{"path":"git-version-control.html","id":"reset-to-a-previous-commit","chapter":"21 Git Version Control","heading":"21.7.4.2 Reset to a previous commit","text":"find place want abandon changes\nalready committed Bioconductor GitHub, use reset undo\ncommits local repository push -f force \nchanges remotes. Remember HEAD commit id \nrecent parent commit current state local\nrepository.Example:make changes permanent, need push changes\nGitHub, email Bioconductor core team force push \nrepository Bioconductor.Bioconductor core team rest email.","code":"git reset --hard git reset --hard e02e4d86812457fd9fdd43adae5761f5946fdfb3\nHEAD is now at e02e4d8 version bump by bioc core## You\n\ngit push -f origin"},{"path":"git-version-control.html","id":"delete-your-local-copy-and-github-repo-because-nothing-is-working","chapter":"21 Git Version Control","heading":"21.7.4.3 Delete your local copy and GitHub repo, because nothing is working","text":"CAUTION: instructions come many disadvantages. \nwarned.Delete local repository, e.g., rm -rf BiocGenericsDelete local repository, e.g., rm -rf BiocGenericsDelete (rename) GitHub repository.Delete (rename) GitHub repository.Maintain GitHub Bioconductor repositories existing\nBioconductor repository, Pull upstream changes.Maintain GitHub Bioconductor repositories existing\nBioconductor repository, Pull upstream changes.","code":""},{"path":"git-version-control.html","id":"disadvantages-of-going-nuclear","chapter":"21 Git Version Control","heading":"21.7.4.3.1 Disadvantages of going “nuclear”","text":"lose GitHub issuesYou lose GitHub issuesYou lose custom collaborator settings GitHub.lose custom collaborator settings GitHub.lose GitHub-specific changes.lose GitHub-specific changes.","code":""},{"path":"git-version-control.html","id":"bug-fix-in-release-and-devel","chapter":"21 Git Version Control","heading":"21.7.5 Fix bugs in devel and release","text":"Goal: bug present release devel branches \nBioconductor, maintainer introduce patch default\ngit branch current release branch (e.g., RELEASE_3_14).First Sync existing repositories.\n git fetch --\n git checkout devel\n git merge upstream/devel\n git merge origin/devel\n git checkout \n git merge upstream/\n git merge origin/First Sync existing repositories.local machine, sure devel branch.\n git checkout devel\nMake changes needed fix bug add modified files\ncommit. Remember bump version number DESCRIPTION file\nseparate commit. bug-fix changes introduced \ncommit.\n git add \nCommit modified files. helpful tag commit message “bug\nfix”.\n git commit -m \"bug fix: bug fix\"\nBump version package editing Version field \nDESCRIPTION commit change separate commit. allows \ncherry-pick bug correction avoid version number conflicts \nBioconductor branches /bug fixes ported release.\n ## version bump\n git add DESCRIPTION\n git commit -m \"version bump devel\"local machine, sure devel branch.Make changes needed fix bug add modified files\ncommit. Remember bump version number DESCRIPTION file\nseparate commit. bug-fix changes introduced \ncommit.Commit modified files. helpful tag commit message “bug\nfix”.Bump version package editing Version field \nDESCRIPTION commit change separate commit. allows \ncherry-pick bug correction avoid version number conflicts \nBioconductor branches /bug fixes ported release.(Alternative) changes non-trivial .e., multiple commits,\ncreate new branch can easily abandon false starts.\n git checkout devel\n git checkout -b bugfix--bug\n ## add commit branch fix bug\nMerge final version branch default branch.\n git checkout devel\n git merge bugfix--bug(Alternative) changes non-trivial .e., multiple commits,\ncreate new branch can easily abandon false starts.Merge final version branch default branch.Switch release branch cherry-pick commit hash range \nhashes default branch correspond bug fix (examples\ngit cherry-pick --help). Remember edit DESCRIPTION file \nupdate release version package according Bioconductor’s\nversion numbering scheme.\n git checkout \n ## example hash git log: 2644710\n git cherry-pick \n ## Bump version commit change\n git add DESCRIPTION\n git commit -m \"version bump release\"\nNOTE: patching release first time, \nmake local copy RELEASE_X_Y branch \n git checkout -b upstream/\nFollowing one time local checkout, may switch RELEASE_X_Y\ndevel git checkout . use command\nget local checkout release branch, get message:\n (HEAD detached origin/RELEASE_X_Y)Switch release branch cherry-pick commit hash range \nhashes default branch correspond bug fix (examples\ngit cherry-pick --help). Remember edit DESCRIPTION file \nupdate release version package according Bioconductor’s\nversion numbering scheme.NOTE: patching release first time, \nmake local copy RELEASE_X_Y branch withFollowing one time local checkout, may switch RELEASE_X_Y\ndevel git checkout . use command\nget local checkout release branch, get message:Push changes GitHub Bioconductor devel\n branches. Make sure correct\nbranch local machine.\ndevel branch,\n git checkout devel\n git push upstream devel\n git push origin devel\nrelease branch,\n git checkout \n git push upstream \n git push origin Push changes GitHub Bioconductor devel\n branches. Make sure correct\nbranch local machine.devel branch,release branch,See video tutorial :","code":" git fetch --all\n git checkout devel\n git merge upstream/devel\n git merge origin/devel\n git checkout \n git merge upstream/\n git merge origin/ git checkout devel git add git commit -m \"bug fix: my bug fix\" ## after version bump\n git add DESCRIPTION\n git commit -m \"version bump in devel\" git checkout devel\n git checkout -b bugfix-my-bug\n ## add and commit to this branch to fix the bug git checkout devel\n git merge bugfix-my-bug git checkout \n ## example hash from git log: 2644710\n git cherry-pick \n ## Bump the version and commit the change\n git add DESCRIPTION\n git commit -m \"version bump in release\" git checkout -b upstream/ (HEAD detached from origin/RELEASE_X_Y) git checkout devel\n git push upstream devel\n git push origin devel git checkout \n git push upstream \n git push origin "},{"path":"git-version-control.html","id":"resolve-duplicate-commits","chapter":"21 Git Version Control","heading":"21.7.6 Resolve Duplicate Commits","text":"Goal: want get rid duplicate (triplicate) commits\ngit commit history.begin Update package existing version \nBioconductor.","code":""},{"path":"git-version-control.html","id":"steps","chapter":"21 Git Version Control","heading":"21.7.6.1 Steps:","text":"IMPORTANT Make backup branch duplicate commits,\ncall devel_backup (RELEASE_3_7_backup). name \nback branch identifiable specific \nbranch trying fix (.e want fix devel\nbranch branch).\ndevel, (make sure devel git checkout devel)\n git branch devel_backupIMPORTANT Make backup branch duplicate commits,\ncall devel_backup (RELEASE_3_7_backup). name \nback branch identifiable specific \nbranch trying fix (.e want fix devel\nbranch branch).devel, (make sure devel git checkout devel)Identify commit duplicates \noriginated. commits often , merge commits.Identify commit duplicates \noriginated. commits often , merge commits.Reset branch commit merge commit.\n git reset —hard Reset branch commit merge commit.Now cherry pick commits devel_backup branch.\n git cherry-pick \ncommits cherry-pick 1 version \nduplicate commit, .e don’t cherry-pick commit twice.\nInclude branching version bump commits \ncherry-pick. Make package history look normal possible.\nNow cherry pick commits devel_backup branch.commits cherry-pick 1 version \nduplicate commit, .e don’t cherry-pick commit twice.commits cherry-pick 1 version \nduplicate commit, .e don’t cherry-pick commit twice.Include branching version bump commits \ncherry-pick. Make package history look normal possible.Include branching version bump commits \ncherry-pick. Make package history look normal possible.(Optional) cases, conflicts need fix \ncherry-pick succeed. Please read documentation \nresolve conflicts(Optional) cases, conflicts need fix \ncherry-pick succeed. Please read documentation \nresolve conflictsFinally, need contact bioc-devel mailing list \nreach Bioconductor core team sync repository \nversion Bioconductor. possible --force pushes\nalter git timeline possible maintainers.Finally, need contact bioc-devel mailing list \nreach Bioconductor core team sync repository \nversion Bioconductor. possible --force pushes\nalter git timeline possible maintainers.","code":" git branch devel_backup git reset —hard git cherry-pick "},{"path":"git-version-control.html","id":"how-to-check-if-your-package-has-duplicate-commits","chapter":"21 Git Version Control","heading":"21.7.6.2 How to check if your package has duplicate commits","text":"One way check log. see commit message\nchanges, different commit ID, tryor","code":"git loggit log --oneline"},{"path":"git-version-control.html","id":"script-to-detect-duplicate-commits","chapter":"21 Git Version Control","heading":"21.7.6.3 Script to detect duplicate commits","text":"Run script written python detect duplicate commits\nspecific Bioconductor repositories.Usage example:","code":"python detect_duplicate_commits.py /BiocGenerics 1000\n\npython detect_duplicate_commits.py '"},{"path":"git-version-control.html","id":"github-scenarios","chapter":"21 Git Version Control","heading":"21.8 Github scenarios","text":"Add collaborators use Github social coding features.Change Package MaintainerRemove Large Data Files clean git tree","code":""},{"path":"git-version-control.html","id":"add-collaborators-and-leverage-github-features","chapter":"21 Git Version Control","heading":"21.8.1 Add collaborators and leverage GitHub features","text":"Goal: like take advantage social coding\nfeatures provided GitHub, continuing update \nBioconductor repository.","code":""},{"path":"git-version-control.html","id":"maintaining-collaborators-on-github","chapter":"21 Git Version Control","heading":"21.8.1.1 Maintaining Collaborators on GitHub","text":"Adding new collaboratorAdding new collaboratorRemoving collaboratorRemoving collaborator","code":""},{"path":"git-version-control.html","id":"pull-requests-on-github","chapter":"21 Git Version Control","heading":"21.8.1.2 Pull requests on GitHub","text":"Merging pull request","code":""},{"path":"git-version-control.html","id":"push-github-changes-to-the-bioconductor-repository","chapter":"21 Git Version Control","heading":"21.8.1.3 Push GitHub changes to the Bioconductor repository","text":"accepted pull requests package community \nGitHub, can push changes Bioconductor.Make sure branch changes \napplied, example devel.\n git checkout develMake sure branch changes \napplied, example devel.Fetch merge GitHub changes local repository.\n git fetch origin\n git merge\nResolve merge conflicts necessary.Fetch merge GitHub changes local repository.Resolve merge conflicts necessary.Push local repository upstream Bioconductor repository.\n git push upstream devel\npush GitHub release branch updates Bioconductor\nrelease branch, replace devel name release branch,\ne.g.: RELEASE_3_6.Push local repository upstream Bioconductor repository.push GitHub release branch updates Bioconductor\nrelease branch, replace devel name release branch,\ne.g.: RELEASE_3_6.","code":" git checkout devel git fetch origin\n git merge git push upstream devel"},{"path":"git-version-control.html","id":"change-maintainer","chapter":"21 Git Version Control","heading":"21.8.2 Add or Transfer Maintainership of a Package","text":"Goal: Perhaps point time can longer maintain \npackage accordance Bioconductor package guidelines. may \nnecessary add transfer maintainer-ship package order properly\nmaintain package avoid deprecation removal.Find new maintainer\nmay collaborator colleague volunteer take . , ask\nbioc-devel mailing list.Find new maintainerYou may collaborator colleague volunteer take . , ask\nbioc-devel mailing list.Email maintainer@bioconductor.org bioc-devel@r-project.org\noriginal maintainer email request maintainer \npackage updated. Include package name contact information \nnew maintainer.Email maintainer@bioconductor.org bioc-devel@r-project.orgThe original maintainer email request maintainer \npackage updated. Include package name contact information \nnew maintainer.Update Package DESCRIPTION file\nDESCRIPTION file package updated new maintainer\ninformation pushed Bioconductor git.bioconductor.org repository.Update Package DESCRIPTION fileThe DESCRIPTION file package updated new maintainer\ninformation pushed Bioconductor git.bioconductor.org repository.","code":""},{"path":"git-version-control.html","id":"remove-large-data-files-and-clean-git-tree","chapter":"21 Git Version Control","heading":"21.8.3 Remove Large Data Files and Clean Git Tree","text":"Goal: Git remembers. Sometimes large data files added git\nrepository (intentionally unintentionally) causing size repository\nbecome large. happens, ’s enough just remove files.\nalso must remove git tree (repository history), else\nrepository remain large.ways remove large files git history. , ’ll\noutline two options: 1) git filter-repo, 2) BFG repo cleaner.\nsteps run local copy (necessary) pushed \ngithub repository.","code":""},{"path":"git-version-control.html","id":"removing-large-files-from-history-with-filter-repo","chapter":"21 Git Version Control","heading":"21.8.3.1 Removing Large Files from History with filter-repo","text":"2023, recommended way first locate large files, \nremove git filter-repo.Identify large files using git rev-list script:list objects repository, including objects \nhistory, order file size. Use identify names files remove.Remove filter-repo.separate tool ’ll install\n(e.g. pip3 install git-filter-repo). , can rewrite repository\nhistory remove files like , identifies files:example, remove .RData files, use:command may reset remotes. Check git remote \nneeded, can add remotes back using something like :Finally, push --mirror reset remote.Now, just notify everyone ’ll re-clone new repository, since\nhistory rewritten, existing clones longer compatible\nrepo.","code":"git rev-list --objects --all \\\n| git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' \\\n| sed -n 's/^blob //p' \\\n| sort --numeric-sort --key=2 \\\n| cut -c 1-12,41- \\\n| $(command -v gnumfmt || echo numfmt) --field=2 --to=iec-i --suffix=B --padding=7 --round=nearestgit filter-repo --path-glob '' --invert-pathsgit filter-repo --path-glob '*.RData' --invert-pathsgit remote add origin git@github.com:/\ngit push --set-upstream origin devel --forcegit push --force --mirror"},{"path":"git-version-control.html","id":"removing-large-files-from-history-with-bfg-repo-cleaner","chapter":"21 Git Version Control","heading":"21.8.3.2 Removing Large Files from History with BFG repo cleaner","text":"Another option use BFG. steps assume origin user-maintained github\nrepository.NOTE: Anyone maintaining package repository (local copy)\nrun steps 1-3.Download BFG Repo-CleanerDownload BFG Repo-CleanerRun BFG Repo-Cleaner package directory\nlocation package, run following command\njava -jar /bfg-1.13.0.jar --strip-blobs-bigger-100M <\npackage>\nNote: command remove file 100Mb \nlarger. Adjust argument based size files cleaning \n. lower offending file size.Run BFG Repo-Cleaner package directoryIn location package, run following commandNote: command remove file 100Mb \nlarger. Adjust argument based size files cleaning \n. lower offending file size.Run clean \ncd \ngit reflog expire --expire=now --&& git gc --prune=now --aggressiveRun clean upPush Changes\ngit push -f originPush ChangesRequest updates git.bioconductor.org repository location.\nBioconductor git server allow -f force push \ngit.bioconductor.org location. Please email bioc-devel@r-project.org\nexplaining package cleaned large data files needs \nreset.Request updates git.bioconductor.org repository location.Bioconductor git server allow -f force push \ngit.bioconductor.org location. Please email bioc-devel@r-project.org\nexplaining package cleaned large data files needs \nreset.","code":"java -jar /bfg-1.13.0.jar --strip-blobs-bigger-than 100M cd \ngit reflog expire --expire=now --all && git gc --prune=now --aggressivegit push -f origin"},{"path":"git-version-control.html","id":"faq","chapter":"21 Git Version Control","heading":"21.9 Frequently Asked Question (FAQs)","text":"can’t access package.\nneed log BiocCredentials application. \nlogged , must first activate account.\ntwo steps,\nSSH key registered, must add one.\nalready SSH key registered, check packages \naccess ‘Profile’ interface.\ncan alternatively check access package\nusing command line\n ssh -T git@git.bioconductor.org\naccess package, git pull push,\nplease check FAQ #13, #14, #15.can’t access package.need log BiocCredentials application. \nlogged , must first activate account.two steps,SSH key registered, must add one.SSH key registered, must add one.already SSH key registered, check packages \naccess ‘Profile’ interface.already SSH key registered, check packages \naccess ‘Profile’ interface.can alternatively check access package\nusing command lineIf access package, git pull push,\nplease check FAQ #13, #14, #15.’m developer Bioconductor, package ExamplePackage \nnew server https://git.bioconductor.org. next?\nTake look Maintain GitHub Bioconductor repositories.\ngive information needed.\nNOTE: situation packages previously\nmaintained SVN never accessed GIT. \nnewly accepted packages Github.’m developer Bioconductor, package ExamplePackage \nnew server https://git.bioconductor.org. next?Take look Maintain GitHub Bioconductor repositories.\ngive information needed.NOTE: situation packages previously\nmaintained SVN never accessed GIT. \nnewly accepted packages Github.GitHub repository already set Bioconductor\npackage www.github.com// , \nlink repository GitHub https://git.bioconductor.org ?\nTake look New package workflow. Step 2 gives \ninformation add remote link GitHub \nBioconductor repositories.GitHub repository already set Bioconductor\npackage www.github.com// , \nlink repository GitHub https://git.bioconductor.org ?Take look New package workflow. Step 2 gives \ninformation add remote link GitHub \nBioconductor repositories.’m unable push merge updates GitHub\nrepository Bioconductor package \ngit@git.bioconductor.org, go ?\nunable push merge either GitHub\naccount Bioconductor repository, means \ncorrect access rights. developer Bioconductor,\nneed submit SSH public key \nBiocCredentials app.\nalso make sure check public key set \ncorrectly GitHub. Follow\nAdding new SSH key GitHub account.’m unable push merge updates GitHub\nrepository Bioconductor package \ngit@git.bioconductor.org, go ?unable push merge either GitHub\naccount Bioconductor repository, means \ncorrect access rights. developer Bioconductor,\nneed submit SSH public key \nBiocCredentials app.also make sure check public key set \ncorrectly GitHub. Follow\nAdding new SSH key GitHub account.’m sure fetch updates git.bioconductor.org\nregards package, ?\nTake look Sync existing repositories. give \ninformation needed.’m sure fetch updates git.bioconductor.org\nregards package, ?Take look Sync existing repositories. give \ninformation needed.’m just package user, need ?\npackage user, need developer\nrelated documentation. Although, good primer want\ncontributor Bioconductor.\ncan also open Pull requests issues \nBioconductor packages use, GitHub\nrepository.’m just package user, need ?package user, need developer\nrelated documentation. Although, good primer want\ncontributor Bioconductor.can also open Pull requests issues \nBioconductor packages use, GitHub\nrepository.’m new git GitHub, learn?\nmany resources can learn git GitHub.\ngit--github-learning-resources\ngit-scm\nGuides\n’m new git GitHub, learn?many resources can learn git GitHub.git--github-learning-resourcesgit-scmGuidesI’m Bioconductor package maintainer, don’t access \nBioconductor server packages maintained. \ngain access?\nPlease submit SSH public key using BiocCredentials\napp. key added server get\nread+ write access package.\ndevelopers Bioconductor packages required ,\ndon’t already access. Please identify packages\nneed read/write access email.’m Bioconductor package maintainer, don’t access \nBioconductor server packages maintained. \ngain access?Please submit SSH public key using BiocCredentials\napp. key added server get\nread+ write access package.developers Bioconductor packages required ,\ndon’t already access. Please identify packages\nneed read/write access email.relationship origin upstream remote?\ngit lingo origin just default name remote\nrepository originally cloned. might equally\ncalled another name. recommend origin \nset developers GitHub repository.\nSimilarly, upstream name remote hosted\nBioconductor server.\nimportant changes/updates \norigin equal upstream, words, want\ntwo remotes sync.\nFollow Sync existing repositories details \nachieve .\nImage explaining GitHub Bioconductor relationship \ndeveloper\nrelationship origin upstream remote?git lingo origin just default name remote\nrepository originally cloned. might equally\ncalled another name. recommend origin \nset developers GitHub repository.Similarly, upstream name remote hosted\nBioconductor server.important changes/updates \norigin equal upstream, words, want\ntwo remotes sync.Follow Sync existing repositories details \nachieve .Image explaining GitHub Bioconductor relationship \ndeveloperCan one upstream remote, yes, recommended?\ncan many remotes please. can \none remote name upstream. recommend \nremote origin set GitHub, upstream set \nBioconductor git server avoid confusion.Can one upstream remote, yes, recommended?can many remotes please. can \none remote name upstream. recommend \nremote origin set GitHub, upstream set \nBioconductor git server avoid confusion.Common names used scenario’s\ndeveloper: GitHub username, e.g., mine \nnturaga.\nBiocGenerics: used example demonstrate\ngit commands.\nExamplePackage: used place holder package\nname.\nSVN trunk git devel branch now development\nbranches.Common names used scenario’sdeveloper: GitHub username, e.g., mine \nnturaga.BiocGenerics: used example demonstrate\ngit commands.ExamplePackage: used place holder package\nname.SVN trunk git devel branch now development\nbranches.’m Bioconductor developer Bioconductor server. \n/want GitHub account. ?\nget Github account want\none. really good idea, maintain package\npublicly interact community via social coding\nfeatures available Github.\nhighlight Maintain Bioconductor-repositoryI’m Bioconductor developer Bioconductor server. \n/want GitHub account. ?get Github account want\none. really good idea, maintain package\npublicly interact community via social coding\nfeatures available Github.highlight Maintain Bioconductor-repositoryI push package. get error,\n $ git push origin devel\n fatal: remote error: FATAL: W packages/myPackage nobody DENIED fallthru\n (mis-spelled reponame)\n(might renamed origin remote upstream;\nsubstitute upstream origin. Check remote,\n $ git remote -v\n origin https://git.bioconductor.org/packages/myPackage.git (fetch)\n origin https://git.bioconductor.org/packages/myPackage.git (push)\ndeveloper using SSH protocol, \norigin remote HTTPS. Use\n git remote add origin git@git.bioconductor.org:packages/myPackage\nchange remote SSH protocol. Note : \nhost name SSH protocol, rather / HTTPS\nprotocol. Confirm remote updated correctly \ngit remote -v.\nremote correct still see message, \nSSH key invalid. See next FAQ.push package. get error,(might renamed origin remote upstream;\nsubstitute upstream origin. Check remote,developer using SSH protocol, \norigin remote HTTPS. Useto change remote SSH protocol. Note : \nhost name SSH protocol, rather / HTTPS\nprotocol. Confirm remote updated correctly \ngit remote -v.remote correct still see message, \nSSH key invalid. See next FAQ.sending question Bioc-devel mailing list \ngit, please check output following commands \ncorrectness can help better.\ndeveloper check make sure, using SSH \naccess protocol. Check output git remote -v \nconsistency. Include email bioc-devel, \nunsure. remote look like,\n origin git@git.bioconductor.org:packages/myPackage.git (fetch)\n origin git@git.bioconductor.org:packages/myPackage.git (push)\n\n origin git@github.com:/myPackage.git (fetch)\n origin git@github.com:/myPackage.git (push)\n upstream git@git.bioconductor.org:packages/myPackage.git (fetch)\n upstream git@git.bioconductor.org:packages/myPackage.git (push)\nCheck access bioc-git server\n(git@git.bioconductor.org), using ssh -T git@git.bioconductor.org. show list \npackages READ(R) WRITE(W) permissions. developer\nR W next package. based \nSSH public key using, default ssh authentication\nid_rsa.\n R admin/..*\n R packages/..*\n R admin/manifest\n R packages/ABAData\n R packages/ABAEnrichment\n R packages/ABSSeq\n R W packages/ABarray\n R packages/ACME\n R packages/ADaCGH2\n R packages/AGDEX\nsending question Bioc-devel mailing list \ngit, please check output following commands \ncorrectness can help better.developer check make sure, using SSH \naccess protocol. Check output git remote -v \nconsistency. Include email bioc-devel, \nunsure. remote look like,\n origin git@git.bioconductor.org:packages/myPackage.git (fetch)\n origin git@git.bioconductor.org:packages/myPackage.git (push)\n\n origin git@github.com:/myPackage.git (fetch)\n origin git@github.com:/myPackage.git (push)\n upstream git@git.bioconductor.org:packages/myPackage.git (fetch)\n upstream git@git.bioconductor.org:packages/myPackage.git (push)developer check make sure, using SSH \naccess protocol. Check output git remote -v \nconsistency. Include email bioc-devel, \nunsure. remote look like,orCheck access bioc-git server\n(git@git.bioconductor.org), using ssh -T git@git.bioconductor.org. show list \npackages READ(R) WRITE(W) permissions. developer\nR W next package. based \nSSH public key using, default ssh authentication\nid_rsa.\n R admin/..*\n R packages/..*\n R admin/manifest\n R packages/ABAData\n R packages/ABAEnrichment\n R packages/ABSSeq\n R W packages/ABarray\n R packages/ACME\n R packages/ADaCGH2\n R packages/AGDEXCheck access bioc-git server\n(git@git.bioconductor.org), using ssh -T git@git.bioconductor.org. show list \npackages READ(R) WRITE(W) permissions. developer\nR W next package. based \nSSH public key using, default ssh authentication\nid_rsa.SSH key recognized different name?\nnamed SSH public key differently id_rsa \nsuggested ssh-keygen, may find useful set \n~/.ssh/config file machine. Simply make \n~/.ssh/config file exist, add,\n host git.bioconductor.org\n HostName git.bioconductor.org\n IdentityFile ~/.ssh/id_rsa_bioconductor\n User git\nexample, private key called id_rsa_bioconductor\ninstead id_rsa.\nmay find useful check BiocCredentials app see\nSSH key registered.SSH key recognized different name?named SSH public key differently id_rsa \nsuggested ssh-keygen, may find useful set \n~/.ssh/config file machine. Simply make \n~/.ssh/config file exist, add,example, private key called id_rsa_bioconductor\ninstead id_rsa.may find useful check BiocCredentials app see\nSSH key registered.SSH key asking password don’t know ? \nretrieve ?\npossibilities ,\nset password. bioc-devel mailing list help\n. submit new key \nBiocCredentials app.\npermissions SSH key wrong. Verify \npermissions SSH IdentityFile 400. SSH reject, \nclearly explicit manner, SSH keys readable. \njust look like credential rejection. solution, \ncase, (SSH key bioconductor called id_rsa):\n chmod 400 ~/.ssh/id_rsa\nwrong remote set , please check git remote -v\nmake sure SSH access protocol used. bioc-git\nserver remote, \ngit@git.bioconductor.org:packages/myPackage.\nSSH key asking password don’t know ? \nretrieve ?possibilities ,set password. bioc-devel mailing list help\n. submit new key \nBiocCredentials app.set password. bioc-devel mailing list help\n. submit new key \nBiocCredentials app.permissions SSH key wrong. Verify \npermissions SSH IdentityFile 400. SSH reject, \nclearly explicit manner, SSH keys readable. \njust look like credential rejection. solution, \ncase, (SSH key bioconductor called id_rsa):\n chmod 400 ~/.ssh/id_rsaThe permissions SSH key wrong. Verify \npermissions SSH IdentityFile 400. SSH reject, \nclearly explicit manner, SSH keys readable. \njust look like credential rejection. solution, \ncase, (SSH key bioconductor called id_rsa):wrong remote set , please check git remote -v\nmake sure SSH access protocol used. bioc-git\nserver remote, \ngit@git.bioconductor.org:packages/myPackage.wrong remote set , please check git remote -v\nmake sure SSH access protocol used. bioc-git\nserver remote, \ngit@git.bioconductor.org:packages/myPackage.Can create push new branches repository git.bioconductor.org?\n. Maintainers access devel current RELEASE_X_Y.\nNew branches created pushed bioconductor server. \nrecommend maintainers additional branches Github repository\nmaintaining one.Can create push new branches repository git.bioconductor.org?. Maintainers access devel current RELEASE_X_Y.\nNew branches created pushed bioconductor server. \nrecommend maintainers additional branches Github repository\nmaintaining one.can fix duplicate commits issue find required\ndocumentation?\ndetailed documentation resolve duplicate commits\ncan found link.can fix duplicate commits issue find required\ndocumentation?detailed documentation resolve duplicate commits\ncan found link.","code":" ssh -T git@git.bioconductor.org $ git push origin devel\n fatal: remote error: FATAL: W any packages/myPackage nobody DENIED by fallthru\n (or you mis-spelled the reponame) $ git remote -v\n origin https://git.bioconductor.org/packages/myPackage.git (fetch)\n origin https://git.bioconductor.org/packages/myPackage.git (push) git remote add origin git@git.bioconductor.org:packages/myPackage origin git@git.bioconductor.org:packages/myPackage.git (fetch)\n origin git@git.bioconductor.org:packages/myPackage.git (push) origin git@github.com:/myPackage.git (fetch)\n origin git@github.com:/myPackage.git (push)\n upstream git@git.bioconductor.org:packages/myPackage.git (fetch)\n upstream git@git.bioconductor.org:packages/myPackage.git (push) R admin/..*\n R packages/..*\n R admin/manifest\n R packages/ABAData\n R packages/ABAEnrichment\n R packages/ABSSeq\n R W packages/ABarray\n R packages/ACME\n R packages/ADaCGH2\n R packages/AGDEX host git.bioconductor.org\n HostName git.bioconductor.org\n IdentityFile ~/.ssh/id_rsa_bioconductor\n User git chmod 400 ~/.ssh/id_rsa"},{"path":"git-version-control.html","id":"more-questions","chapter":"21 Git Version Control","heading":"21.9.0.1 More questions?","text":"additional questions answered already,\nplease send email bioc-devel@bioconductor.org.","code":""},{"path":"git-version-control.html","id":"helpful-resources","chapter":"21 Git Version Control","heading":"21.9.1 Helpful resources:","text":"Adding new SSH key GitHub accountCreate pull request GitHubCreate issue GitHubGit GitHub learning resourcesgit-scm manualGitHub GuidesNew package workflowMaintain GitHub Bioconductor repositoriesMaintain Bioconductor-repositorySync existing repositoriesAdding SSH key GitHub accountsubmit SSH public keyresolve duplicate commitsPull requestsOpen github issues","code":""},{"path":"versionnum.html","id":"versionnum","chapter":"22 Version Numbering","heading":"22 Version Numbering","text":"Bioconductor packages version number x.y.z format.Examples good version numbers:","code":"1.2.3\n0.99.5\n2.3.0\n3.12.44"},{"path":"versionnum.html","id":"even-odd-schedule","chapter":"22 Version Numbering","heading":"22.1 Even Odd Schedule","text":"Bioconductor ‘devel’ branch new features introduced,\nrelease branches created twice per year. Given package \nversion number x.y.z,y odd number devel.y even number release.regular development new featuresAuthors increment z version package ‘devel’\nbranch 1 GIT commit, e.g., 1.1.0 1.1.1, 1.1.2,\n…, 1.1.10, 1.1.11Any bug fixes ported release branch similarly\nincremented, 1.0.1, 1.0.2, …Changes made GIT without corresponding version bump \npropagate repository visible BiocManager::install().time release, Bioconductor team arranges :Create release branch package version: x . (y+1) . (z-z)Increment devel branch package version : x . (y+2) . (z-z)special case, package version x.99.z bumped \n(x+1) . 0 . (z-z) release, (x+1) . 1 . 0 devel.\nThus authors wishing signify major change package set y\n99 devel package.","code":""},{"path":"versionnum.html","id":"new-packages","chapter":"22 Version Numbering","heading":"22.2 New packages","text":"New packages submitted Bioconductor set Version: 0.99.0 \nDESCRIPTION file. Specifying y=99 triggers bump x next release\ncase results version 1.0.0.See additional details Package Submission page.See also instructions Using Bioc Devel.","code":""},{"path":"versionnum.html","id":"example-cases","chapter":"22 Version Numbering","heading":"22.3 Example Cases","text":"Normal Case. Suppose package devel branch version\nnumber 1.1.25. new release branch now contains copy \npackage version 1.2.0. devel branch Bioconductor\ncontains package whose version number bumped \n1.3.0Normal Case. Suppose package devel branch version\nnumber 1.1.25. new release branch now contains copy \npackage version 1.2.0. devel branch Bioconductor\ncontains package whose version number bumped \n1.3.0Special Case. “0.99.2” version package copied \nBioconductor team release branch version number\n1.0.0. package version bumped 1.1.0 devel\nbranch.Special Case. “0.99.2” version package copied \nBioconductor team release branch version number\n1.0.0. package version bumped 1.1.0 devel\nbranch.Examples version bumping scheme:","code":""},{"path":"versionnum.html","id":"summary","chapter":"22 Version Numbering","heading":"22.4 Summary","text":"summary version components bumped \nkey limitations. Bumps “release time” done Bioconductor\nteam package maintainer.x\n- modified Bioconductor team\n- bumped x+1 release time y=99\ny\n- must even release odd devel\n- must <=99\n- bumped release time packages next\neven number release next odd devel\nz\n- incremented sequentially regular package development\n- limitation size z\n- bumped release time 0 packages.","code":""},{"path":"troubleshooting-build-report.html","id":"troubleshooting-build-report","chapter":"23 Troubleshooting Build Report","heading":"23 Troubleshooting Build Report","text":"","code":""},{"path":"troubleshooting-build-report.html","id":"propagate","chapter":"23 Troubleshooting Build Report","heading":"23.1 How and when does the BBS pull? When will my changes propagate?","text":"Please remember daily builder pulls, installs, builds, checks package\nper day. process starts around 2:30 PM (14:30) EST everyday\n(.e., UTC−05:00).\nChanges pushed Bioconductor 2:30 reflected following\nday’s build report posted around 11:30 EST. build report \ntime stamp top page generated. Changes \n2:30 PM EST reflect day tomorrow, therefore\npossibly taking 36-48 hours. build reports \ndevel release show\npackage version commit id reflected build.\nlanding pages packages (e.g.,\nBiobase)\nupdated package installs/build/checks without ERROR; \npropagate broken packages. account different version \nlanding page pushed Bioconductor. Please also remember \npackage ALWAYS needs valid version bump propagate users.schedule software, data experiment, annotation, books, workflows can \nfound check results page. \norder changes included report, changes committed \nBioconductor git.bioconductor.org location morning listed day\nvalid version bump.","code":""},{"path":"troubleshooting-build-report.html","id":"how-do-i-reproduce-the-build-system-error","chapter":"23 Troubleshooting Build Report","heading":"23.2 How do I reproduce the build system ERROR?","text":"order reproduce ERROR’s accurately locally, remember using \ncorrect version R Bioconductor. version R used build\nreport can found top release \ndevel build reports. using \ncorrect version R make sure packages --date \nBiocManager::valid() BiocManager::install(). additional\nenvironment variables daily builder uses R CMD check.Devel Renviron.biocRelease Renviron.biocThe Single Package build extra\ndocumentation\nset local system use optional environment\nvariables. Please note look file listed page, \nmany additional variables; Bioconductor much stringent check \nincoming packages daily builder (now). welcome use\nfile wish comprehensive check listed\nenvironment variables included minimally.Another option debug test utilize Bioconductor docker\nimage. documentation using docker images can found\n. docker image contain \nenvironment variable setting found daily builder.","code":""},{"path":"troubleshooting-build-report.html","id":"common-build-report-errors","chapter":"23 Troubleshooting Build Report","heading":"23.3 Common Build Report Errors","text":"Often common Error’s arise R develops matures Bioconductor\npackages modified advance. document provides guidance Error’s\npotential solutions.Bioconductor 3.17 R 4.3Bioconductor 3.11 R 4.0","code":""},{"path":"troubleshooting-build-report.html","id":"bioc-317","chapter":"23 Troubleshooting Build Report","heading":"23.4 Bioconductor 3.17 with R 4.3","text":"Length = coercion logical(1)","code":""},{"path":"troubleshooting-build-report.html","id":"lenCoerc","chapter":"23 Troubleshooting Build Report","heading":"23.4.1 Length = coercion to logical(1)","text":"R 4.3, warning vector used statement increased \nERROR. :now :Solution:\ncases misjudgment length argument rather \nintentional use checking value assigned. code reviewed\nsee argument assigned correctly. cases simple\nsolution might use ( ) ( ) surrounding vector.","code":" x = c(TRUE,TRUE, FALSE)\n > if (x) 1\n [1] 1\n Warning message:\n In if (x) 1 :\n the condition has length > 1 and only the first element will be used > x = c(TRUE, TRUE, FALSE)\n > if (x) 1\n Error in if (x) 1 : the condition has length > 1"},{"path":"troubleshooting-build-report.html","id":"bioc-311","chapter":"23 Troubleshooting Build Report","heading":"23.5 Bioconductor 3.11 with R 4.0","text":"R switched 3.x 4.0 generally means significant changes.S3 method registrationRemoved Settings R CMD configConditional length > 1Scalar / Vector LogicClass == vs /inherits\nMatrix now Array\nMatrix now Arraydata.frame stringsAsFactorsstats::smoothEndsgrid package changesplot generic movedPartial Argument MatchingInvalid UTF-8Dependency IssuesDeprecated Functions","code":""},{"path":"troubleshooting-build-report.html","id":"s3method","chapter":"23 Troubleshooting Build Report","heading":"23.5.1 S3 method registration","text":"Many packages currently failing undeclared S3 methods \nNAMESPACE. background information found R developers blog\npost: S3 Method\nLookupThis ERROR takes many different forms build report. \ncommon forms includeCannot coerce class data.frameCannot coerce type ‘S4’ vector type ‘double’applicable method applied object \nclass ‘X’ list, components ‘x’ ‘y’Error colMeans(x, na.rm = TRUE) : ‘x’ must numericError RG\\[1:2, \\] : incorrect number dimensionsformal argument matched multiple actual argumentsobject mode ‘function’ found‘x’ ‘y’ lengths differSolution: Register S3 method NAMESPACEA simple example effects many packages S3 plotting method.\nfollowing line added package NAMESPACE.","code":"S3method(, )S3method(plot, TCC) # example from TCC package"},{"path":"troubleshooting-build-report.html","id":"rcmdconfig","chapter":"23 Troubleshooting Build Report","heading":"23.5.2 Removed Setting in R CMD config","text":"source ERROR utilizing settings package configure script \nremoved replaced.\nsection R NEWS “R CMD config longer knows unused\nsettings F77 FCPIFCPLAGS, CXX98 similar.”\nExecuting configuration script installing package fails, \noutput contains lot messages along lines following:configure: WARNING: flags FFLAGS=“” workchecking whether ERROR: information variable ‘F77’configure: WARNING: value FFLAGS work.Solution: Replace instances “${R} CMD config F77” “${R} CMD config FC”","code":""},{"path":"troubleshooting-build-report.html","id":"condLen","chapter":"23 Troubleshooting Build Report","heading":"23.5.3 Conditional Length > 1","text":"R 4.0 conditional length greater 1 produce WARNING. \nBioconductor Daily Builder Single Package Builder increased \nERROR.Traditionally / statements accept vectors using first\nelement conditional value ignoring remaining values. now\nproduces WARNING seem dummy example documented \nConditions Length Greater OneSolution:\nBioconductor increased severity cases misjudgment \nlength argument rather intentional. code reviewed\nsee argument assigned correctly. cases might \nappropriate use ( ) ( ) surrounding vector.See also mailing list\npost","code":"> if (c(TRUE, FALSE)) {}\nNULL\nWarning message:\nIn if (c(TRUE, FALSE)) { :\n the condition has length > 1 and only the first element will be used"},{"path":"troubleshooting-build-report.html","id":"scalarvec","chapter":"23 Troubleshooting Build Report","heading":"23.5.4 Scalar / Vector Logic","text":"change R yet notified forth coming\nescalated ERROR daily builders preparation. type\nERROR occurs misuse && ||. double && ||\nimply scalar comparison rather vector comparison singular &\n| expect. See dummy example :Solution:\ncases misjudgment misunderstanding use scalar\ncomparison vector comparison. Changing double && / || singular\n& / | generally sufficient vector comparison intended vector argument use \nappropriate ( ) ( ) surrounding vector result \nappropriate scalar comparison. Note: comparison conditional\nplease see section ; ( ) ( ) likely better alternative.See also mailing list post","code":"> c(TRUE, TRUE) && TRUE\nError in c(TRUE, TRUE) && TRUE :\n 'length(x) = 2 > 1' in coercion to 'logical(1)'"},{"path":"troubleshooting-build-report.html","id":"classEq","chapter":"23 Troubleshooting Build Report","heading":"23.5.5 Class == vs is/inherits","text":"isn’t change R / Bioconductor yet, strong discussion\naffects consequences code structure. better discussion\nexplanation can found think class(.) == *, think !sum class( x ) == \"foo\" avoided. can misleading classes extend classes. \nbetter option use ( x , \"foo\") inherits(x, \"foo\").also advised Bioconductor best practicesStarting R 4.0, matrix considered extension array.change along previous section regarding conditional length results\nmany errors users something along lines (class(m) == \"matrix\"); excellent example following \nappropriate change ((m, \"matrix\")) (inherits(m, \"matrix\")) \n(.matrix(m)).Another common ERROR now occurring change something similar\nfollowing:","code":"> m = matrix()\n> class(m)\n[1] \"matrix\" \"array\"\n\n> class(m) == \"matrix\"\n[1] TRUE FALSE\n> if ( class(m) == \"matrix\"){}\nError in if (class(m) == \"matrix\") { : the condition has length > 1Error in vapply(experiments(object), class, character(1)) :\n values must be length 1,\n but FUN(X[[4]]) result is length 2"},{"path":"troubleshooting-build-report.html","id":"stringsAsFactors","chapter":"23 Troubleshooting Build Report","heading":"23.5.6 data.frame stringsAsFactors","text":"R 4.0, default data.frame argument stringsAsFactors changed \nTRUE FALSE. changes causing breakage tests \nchecks particular factor levels constructing factor levels.\nERROR’s take many different forms. simple solution change add\nstringAsFactors=TRUE data.frame call, however maintainers may want\nre-evaluate code potential restructuring ease use.","code":""},{"path":"troubleshooting-build-report.html","id":"statsSmoothEnds","chapter":"23 Troubleshooting Build Report","heading":"23.5.7 stats::smoothEnds","text":"recent change stats::smoothEnds(), now returns integer vector \ninput integer vector. Previously return number vector.Example R 3.6.3Example 4.0.0This potential cause ERROR’s class type checked.","code":"> class(smoothEnds(c(401:403)))\n[1] \"integer\"\n> class(smoothEnds(c(401:403, 555L)))\n[1] \"numeric\"> class(smoothEnds(c(401:403)))\n[1] \"integer\"\n> class(smoothEnds(c(401:403, 555L)))\n[1] \"integer\""},{"path":"troubleshooting-build-report.html","id":"grid","chapter":"23 Troubleshooting Build Report","heading":"23.5.8 Grid package changes","text":"lot specifics changed notified \nemail. Important sections email follows:","code":" I am about to commit some internal changes to 'grid' units\n (for, in some cases, 100x speed-up of unit operations).\n A number of packages have already been fixed to work with these\n changes, but, according to my testing, the following CRAN\n packages will still fail R CMD check.\n Some of those are cascades ('armada', 'countToFPKM', and 'wilson'\n from 'ComplexHeatmap' - see below - and 'fingertipscharts' from 'lemon'\n and 'xpose' is actually a 'ggforce' problem), but all of the other\n package authors have been notified and several are already working on\n fixes.\n The most serious of those is 'ComplexHeatmap' because it causes multiple\n follow-on failures, the CRAN ones above and others on BioConductor:\n Again, the main package authors have been notified and the\n 'ComplexHeatmap' author is working on an update."},{"path":"troubleshooting-build-report.html","id":"plot","chapter":"23 Troubleshooting Build Report","heading":"23.5.9 plot generic moved","text":"plot generic moved graphics base. ERROR’s seen \nchange non specific can take many forms. ERROR’s see\nareorThe explanation given:","code":"Error in getGeneric(f, TRUE, envir, package) :\n no generic function found for 'plot'Error in as.double(y) :\n cannot coerce type 'S4' to vector of type 'double'\n “The namespace controls the search strategy for variables used by\n functions in the package. If not found locally, R searches the package\n namespace first, then the imports, then the base namespace and then the\n normal search path.\" as per\n https://cran.r-project.org/doc/manuals/r-devel/R-exts.html#Package-namespaces):\n\n CRAN and Bioconductor had a few packages that \"worked\" because the right\n plot() was found in the normal search path, but now fail because it's\n calling the one in base instead."},{"path":"troubleshooting-build-report.html","id":"partMatch","chapter":"23 Troubleshooting Build Report","heading":"23.5.10 Partial Argument Matching","text":"now strict checking argument matching regards partial\nargument matching. Best described following exampleNotice generic uses breaks setMethod uses break; \nexample partial argument match longer valid.Partial argument matching envoking functions also avoided \npart best practices. example","code":"setGeneric(“mycoolfunction”, function(object, breaks)\n standardGeneric(“mycoolfunction”)\nsetMethod(“mycoolfunction”,\n signature=c(object=”GRanges”, break=”GRanges”),\n )mycoolfunction <- function( x, myargum, secondarg ) { code }\n\nmycoolfunction(x=2, myar=1:2, second=3) # BAD Coding!\n\nmycoolfunction(x=2, myargum=1:2, secondarg=3) # Good Practice!"},{"path":"troubleshooting-build-report.html","id":"invalidUTF","chapter":"23 Troubleshooting Build Report","heading":"23.5.11 Package inputenc Error: Invalid UTF-8","text":"ERROR started appear tokay2 (windows) Spring 2020. sure\nexact source ERROR (change MiKTek, Change R, ?) \nsolution simple:Please place \\usepackage[utf8]{inputenc} beginning Sweave\nvignette right \\documentclass line.","code":""},{"path":"troubleshooting-build-report.html","id":"dep311","chapter":"23 Troubleshooting Build Report","heading":"23.5.12 Dependency Issues","text":"Dependency Issues can fall sub-categories:","code":""},{"path":"troubleshooting-build-report.html","id":"cran-binaries-not-available-for-r-4.0","chapter":"23 Troubleshooting Build Report","heading":"23.5.12.1 CRAN binaries not available for R 4.0","text":"fall cycle Bioconductor uses R-devel preparation new release \nR spring. always slightly disruptive cycle regards \npackage dependencies CRAN. CRAN next 6 months leading new release R\nmake binaries Windows MacOS available. become available \nBioconductor builders automatically add binaries. binaries \ncreated yet, unavailable result package available error. Bioconductor go extra efforts find work around install\npackages; available, added.\nSolution: Please patient!","code":""},{"path":"troubleshooting-build-report.html","id":"package-have-been-removed-from-cran","chapter":"23 Troubleshooting Build Report","heading":"23.5.12.2 Package have been removed from CRAN","text":"CRAN packages occasionally removed. Unfortunately, Bioconductor \nallow package dependencies actively maintained packages CRAN Bioconductor.\npackage alter package utilize code rely \ndependency. may course try petition CRAN reinstatement reach\npackage maintainer fix submit CRAN. Good Luck!","code":""},{"path":"troubleshooting-build-report.html","id":"package-has-been-removed-from-bioconductor","chapter":"23 Troubleshooting Build Report","heading":"23.5.12.3 Package has been removed from Bioconductor","text":"try aware orphaned packages packages remain broken \nextended periods time. Package deprecation removal occurs packages\nalter utilize code packages potential\noffer take maintenance broken packages require original\nmaintainers permission. Bioconductor Package deprecation announced throughout\nrelease cycle mailing list support site try allow dependent\npackages time adjust code removal. release \nnotable maintainer requested deprecation 3.10 (therefore removed 3.11) \nSNPchip GenomeGraphs. full list deprecated packages can found\nList Deprecated Packages 3.10.\nalso documented removed packages Removed Package Page","code":""},{"path":"troubleshooting-build-report.html","id":"system-requirement-missing-in-the-bioconductor-build-system","chapter":"23 Troubleshooting Build Report","heading":"23.5.12.4 System Requirement missing in the Bioconductor Build System","text":"package may fail build check Bioconductor Build System (BBS)\npackage dependencies System Requirement \navailable BBS.instance, first Bioconductor package suggested installation \narchive\nCRAN package, pass checks BBS. build report stated \n“archive package found”, however package present\nCRAN months. archive package reports among system requirements\nlibarchive library, BBS library installed.happen miss system dependency BBS, please open issue similar\nBBS issue #220, \nmention Bioconductor package either directly indirectly\nsystem requirement, possible provide information missing\npackage need installed. follow pull requests related\nissue, see solution installation \nlibarchive-dev package, BBS Bioconductor docker images.","code":""},{"path":"troubleshooting-build-report.html","id":"depFun311","chapter":"23 Troubleshooting Build Report","heading":"23.5.13 Deprecated Functions","text":"Functions can deprecated, defunct, eventually removed. Bioconductor tries\nenforce progression allow maintainers adjust code. deprecated\ndefunct functions () suggest alternative. following \nnoted Bioconductor 3.11","code":""},{"path":"troubleshooting-build-report.html","id":"rangeddata","chapter":"23 Troubleshooting Build Report","heading":"23.5.13.1 RangedData","text":"","code":"Error : RangedData objects are defunct. Please migrate your code to use GRanges\n or GRangesList objects instead. See IMPORTANT NOTE in ?RangedData"},{"path":"troubleshooting-build-report.html","id":"normalize","chapter":"23 Troubleshooting Build Report","heading":"23.5.13.2 Normalize","text":"","code":"Error:\n'normalize' is defunct.\nUse ''normalize,SingleCellExperiment-method' is defunct.\nUse 'logNormCounts' instead' instead."},{"path":"troubleshooting-build-report.html","id":"calculateqcmetrics","chapter":"23 Troubleshooting Build Report","heading":"23.5.13.3 calculateQCMetrics","text":"","code":"Error:\n'calculateQCMetrics' is defunct.\nUse 'perCellQCMetrics' instead."},{"path":"debugging-cc-code.html","id":"debugging-cc-code","chapter":"24 Debugging C/C++ code","heading":"24 Debugging C/C++ code","text":"following applies non-Windows operating systems. \nfaint heart, requires C-level familiarity.learn better visually, see video Bioconductor\nalum using gdb debug R packages native code.benefit diagnose--crash Case\nstudy examples steps logic written\n; one need rewind video review steps.","code":""},{"path":"debugging-cc-code.html","id":"set-up","chapter":"24 Debugging C/C++ code","heading":"24.1 Set-up","text":"first, essential, step write short script reliably \nquickly reproduces error. Call script buggy.R.debugging package code C/C++ level, one usually starts \ninstalling package without compiler optimizations, e.g., \nfollowingsection 6.3.3. setting instancein .R/Makevars. See relevant Package Guidelines\nsection examples information.","code":"RShowDoc(\"R-admin\")CFLAGS=-ggdb -O0"},{"path":"debugging-cc-code.html","id":"detecting-memory-errors-valgrind","chapter":"24 Debugging C/C++ code","heading":"24.2 Detecting memory errors (Valgrind)","text":"Valgrind mature suite tools \nlow-level program analysis. Valgrind’s memory error checker\n(Memcheck) \npremier tool diagnosing C/C++ memory errors.Valgrind can used spot memory access problems, \ncommon source segfaults C/C++ code. bug isolated \neasily produced buggy.R, start R :runs quite slowly, flag invalid memory read write\nlocations. former typically contribute bad data, latter \nmemory corruption spectacular failures. output require C\nfamiliarity interpret. helpful run buggy code \npackage installed without compiler optimizations. See\nsection 4.3 RShowDoc(\"R-exts\") relevant Package Guidelines\nsection.","code":"R -d valgrind -f buggy.R"},{"path":"debugging-cc-code.html","id":"interactive-debugging-gdb-or-lldb","chapter":"24 Debugging C/C++ code","heading":"24.3 Interactive debugging (gdb or lldb)","text":"never used command-line debugger, many fine\nquick-start guides web; daunting seems.Linux preferred debugger gdb, lldb default Mavericks\nplatform. interfaces similar, accustomed \ngdb, see gdb lldb command map.Start R C-level debugger gdb.’ll end gdb promptand typical operation (r)un (c)ontinue executionto run buggy.R. ’ll end back C segfault, \npress cntrl-C (^C, ), ’ve inserted \n(b)reakpoint C-level function suspect buggy, e.g.,end back debugger, can print C variables \nC representation R variables (provided R isn’t confused \npoint)can also view (b)ack(t)race call stack, navigate (u)p \n(d)call stack, etc. Seeand mutual friend Google additional information.","code":"R -d gdb -f buggy.R(gdb)(gdb) r> ^C\n(gdb) b some_buggy_fun\n(gdb) c(gdb) p c_var\n(gdb) call Rf_PrintValue(some_R_variable)(gdb) help"},{"path":"debugging-cc-code.html","id":"diagnose-a-crash","chapter":"24 Debugging C/C++ code","heading":"24.3.1 Finding clues for causes of a program crash","text":"Perhaps useful function debuggers provide \nbreadcrumb trail (“backtrace”) routines led crash\nbuggy program. knowledge can narrow inquiry \ncode affects parts program state relevant time \ncrash.worth reiterating essential optimizations turned\ncompiler instructed include debugging symbols one\nhopes fruitful debugging session. See relevant Package\nGuidelines section.Though debugger output example may differ slightly compared\noutput computing environments, underlying techniques\napply diagnosing program crashes platform. See Case\nstudy real-world example uses Valgrind \ngdb conjunction.use contrived example demonstrate identify\npotential places code cause crash. able \nuse example files exactly appear. extraneous output\nomitted brevity.particular example uses lldb code compiled clang \nMavericks. example lead program crash Linux\nGCC clang.C++ file buggy.cpp:Compile R CMD SHLIB buggy.cpp -o buggy..source()ing file (buggy.R) within R session (entering\ncommands R session) lead program crash:Unfortunately R’s diagnostics illuminating:Now turn debugger. Start R lldb debugger (\nequivalent platform):point R crashes, lldb produces output, back\nlldb prompt. lldb output looks like (showing us \nframe (#0) call stack crash occurred):looks like debugger telling us memory access\nerror fetching tree node. (Trees common underlying data\nstructure standard library map). output voluminous\nlooks confusing, gist important right now.Still lldb session, enter bt command (\n“backtrace”) lldb prompt see stack frames (\nfunction calls) preceded crash. Frames listed \nascending order, starting frame crash\nhappened. (Note frame #0 frame #0 given .)\nmeans diagnosing crash, usually makes sense start\nlower-numbered frames proceed upwards.frame #5 mentions do_dotcall, native function (\nR library) corresponds .Call(\"buggy_function\") line \nbuggy.R call C entry point. can reasonably conclude\nuseful information bug probably frames #0-4.possible chain thought leads right conclusion:frames #0-2 look like dealing tree/map internals;\nignore moment.frames #0-2 look like dealing tree/map internals;\nignore moment.frame #3 indicates probably talking map\nconst_iterator variable declared line #14 buggy.cpp\n(std::map::const_iterator = m.begin();).frame #3 indicates probably talking map\nconst_iterator variable declared line #14 buggy.cpp\n(std::map::const_iterator = m.begin();).frame #4 key: tells us line (#17) buggy.cpp file\n(++;) execution went C++ code wrote \nmap iterator internals produced error.frame #4 key: tells us line (#17) buggy.cpp file\n(++;) execution went C++ code wrote \nmap iterator internals produced error.Eureka! carefully reading code buggy.cpp realize\ninserts size map m 2. means \nincrementing iterator line #16 (++;), value \nspecial\npast--end\nvalue. Incrementing iterator beyond past--end (third\n++; line #17) undefined\nbehavior!Eureka! carefully reading code buggy.cpp realize\ninserts size map m 2. means \nincrementing iterator line #16 (++;), value \nspecial\npast--end\nvalue. Incrementing iterator beyond past--end (third\n++; line #17) undefined\nbehavior!revise buggy.cpp increment beyond past--end\nremoving third ++; program runs without\ncomplaint. Problem solved!can see, debugger able immediately tell us \nprogram crashed, just program crashed. used \ninformation crash happened home parts \ncode affected program state relevant time \ncrash. Obviously example contrived; real-world scenario\nextra help afforded insight relevant program state \ninvaluable.","code":"#include \n#include \n#ifdef __cplusplus\n#define R_NO_REMAP\n#endif\n#include \n\nextern \"C\" SEXP buggy_function();\n\nSEXP buggy_function() {\n std::map m;\n m.insert(std::make_pair(5, 7));\n m.insert(std::make_pair(9, 42));\n std::map::const_iterator it = m.begin();\n ++it;\n ++it;\n ++it;\n\n return R_NilValue;\n}dyn.load(\"buggy.so\")\n.Call(\"buggy_function\")> source(\"buggy.R\")\n\n *** caught segfault ***\naddress 0x2, cause 'memory not mapped'\n\nTraceback:\n 1: .Call(\"buggy_function\")\n 2: eval(expr, envir, enclos)\n 3: eval(ei, envir)\n 4: withVisible(eval(ei, envir))\n 5: source(\"buggy.R\")R -d lldb\n(lldb) run\n## R startup messages elided\n## now in R session\n> source(\"buggy.R\")Process 21657 stopped\n* thread #1: tid = 0xbcb4ab, 0x00000001028fcbb0 buggy.so`buggy_function [inlined] std::__1::__tree_node_base* std::__1::__tree_min*>(std::__1::__tree_node_base*) at __tree:134, queue = 'com.apple.main-thread', stop reason = EXC_BAD_ACCESS (code=1, address=0x2)\n frame #0: 0x00000001028fcbb0 buggy.so`buggy_function [inlined] std::__1::__tree_node_base* std::__1::__tree_min*>(std::__1::__tree_node_base*) at __tree:134\n 131 _NodePtr\n 132 __tree_min(_NodePtr __x) _NOEXCEPT\n 133 {\n-> 134 while (__x->__left_ != nullptr)\n 135 __x = __x->__left_;\n 136 return __x;\n 137 }(lldb) bt\n* thread #1: tid = 0xbcb4ab, 0x00000001028fcbb0 buggy.so`buggy_function [inlined] std::__1::__tree_node_base* std::__1::__tree_min*>(std::__1::__tree_node_base*) at __tree:134, queue = 'com.apple.main-thread', stop reason = EXC_BAD_ACCESS (code=1, address=0x2)\n * frame #0: 0x00000001028fcbb0 buggy.so`buggy_function [inlined] std::__1::__tree_node_base* std::__1::__tree_min*>(std::__1::__tree_node_base*) at __tree:134\n frame #1: 0x00000001028fcbb0 buggy.so`buggy_function [inlined] std::__1::__tree_node_base* std::__1::__tree_next*>(std::__1::__tree_node_base*) + 20 at __tree:158\n frame #2: 0x00000001028fcb9c buggy.so`buggy_function [inlined] std::__1::__tree_const_iterator, std::__1::__tree_node, void*>*, long>::operator++() at __tree:747\n frame #3: 0x00000001028fcb9c buggy.so`buggy_function [inlined] std::__1::__map_const_iterator, std::__1::__tree_node, void*>*, long> >::operator++() at map:750\n frame #4: 0x00000001028fcb9c buggy.so`buggy_function + 188 at buggy.cpp:17\n frame #5: 0x0000000100073a13 libR.dylib`do_dotcall(call=, op=, args=, env=) + 323 at dotcode.c:578"},{"path":"debugging-cc-code.html","id":"case-study","chapter":"24 Debugging C/C++ code","heading":"24.4 Case study","text":"case study, colleague reported complicated program\n, one particular computer, produce segmentation fault \njust stop responding. series actions wouldn’t cause\nproblems computers. sounds like classic memory\nproblem, segfault difficulty reproduction.first advice develop simple script reproduced \nproblem: original report many moving parts. big insight\nbug produced running part code \nuses RCurl, followed call garbage collector, gc(). \nrole garbage collector suggests memory corruption \nsort, particular perhaps RCurl allocating (C\nlevel) R object properly PROTECT’ing garbage\ncollection. suspect RCurl rather R libcurl (possible\nplayers) least tested code. \nwrong, course… many iterations, colleague arrived \nbuggy24.R:pretty simple, doesn’t require access special\nresources (like server originally queried). \nscript doesn’t cause segfault run systems, running\nvalgrind (installed RCurl without optimizations) shows…Look around C source code RCurl’s curl.c, suggested \nbacktrace, just get oriented. doto run script gdb. Run test scriptNo error. Don’t give , set break pointand run againThat ‘file’ means gdb doesn’t know find \nRCurl package src/ directory, tell (l)ist context, \n(p)rint value C variable isProtected, seems \nsource valgrind warningisProtected value (!), furthermore value \nFALSE results PROTECT’ing object el across C calls (\nR_PreserveObject ). pretty interesting, \n’re aware garbage collection triggers segfault. valgrind \ntelling us value isProtected isn’t actually result\nassignment, result accessing array \nbounds. Let’s head call stack see value \ncoming fromWe’re entering function getCurlPointerForData value\nLOGICAL(isProtected)[ % n ]. , isProtected now R\nobject, C variable. Looking surrounding code, % n doesn’t look right – ’s probably meant recycle isProtected\ncase shorter logical variable provided \nvector elements requiring protection, value n \nnecessarily length isProtected. Let’s look \n’ve got, using C-level R function Rf_PrintValue print R\nvalues (SEXP’s) R fashionisProtected logical vector length 1.…’re trying access element 1 . C\nrepresentation R vectors zero-based, valid value \nindex 0 – ’re bounds! well bug, \n’s time try fixing (naively,\nLOGICAL(isProtected)[ % LENGTH(isProtected) ]) confirm \ndiagnosis, report packageDescription(\"RCurl\")$Maintainer\nmight better sense overall structure intention\ncode.","code":"\nlibrary(RCurl)\n\nfoo <- function() {\n url <- \"https://google.com\"\n curl <- getCurlHandle()\n opts <- list(followlocation=NULL, ssl.verifypeer=TRUE)\n d <- debugGatherer()\n getURL(url,customrequest=\"GET\",curl=curl,debugfunction=d$update,.opts=opts)\n}\n\nexecute <- function() {\n foo()\n gc()\n}\n\nexecute()> R -d valgrind -f buggy24.R\n...\n==10859== Conditional jump or move depends on uninitialised value(s)\n==10859== at 0x11BF00F6: getCurlPointerForData (curl.c:798)\n==10859== by 0x11BF0E80: R_curl_easy_setopt (curl.c:164)\n==10859== by 0x11BF17AD: R_curl_easy_perform (curl.c:89)\n==10859== by 0x4ED5499: do_dotcall (dotcode.c:588)\n==10859== by 0x4F1CAA4: Rf_eval (eval.c:593)\n==10859== by 0x4F2BD5C: do_set (eval.c:1828)\n==10859== by 0x4F1C8B7: Rf_eval (eval.c:567)\n==10859== by 0x4F2B957: do_begin (eval.c:1514)\n==10859== by 0x4F1C8B7: Rf_eval (eval.c:567)\n==10859== by 0x4F297E9: Rf_applyClosure (eval.c:960)\n==10859== by 0x4F1CBA5: Rf_eval (eval.c:611)\n==10859== by 0x4F2BD5C: do_set (eval.c:1828)R -d gdb -f buggy24.R(gdb) r(gdb) b curl.c:798(gdb) r\nBreakpoint 1, getCurlPointerForData (el=0x79e038,\n option=CURLOPT_WRITEFUNCTION, isProtected=FALSE, curl=0x1d9bdc0)\n at curl.c:798\n798 curl.c: No such file or directory.\n(gdb)(gdb) dir ~/tmp/RCurl/src\n(gdb) l\n793 }\n794 }\n795 }\n796 break;\n797 case CLOSXP:\n798 (gdb) l\n793 }\n794 }\n795 }\n796 break;\n797 case CLOSXP:\n798 if(!isProtected) {\n799 R_PreserveObject(el);\n800 }\n801 ptr = (void *) el;\n802 break;\n(gdb) p isProtected\n$5 = FALSE(gdb) up\n#1 0x00007ffff426e273 in R_curl_easy_setopt (handle=0x15d9600,\n values=0x1445788, opts=0xf3d418, isProtected=0xb7d308, encoding=0x776db0)\n at curl.c:164\n164 val = getCurlPointerForData(el, opt, LOGICAL(isProtected)[ i % n ], obj);\n(gdb) l\n159 /* Loop over all the options we are setting. */\n160 for(i = 0; i < n; i++) {\n161 opt = INTEGER(opts)[i];\n162 el = VECTOR_ELT(values, i);\n163 /* Turn the R value into something we can use in libcurl. */\n164 val = getCurlPointerForData(el, opt, LOGICAL(isProtected)[ i % n ], obj);\n165\n166 if(opt == CURLOPT_WRITEFUNCTION && TYPEOF(el) == CLOSXP) {\n167 data->fun = val; useData++;\n168 status = curl_easy_setopt(obj, CURLOPT_WRITEFUNCTION, &R_curl_write_data);\n(gdb)(gdb) p isProtected\n$1 = (SEXP) 0xaad8a0\n(gdb) call Rf_PrintValue(isProtected )\n[1] FALSE(gdb) p i\n$7 = 1\n(gdb) p n\n$8 = 6\n(gdb) p i % n\n$9 = 1"},{"path":"deprecation.html","id":"deprecation","chapter":"25 Deprecation Guidelines","heading":"25 Deprecation Guidelines","text":"normal course software development, functions, classes, methods, \ndata objects may need removed. guidelines ensuring\nprocess minimally disruptive users.","code":""},{"path":"deprecation.html","id":"what-to-deprecate","chapter":"25 Deprecation Guidelines","heading":"25.1 What to Deprecate?","text":"function, class, method, data, even package longer used \nneeded.","code":""},{"path":"deprecation.html","id":"when-to-follow-these-guidelines","chapter":"25 Deprecation Guidelines","heading":"25.2 When to Follow These Guidelines?","text":"Note decide using function introduced\nwithin development cycle, may simply remove function\nwithout following standard function deprecation guidelines. expected\ndevel branch unstable subject API changes without notice\n(though may decide communicate changes users via \nBioconductor support site).However, function published least one release version\nBioconductor, guidelines must followed. process removing\nfeature function, class, method, exported package object\ntakes approximately three release cycles (18 months).","code":">|--- Bioconductor development cycle ---------------|>\n>|--- o feature introduced --- o feature removed ---|>>| Bioconductor RELEASE_X_Y | Bioconductor development cycle |>\n>|-- o feature introduced --|----- o feature removed --------|>"},{"path":"deprecation.html","id":"deprecate-function","chapter":"25 Deprecation Guidelines","heading":"25.3 How To Deprecate A Function","text":"","code":""},{"path":"deprecation.html","id":"step-1-deprecate-the-function","chapter":"25 Deprecation Guidelines","heading":"25.3.1 Step 1: Deprecate the function","text":"first decide deprecate function, mark \ndeprecated devel branch. calling .Deprecated()\ninside function. , must provide replacement function\nused place old function. Example:causes warning emitted whenever user calls\nmyOldFunc(). See ?.Deprecated information.Indicate man page old function \ndeprecated, suggest replacement function. sure old\nfunction called man page examples vignette code chunks; R\nCMD check report .","code":"myOldFunc <- function()\n{\n .Deprecated(\"myNewFunc\")\n ## use new function, or remainder of myOldFunc\n}\\name{MyPkg-deprecated}\n\\alias{MyPkg-deprecated}\n\\title{Deprecated functions in package \\sQuote{MyPkg}}\n\n\\description{\n These functions are provided for compatibility with older versions\n of \\sQuote{MyPkg} only, and will be defunct at the next release.\n}\n\n\\details{\n\n The following functions are deprecated and will be made defunct; use\n the replacement indicated below:\n \\itemize{\n\n \\item{myOldFunc: \\code{\\link{newFunc}}}\n\n }\n}"},{"path":"deprecation.html","id":"step-2-mark-the-function-as-defunct","chapter":"25 Deprecation Guidelines","heading":"25.3.2 Step 2: Mark the function as defunct","text":"next release cycle, function deprecated, \nmust made defunct devel branch. means call \nold function return informative error run \nadditional code. Example:See ?Defunct information.Remove documentation defunct function, add man\npage following:","code":"myOldFunc <- function()\n{\n .Defunct(\"myNewFunc\")\n}\\name{MyPkg-defunct}\n\\alias{myOldFunc}\n\\title{Defunct functions in package \\sQuote{pkg}}\n\\description{These functions are defunct and no longer available.}\n\n\\details{\n Defunct functions are: \\code{myOldFunc}\n}"},{"path":"deprecation.html","id":"step-3-remove-the-function","chapter":"25 Deprecation Guidelines","heading":"25.3.3 Step 3: Remove the function","text":"next release cycle, function marked defunct,\nremove entirely package R code NAMESPACE devel\nbranch. Also remove man page content documents function.Leave man page previous step place thatstill shows list defunct functions appropriate replacements.","code":"help(\"MyPkg-defunct\")"},{"path":"deprecation.html","id":"deprecate-dataset","chapter":"25 Deprecation Guidelines","heading":"25.4 How To Deprecate An S3 Dataset","text":"","code":""},{"path":"deprecation.html","id":"step-1---create-an-s3-deprecation-class","chapter":"25 Deprecation Guidelines","heading":"25.4.1 Step 1 - Create an S3 deprecation class","text":"initial step deprecating dataset signal users \ndataset longer used. Alert user warning message added \nprint method. , first add deprecation class dataset\nobject. Note class name arbitrary descriptive:serialize class R object can loaded \npackage:usethis:","code":"class(pkgDataset) <- c(\"DeprecatedData\", class(pkgDataset))save(pkgDataset, file = \"data/pkgDataset.rda\")usethis::use_data(pkgDataset, overwrite = TRUE)"},{"path":"deprecation.html","id":"step-2---create-a-print-method","chapter":"25 Deprecation Guidelines","heading":"25.4.2 Step 2 - Create a print method","text":"create print method new class print warning\nmessage:useful guide user replacement dataset functionality\nreplace data warning message. Note method\nexported package’s NAMESPACE file.","code":"print.DeprecatedData <- function(x, ...) {\n warning(\"'pkgDataset' dataset is deprecated; see '?newData'\")\n NextMethod()\n}"},{"path":"deprecation.html","id":"step-3---update-documentation","chapter":"25 Deprecation Guidelines","heading":"25.4.3 Step 3 - Update documentation","text":"dataset object saved, update documentation \nreflect changes provide additional details resources \nusers necessary. recommended include “[Deprecated]” label\ndata documentation title.","code":""},{"path":"deprecation.html","id":"step-4---defunct-the-dataset","chapter":"25 Deprecation Guidelines","heading":"25.4.4 Step 4 - Defunct the dataset","text":"following release cycle, upgrade warning message error\nmessage indicate longer available. data can \nremoved package. Remember update “[Deprecated]”\nlabel documentation title “[Defunct]”.","code":""},{"path":"deprecation.html","id":"how-to-deprecate-an-s4-dataset","chapter":"25 Deprecation Guidelines","heading":"25.5 How to Deprecate An S4 Dataset","text":"","code":""},{"path":"deprecation.html","id":"step-1---create-an-s4-deprecation-class","chapter":"25 Deprecation Guidelines","heading":"25.5.1 Step 1 - Create an S4 deprecation class","text":"S4, process similar S3, need create new class\ninherits original class setClass. class name \narbitrary descriptive:setClass call creates generator function can use\ncreate instance new class old object:serialize object disk can loaded \npackage:using usethis:","code":".DeprecatedData <-\n setClass(\"DeprecatedData\", contains = \"S4Class\")myS4DataObject <- .DeprecatedData(myS4DataObject)save(myS4DataObject, file = \"data/myS4DataObject.rda\")usethis::use_data(myS4DataObject, overwrite = TRUE)"},{"path":"deprecation.html","id":"step-2---create-a-show-method","chapter":"25 Deprecation Guidelines","heading":"25.5.2 Step 2 - Create a show method","text":"Create show method new class produce warning message:Note method exported package’s NAMESPACE \nshow generic imported methods package.Note steps 3 4 S3 datasets.","code":"setMethod(\"show\", \"DeprecatedData\", function(object) {\n warning(\"This dataset is deprecated; see '?newData'\")\n callNextMethod()\n})"},{"path":"deprecation.html","id":"deprecate-package","chapter":"25 Deprecation Guidelines","heading":"25.6 How to Deprecate a Package","text":"Please see section Package End Life Policy","code":""},{"path":"package-end-of-life-policy.html","id":"package-end-of-life-policy","chapter":"26 Package End of Life Policy","heading":"26 Package End of Life Policy","text":"Bioconductor project strives provide software repository \nstable relevant users across community. year 100-150 new\nsoftware packages added repository; Spring 2021 2000\npackages hosted. Bioconductor Build System (BBS) installs, builds, \nchecks software package every 24 hours. Regular execution example,\nvignette, unit test code ensures package operating expected \nrequired dependencies available. build system\nprovides detailed report package across three platforms: Linux,\nWindows, Mac.effort maintain high quality repository adopted \none-year end life (EOL) process packages longer pass\nbuild check active maintainer. Packages \nassessed EOL deprecation prior Bioconductor release; \nEOL policies apply software, annotation, workflow, experiment data\npackages.","code":""},{"path":"package-end-of-life-policy.html","id":"criteria-for-package-deprecation-by-core-team","chapter":"26 Package End of Life Policy","heading":"26.1 Criteria for package deprecation by Core Team","text":"R CMD build check errors one platforms\npackage must build check without error platforms\n(exceptions cross-platform builds available limited\ncircumstances) Bioconductor release. efforts \nmade keep package repository maintainer \nactively attempting fix.\npackage broken extended period time maintainer \ngiven final 2 week notice. package fixed end\n2 weeks, End Life started.R CMD build check errors one platformsThe package must build check without error platforms\n(exceptions cross-platform builds available limited\ncircumstances) Bioconductor release. efforts \nmade keep package repository maintainer \nactively attempting fix.package broken extended period time maintainer \ngiven final 2 week notice. package fixed end\n2 weeks, End Life started.Inactive maintainer\nmaintainer listed DESCRIPTION file must responsive \nquestions support site, package-related email users \nBioconductor team members, package-related errors build\nsystem, requests bug fixes. email DESCRIPTION must also\nremain valid, active email.Inactive maintainerThe maintainer listed DESCRIPTION file must responsive \nquestions support site, package-related email users \nBioconductor team members, package-related errors build\nsystem, requests bug fixes. email DESCRIPTION must also\nremain valid, active email.","code":""},{"path":"package-end-of-life-policy.html","id":"user-requested-deprecation","chapter":"26 Package End of Life Policy","heading":"26.2 User Requested Deprecation","text":"Alternatively, package maintainer may request package deprecation. \nmaintainer may number reasons deprecating package. \ncommon reasons include:longer wish maintain packageThey longer wish maintain packageThe package functionality superseded packagesThe package functionality superseded packagesThe package material become --date makes sense retire \npackage.package material become --date makes sense retire \npackage.Significant changes underlying technology e.g., web API, made\npackage unmaintainable.Significant changes underlying technology e.g., web API, made\npackage unmaintainable.ask maintainers wishing deprecate package send email\nnotification bioc-devel mailing list. core team \nensure necessary steps notifications can occur.","code":""},{"path":"package-end-of-life-policy.html","id":"end-of-life-process","chapter":"26 Package End of Life Policy","heading":"26.3 End of Life process","text":"Step : DeprecationPackages deprecated marked deprecation warning \npackage name strikethrough build report. warning \nemitted package loaded, reported package ‘landing\npage’. message alerts users package currently fails minimal\nbuild check criteria, package likely removed \nBioconductor next release.time 6 month period required criteria met (e.g., \npackage returns active maintenance, perhaps ‘adoption’ third\nparty) warning removed.Step II: DefunctWhen package gone one development cycle ‘deprecated’ without\nremedial action, package marked ‘Defunct’. package removed\nnightly build system, longer available \n‘BiocManager::install()’, current ‘landing page’.package remains available git archive, previous\nversions Bioconductor.Defunct packages re-enter Bioconductor repository except \nreview ‘new package’.Example:package identified deprecation Bioconductor release 3.2 /\ndevel 3.3 make following transitions:","code":"- deprecate in devel 3.3\n** Bioc Release **\n- deprecate in release 3.3 (i.e., no change in release status)\n- defunct in devel 3.4\n** Bioc Release **\n- defunct in release 3.4\n- gone in devel 3.5\n** Bioc Release **\n- gone in release 3.5"},{"path":"package-end-of-life-policy.html","id":"implementation-detail","chapter":"26 Package End of Life Policy","heading":"26.4 Implementation detail","text":"Notify bioc-devel mailing list maintainers packages\nDepending, Importing, Suggesting package package\ndeprecated. appropriate, indicate new maintainer\nwelcome take .Notify bioc-devel mailing list maintainers packages\nDepending, Importing, Suggesting package package\ndeprecated. appropriate, indicate new maintainer\nwelcome take .Add following code chunk ‘devel’ version package\nfile R/zzz.R, adjusting Bioconductor version \nversion current devel version.\n.onAttach <- function(libname, pkgname) {\n msg <- sprintf(\n \"Package '%s' deprecated removed Bioconductor\n version %s\", pkgname, \"3.4\")\n .Deprecated(msg=paste(strwrap(msg, exdent=2), collapse=\"\\n\"))\n}Add following code chunk ‘devel’ version package\nfile R/zzz.R, adjusting Bioconductor version \nversion current devel version.Add following annotation package DESCRIPTION file.\nPackageStatus: DeprecatedAdd following annotation package DESCRIPTION file.PackageStatus: DeprecatedThe package remains deprecated ‘devel’ branch 6\nmonths, time Bioconductor core\nteam members remove package ‘devel’ package manifest.package remains deprecated ‘devel’ branch 6\nmonths, time Bioconductor core\nteam members remove package ‘devel’ package manifest.","code":".onAttach <- function(libname, pkgname) {\n msg <- sprintf(\n \"Package '%s' is deprecated and will be removed from Bioconductor\n version %s\", pkgname, \"3.4\")\n .Deprecated(msg=paste(strwrap(msg, exdent=2), collapse=\"\\n\"))\n}"},{"path":"package-end-of-life-policy.html","id":"reversing-end-of-life-status","chapter":"26 Package End of Life Policy","heading":"26.5 Reversing End of Life Status","text":"deprecated package can un-deprecated removed End Life\nprocess fixed next Bioconductor release. \npackage un-deprecated, please contact maintainer@bioconductor.org. package\nalready defunct stage; package mostly likely requested \ngo new package submission process .","code":""},{"path":"package-end-of-life-policy.html","id":"orphaned-packages","chapter":"26 Package End of Life Policy","heading":"26.6 ‘Orphaned’ packages","text":"‘orphaned’ package Bioconductor package inactive \nnon-responsive maintainer. described , Bioconductor makes multiple\nefforts reach package maintainers fix broken packages. \nresponse maintainer emails sent core team, \npackage considered ‘orphaned’. Occasionally, members Bioconductor\ncommunity reach take maintenance ‘orphaned’ package. \ninterested replacement maintainer asked email original maintainer \nmaintainer@bioconductor.org, formally request permission take . Unless\nexplicit request package retired, Bioconductor \ngrant access interested replacement maintainer accordance open\nsource software licenses Bioconductor packages require \npackage naming policy maintainers agree upon submission.","code":""},{"path":"branch-rename-faqs.html","id":"branch-rename-faqs","chapter":"27 Branch Rename FAQs","heading":"27 Branch Rename FAQs","text":"Bioconductor project chosen ‘devel’ default branch \nGitHub git repositories. prepare transition, compiled \nlist Frequently Asked Questions (FAQs) instructions \nrename default branch local clones GitHub.","code":""},{"path":"branch-rename-faqs.html","id":"what-is-changing","chapter":"27 Branch Rename FAQs","heading":"27.1 What is changing?","text":"Bioconductor core team rename default branch ‘devel’ \nBioconductor git repository git.bioconductor.org. \nrepository clones including hosting platforms GitHub, GitLabs,\netc. directly affected core team’s change; however, \nhighly recommend maintainers developers update local cloud\nrepository clones match default branch name.","code":""},{"path":"branch-rename-faqs.html","id":"who-is-affected-by-this-change","chapter":"27 Branch Rename FAQs","heading":"27.2 Who is affected by this change?","text":"Bioconductor developers maintainers affected change.\nBioconductor users affected.","code":""},{"path":"branch-rename-faqs.html","id":"what-repositories-are-affected-by-this-change","chapter":"27 Branch Rename FAQs","heading":"27.3 What repositories are affected by this change?","text":"Note may exist several clones single repository, e.g., \ndifferent servers workstations. repository resides \nBioconductor server hosted git.bioconductor.org affected. \ndefault branch packages Bioconductor git server\nset devel. Maintainers collaborators responsible \nupdating local cloud repository clones.recommend synchronizing default branch changes GitHub-hosted\nrepository simplify workflows.typical setup scenarios, see tidyverse blog\npost.","code":""},{"path":"branch-rename-faqs.html","id":"what-do-i-need-to-change","chapter":"27 Branch Rename FAQs","heading":"27.4 What do I need to change?","text":"recommend Bioconductor developers rename default branches \nlocal repositories ‘devel’. Optionally (highly encouraged), GitHub\nlocal copies affected repositories, including \ncollaborators, branches renamed.Bioconductor users need anything.Note. minority maintainers without GitHub repository \nrename set ‘HEAD’ follows:maintainers GitHub repositories see sections \nset ‘devel’ default branch \nGitHub? set\n‘devel’ default local\n’branch?, respectively.","code":"git branch -m master devel\ngit fetch origin\ngit branch -u origin/devel devel\ngit remote set-head origin -a"},{"path":"branch-rename-faqs.html","id":"what-if-i-am-an-rstudio-user","chapter":"27 Branch Rename FAQs","heading":"27.5 What if I am an RStudio user?","text":"Maintainers use RStudio familiar running git commands\nvia Terminal tab RStudio. commands shown documentation\ncan entered Terminal tab, e.g., git fetch --obtain \nupdates available remotes.","code":""},{"path":"branch-rename-faqs.html","id":"what-if-i-create-a-fresh-clone-of-my-repository","chapter":"27 Branch Rename FAQs","heading":"27.6 What if I create a fresh clone of my repository?","text":"possible create fresh clone repository may lose\nworking changes old local repository. done \ncomfortable git like start afresh. also\nneed set git remotes \n.","code":""},{"path":"branch-rename-faqs.html","id":"what-should-my-git-remotes-look-like","chapter":"27 Branch Rename FAQs","heading":"27.7 What should my Git remotes look like?","text":"reminder, maintainers use GitHub following recommended\nsetup. command git remote -v display origin remote points\nGitHub location upstream remote points Bioconductor\ngit repository. example, set BiocGenerics:Note. maintainers, use SSH protocol remotes.","code":"git remote -v\n# origin git@github.com:Bioconductor/BiocGenerics (fetch)\n# origin git@github.com:Bioconductor/BiocGenerics (push)\n# upstream git@git.bioconductor.org:packages/BiocGenerics (fetch)\n# upstream git@git.bioconductor.org:packages/BiocGenerics (push)"},{"path":"branch-rename-faqs.html","id":"how-do-i-sync-my-git-remotes","chapter":"27 Branch Rename FAQs","heading":"27.8 How do I sync my Git remotes?","text":"making updates local branches, make sure remotes origin\nupstream sync :Note. commands run old local repository \napply freshly cloned repositories.","code":"git checkout master\ngit pull origin master\ngit pull upstream devel:master"},{"path":"branch-rename-faqs.html","id":"how-do-i-set-devel-as-the-default-branch-on-github","chapter":"27 Branch Rename FAQs","heading":"27.9 How do I set ‘devel’ as the default branch on GitHub?","text":"maintainers manage GitHub repositories like use streamlined\ncommands, recommend synchronizing default branch changes GitHub\nrepositories. end, GitHub provided convenient way rename \ndefault branch repository. First, go \nhttps://github.com/{username}/{repo}/branches \nusername repo correspond GitHub username repository,\nrespectively., click ‘edit’ pencil 🖊 rename branch (seen\nbottom right corner) rename branch ‘devel’:’s ! default branch GitHub now set devel.Follow instructions set ‘devel’ default local\nbranch? sync local\nrepository clones.","code":""},{"path":"branch-rename-faqs.html","id":"what-if-i-already-have-a-devel-branch-on-github","chapter":"27 Branch Rename FAQs","heading":"27.10 What if I already have a ‘devel’ branch on GitHub?","text":"Simply select “switch default branch” button (looks like exchange\narrows 🔄) top right “Default\nbranch” box navigating https://github.com/{username}/{repo}/branches\nusername repo correspond GitHub username repository,\nrespectively.","code":""},{"path":"branch-rename-faqs.html","id":"how-do-i-set-devel-as-the-default-local-branch","chapter":"27 Branch Rename FAQs","heading":"27.11 How do I set ‘devel’ as the default local branch?","text":"order keep commands simple avoid confusion, recommend making \ndefault branch changes GitHub repository. allows minimal\ncommands asto simply work without specifying additional parameters, (e.g., main:devel)\npushing GitHub Bioconductor.maintainers wish make changes GitHub well, recommend\nperforming rename operation \nGitHub first, \nperforming adjustment (rename) local branch(es).Note. step necessary cloned fresh copy \nBioconductor git server though re-specify origin \nupstream remotes (described )\nfresh copy.branch renamed GitHub, use GitHub-provided commands update\nlocal copy repository:Note. Change ‘master’ ‘main’ repository ‘main’ default\nbranch:","code":"git push origin\ngit push upstreamgit branch -m master devel\ngit fetch origin\ngit branch -u origin/devel devel\ngit remote set-head origin -agit branch -m main devel\ngit fetch origin\ngit branch -u origin/devel devel\ngit remote set-head origin -a"},{"path":"branch-rename-faqs.html","id":"how-do-i-push-to-bioconductor-after-renaming","chapter":"27 Branch Rename FAQs","heading":"27.12 How do I push to Bioconductor after renaming?","text":"push upstream Bioconductor, developer simply push \ndevel branch:","code":"## branch should already exist\ngit checkout devel\n#### \ngit push upstream devel"},{"path":"branch-rename-faqs.html","id":"clean-up-how-do-i-get-rid-of-stale-remote-tracking-branches","chapter":"27 Branch Rename FAQs","heading":"27.13 Clean up: How do I get rid of stale remote-tracking branches?","text":"rename, remain stale references origin remote.\nSee local remote branches git branch -:Run following get rid stale reference “master” origin\nremote:Note. Remove --dry-run option making sure correct\nremote reference listed.","code":"git branch -a\n# * devel\n# remotes/origin/HEAD -> origin/devel\n# [...]\n# remotes/origin/mastergit remote prune origin --dry-run"},{"path":"branch-rename-faqs.html","id":"what-if-i-have-a-gitlab-repository","chapter":"27 Branch Rename FAQs","heading":"27.14 What if I have a GitLab repository?","text":"possible also change default branch GitLab. See \nchange default branch instructions.\ncomplete, can update local repository similarly \ninstructions.","code":""},{"path":"reviewer-resources-overview.html","id":"reviewer-resources-overview","chapter":"Overview","heading":"Overview","text":"following sections contain resources package reviewers \ninterested becoming package reviewers. find reviewer expectations,\nuseful tools, volunteer community reviewer.also encourage communication conversation package review \ncommunity addition assigned reviewers: Packages Review. \npackage reviews publicly accessible, therefore feedback interactions \nsubmitted packages must abide Bioconductor Code Conduct.","code":""},{"path":"review-expectation.html","id":"review-expectation","chapter":"28 Review Expectations","heading":"28 Review Expectations","text":"Anyone Bioconductor community package Bioconductor can\nvolunteer become community reviewer assess incoming packages submitted\nNew Submission Tracker. following\noverviews expected community reviewers.QualificationsTime CommitmentAssignmentsExpectations deadlinesAccept Decline PackagesRequesting reassignment temporary leave assignmentOn-boardingRecognitionVolunteer","code":""},{"path":"review-expectation.html","id":"review-qualifications","chapter":"28 Review Expectations","heading":"Qualifications","text":"Actively maintaining Bioconductor package","code":""},{"path":"review-expectation.html","id":"review-time-commitment","chapter":"28 Review Expectations","heading":"Time commitment","text":"Package reviews can vary depending quality organization \nsubmitted package. average package review single package \n30 min - 1.5 hour.also plan quarterly “-hands” meeting currently active\nreviewers. meeting acquaint reviewers new\nrequirements, classes, checks activated CRAN BiocCheck, etc. also\nplace raise questions comments larger group perhaps point\nfrequently used comments (perhaps implemented automated\ncheck). Everyone ends slightly different review styles \nbeneficial discuss everyone finds priority. Every effort \nmade attend meetings expect reviewer attend least\nyear.","code":""},{"path":"review-expectation.html","id":"review-assignments","chapter":"28 Review Expectations","heading":"Assignments","text":"Packages assigned evenly randomly, community review\nengagement distributed currently anticipate package assigned \nevery week every 2 weeks. weeks leading Bioconductor\nrelease.‘Additional Package’/‘Circular dependency’ packages submitted occasionally.\nSubmitters allowed submit related packages issue. \noccurs, assigned reviewer responsible reviews \naccept issue packages accepted state.","code":""},{"path":"review-expectation.html","id":"review-expectations-and-deadlines","chapter":"28 Review Expectations","heading":"Expectations and deadlines","text":"Package[s] expected reviewed within 3 weeks assignment \nproduce clean build report build machine. plan make hard\nlimit 3 weeks. delay submitter, issue closed\ninactivity; reopened submitter can commit timely\nupdates engagement review process. delay reviewer,\nreassigned someone else. keep track many\nreassignments occur frequent reassignments (3-4 unexplained) \nremove reviewer person must reapply \nreactivated. Active reviewers expected review least 1 package per\nBioconductor release cycle. Otherwise removed active\nreviewer.","code":""},{"path":"review-expectation.html","id":"acceptdecline","chapter":"28 Review Expectations","heading":"Accept and Decline Packages","text":"general try work submitters get package \nstate acceptable inclusion Bioconductor regardless \nlong takes. willing take critiques open minded \nBioconductor requirements; work . reviewer truly feels \npackage qualify Bioconductor (applicability, coding\nstyle, etc) encounters difficult submitter (unwilling make changes,\naggressive, etc) , please reach package review administrators. \nadministrators make final determination official rejection \ntake review becomes uncomfortable.","code":""},{"path":"review-expectation.html","id":"review-reassignment-and-temporary-leave","chapter":"28 Review Expectations","heading":"Requesting reassignment and temporary leave of assignment","text":"temporary leave assigning packages needs occur (vacation,\nparticularly busy period time, etc), reviewer reach \npackage review committee administrator. administrator temporarily stop\nassignments can discuss currently assigned packages need re-assignment.reviewers slack channel package reviewers ask questions necessary\nask swap/switch/volunteer review packages. Requests can also made \ndirectly contacting package review administrator.Reviewers request reassignment simply lack interest \nlack expertise particular area. review focus ease--use\npackage, documentation, well written code, interoperability. \nreviewer knows particular ‘expert’ field relating submitted\npackage can request someone offer additional comments (including \nofficially part package review list) without explicitly asking \nreassignment.Frequent requests reassignment consider longer leave absence\nagreement package review administrator. frequent requests \nmade reassignement reviewer notified risk \nremoved active review process. reviewer removed, must\nreapply become active reviewer.","code":""},{"path":"review-expectation.html","id":"review-onboarding","chapter":"28 Review Expectations","heading":"On-boarding","text":"New volunteers undergo -boarding process becoming fully active\nreviewers. -boarding process involves least one paired review\ncurrently active reviewing member. Coordination paired review\ncommunicated mentor mentee. recommended practice\nseparate review currently submitted package \ncompare results. currently active member decide another\npaired review necessary review sufficient continue \nsolo reviews.","code":""},{"path":"review-expectation.html","id":"review-recognition","chapter":"28 Review Expectations","heading":"Recognition","text":"Feel free advertise CV resumes Bioconductor reviewer.\nReviewers also listed Community Reviewers Webpage. Reviewers\nmay optionally opt-listed webpage contacting package\nreview administrator. Ideally, plan badges notable achievements\nmilestones, sticker progress.","code":""},{"path":"review-expectation.html","id":"review-volunteer","chapter":"28 Review Expectations","heading":"Volunteer","text":"Refer chapter Volunteer Review details.","code":""},{"path":"reviewtools.html","id":"reviewtools","chapter":"29 Reviewer Resources and Tools","heading":"29 Reviewer Resources and Tools","text":"Reviewers may find following links references useful.","code":""},{"path":"reviewtools.html","id":"review-checklist","chapter":"29 Reviewer Resources and Tools","heading":"Package Review checklist","text":"Reviewers can download template review checklist .checklist can pasted relevant issue New Submission\nTracker, updated review progresses.","code":""},{"path":"reviewtools.html","id":"review-example","chapter":"29 Reviewer Resources and Tools","heading":"Example Review","text":"\nReview 1787: MAGAR\n\nReview 2090: HubPub\n\nReview 1229: BiocSet\n\nReview 1659: AnVILBilling\n\nReview 1671: AnVILPublish\n\nReview 311: AnnotationFilter\n\nReview 498: restfulSEData\n\nReview 1270: biscuiteerData/biscuiteer\n","code":""},{"path":"review-volunteer-chapter.html","id":"review-volunteer-chapter","chapter":"30 Volunteer to Review","heading":"30 Volunteer to Review","text":"Anyone Bioconductor community can volunteer become Bioconductor\ncommunity reviewer review incoming packages submitted New\nSubmission Tracker. Please review Reviewer\nExpectations Bioconductor Code Conduct filling \nvolunteer form.","code":""},{"path":"use-devel.html","id":"use-devel","chapter":"A Using the ‘Devel’ Version of Bioconductor","heading":"A Using the ‘Devel’ Version of Bioconductor","text":"","code":""},{"path":"use-devel.html","id":"which-version-of-r","chapter":"A Using the ‘Devel’ Version of Bioconductor","heading":"A.1 Which version of R?","text":"Package authors develop version R \navailable users Bioconductor devel branch becomes \nBioconductor release branch.R ‘.y’ release x.y.z every year (typically mid-April), \nBioconductor .y release (current devel becomes release)\nevery 6 months (mid-April mid-October).means , mid-October mid-April, Bioconductor\ndevelopers developing R-devel. mid-April \nmid-October, developers use R-release (actually, R snapshot\nR-x-y-branch) Bioconductor development.See BiocManager vignette instructions using multiple versions\nBioconductor.","code":""},{"path":"use-devel.html","id":"mid-april","chapter":"A Using the ‘Devel’ Version of Bioconductor","heading":"A.2 Using ‘bioc-devel’ during mid-April to mid-October","text":"order use ‘bioc-devel’ version Bioconductor \nmid-April mid-October release cycle, use release version R\ninvoke function install(version=\"devel\") (\nBiocManager package):, packages installed ‘bioc-devel’\nrepository.","code":"if (!requireNamespace(\"BiocManager\", quietly=TRUE))\n install.packages(\"BiocManager\")\nBiocManager::install(version = \"devel\")\nBiocManager::valid() # checks for out of date packages"},{"path":"use-devel.html","id":"mid-october","chapter":"A Using the ‘Devel’ Version of Bioconductor","heading":"A.3 Using ‘bioc-devel’ during mid-October to mid-April","text":"order use ‘bioc-devel’ version Bioconductor \nmid-October mid-April release cycle, must install devel\nversion R.SourcemacOSWindowsThen, make sure version BiocManager current \npackages --date.","code":"if (!requireNamespace(\"BiocManager\", quietly=TRUE))\n install.packages(\"BiocManager\")\nBiocManager::install(version=\"devel\")\nBiocManager::valid()"},{"path":"long-tests.html","id":"long-tests","chapter":"B Long Tests","heading":"B Long Tests","text":"","code":""},{"path":"long-tests.html","id":"what-are-they","chapter":"B Long Tests","heading":"B.1 What are they","text":"Code tests subdirectory Bioconductor software\npackages run R CMD check daily basis part \nBioconductor nightly builds.\nmaximum amount time R CMD check allowed spend\npackage 40 min.Package developers wish implement tests long\nrun context nightly builds can set “long tests” \npackage add package Bioconductor Long Tests builds.","code":""},{"path":"long-tests.html","id":"setup","chapter":"B Long Tests","heading":"B.2 Setup","text":"4 steps:Put code “long tests” longtests subdirectory \npackage. Like code tests directory, code\ntypically (necessarily) run unit tests.Put code “long tests” longtests subdirectory \npackage. Like code tests directory, code\ntypically (necessarily) run unit tests.Add package Long Tests builds adding .BBSoptions\nfile top-level directory following line :\nRunLongTests: TRUEAdd package Long Tests builds adding .BBSoptions\nfile top-level directory following line :code longtests subdirectory run week\n(every Saturday) part Long Tests builds allowed\nrun maximum 6 hours TIMEOUT raised.code longtests subdirectory run week\n(every Saturday) part Long Tests builds allowed\nrun maximum 6 hours TIMEOUT raised.Check \nlatest Long Tests report BioC devel.\nnext time report updated (normally every Saturday), \npackage included .Check \nlatest Long Tests report BioC devel.\nnext time report updated (normally every Saturday), \npackage included .Note also run Long Tests builds current release\nbranch week (every Saturday). latest report builds\n.","code":"RunLongTests: TRUE"},{"path":"long-tests.html","id":"short-tests-vs-long-tests","chapter":"B Long Tests","heading":"B.3 “Short tests” vs “long tests”","text":"Long Tests setup forces developers split testing code\npackage “short tests” “long tests”. former go \ntests subdirectory must able run less 40 min (\nlimit actually full R CMD check command runs \npossibly time-consuming things addition code tests).\nlatter go longtests subdirectory must able run\nless 6 hours.Note , unlike “short tests” failures, “long tests” failures don’t\nprevent package propagating version bump. words,\neven package included Long Tests builds, propagation\nstill determined results nightly builds.","code":""},{"path":"long-tests.html","id":"need-help","chapter":"B Long Tests","heading":"B.4 Need help?","text":"Ask bioc-devel mailing list questions \nneed help Long Tests builds.","code":""},{"path":"querying-web-resources.html","id":"querying-web-resources","chapter":"C Querying Web Resources","heading":"C Querying Web Resources","text":"Packages rely access web resources need written\ncarefully. Web resources can change location, can temporarily\nunavailable, can slow access retrieve. Functions\nquery web resources, anticipate handle situations\ngracefully – failing quickly clearly resource \navailable reasonable time frame. avoidable problems seen \nBioconductor package code include infinite loops, use \navailable R connections, unclear error messages.","code":""},{"path":"querying-web-resources.html","id":"guiding-principles-1","chapter":"C Querying Web Resources","heading":"C.1 Guiding Principles","text":"Remember Bioconductor packages built nightly across multiple\noperating systems, users benefit easy--run vignettes\nexamples.Download files reasonable size. Use system.time() estimate \ndownload time. Remember package require less 10 minutes \nrun R CMD check ---build-vignettes upper limit 15 minutes.Download files reasonable size. Use system.time() estimate \ndownload time. Remember package require less 10 minutes \nrun R CMD check ---build-vignettes upper limit 15 minutes.Set limit number times function tries URL. Avoid\n() statements guaranteed termination. \nbecome infinite loops eventually result build-system TIMEOUTs.Set limit number times function tries URL. Avoid\n() statements guaranteed termination. \nbecome infinite loops eventually result build-system TIMEOUTs.Supply informative error messages.Supply informative error messages.","code":""},{"path":"querying-web-resources.html","id":"template-for-resource-queries","chapter":"C Querying Web Resources","heading":"C.2 Template for Resource Queries","text":"function can serve template appropriate resource\nretrieval. tries retrieve resource one several times \nfailing, takes arguments:URL, resource queried, typically character(1) \nurl().FUN, function used query resource. Examples might\ninclude readLines(), download.file(), httr::GET(),\nRCurl::getURL()....: additional arguments used FUN.N.TRIES: number times URL attempted; \nexceptional circumstances might differ default value.return value retrieved resource. resource retrieval\nfails, function indicates failure, including condition\n(error) message last attempt. Warnings propagate user \nnormal way.Base R functions using url() connections respect\ngetOption(\"timeout\"); see ?url details.FUN might implemented retrieve resource test \nstatus, e.g.,","code":"getURL <- function(URL, FUN, ..., N.TRIES=1L) {\n N.TRIES <- as.integer(N.TRIES)\n stopifnot(length(N.TRIES) == 1L, !is.na(N.TRIES))\n\n while (N.TRIES > 0L) {\n result <- tryCatch(FUN(URL, ...), error=identity)\n if (!inherits(result, \"error\"))\n break\n N.TRIES <- N.TRIES - 1L\n }\n\n if (N.TRIES == 0L) {\n stop(\"'getURL()' failed:\",\n \"\\n URL: \", URL,\n \"\\n error: \", conditionMessage(result))\n }\n\n result\n}FUN <- function(URL, ...) {\n response <- httr::GET(URL, timeout(getOption(\"timeout\")), ...)\n stop_for_status(response)\n response\n}"},{"path":"c-fortran.html","id":"c-fortran","chapter":"D C and Fortran code","heading":"D C and Fortran code","text":"package contains C Fortran code, adhere standards \nmethods described System foreign language interfaces\nsection Writing R Extensions manual.emphasize particular points following sections.","code":""},{"path":"c-fortran.html","id":"internal-functions","chapter":"D C and Fortran code","heading":"D.0.1 Internal functions","text":"Use internal functions, e.g., R_alloc random number generators (RNGs), system-supplied ones.","code":""},{"path":"c-fortran.html","id":"c-function-registration","chapter":"D C and Fortran code","heading":"D.0.2 C function registration","text":"Use C function registration (See Registering native routines section \nWriting R Extensions manual).","code":""},{"path":"c-fortran.html","id":"checks-for-user-interruption","chapter":"D C and Fortran code","heading":"D.0.3 Checks for user interruption","text":"Use R_CheckUserInterrupt() C level loops chance may terminate certain parameter settings run time exceeds 10 seconds typical parameter settings, method intended interactive use.","code":""},{"path":"c-fortran.html","id":"makevars-1","chapter":"D C and Fortran code","heading":"D.0.4 Makevars","text":"Make judicious use Makevars Makefile files within package.\noften required (See Configure cleanup section Writing R Extensions manual).","code":""},{"path":"c-fortran.html","id":"warnings-and-optimizations","chapter":"D C and Fortran code","heading":"D.0.5 Warnings and optimizations","text":"package development, enable warnings disable optimizations.\nplan use debugger, tell compiler \ninclude debugging symbols.easiest way enforce create user-level Makevars file user’s home directory sub-directory called ‘.R’). See examples flags common toolchains.\nConsult section Makevars files Writing R Extensions manual.Example gcc/g++:Example clang/clang++:","code":"CFLAGS=-Wall -Wextra -pedantic -O0 -ggdb\nCXXFLAGS=-Wall -Wextra -pedantic -O0 -ggdb\nFFLAGS=-Wall -Wextra -pedantic -O0 -ggdbCFLAGS=-Weverything -O0 -g\nCXXFLAGS=-Weverything -O0 -g\nFFLAGS=-Wall -Wextra -pedantic -O0 -g"},{"path":"cmavericks-best-practices.html","id":"cmavericks-best-practices","chapter":"E C++/Mavericks Best Practices","heading":"E C++/Mavericks Best Practices","text":"guide mostly addresses adapt C/C++ code Bioconductor\npackages build Mac OS X 10.9 (Mavericks). package \nuse C C++ code, can assume document relevant \n.","code":""},{"path":"cmavericks-best-practices.html","id":"table-of-contents-1","chapter":"E C++/Mavericks Best Practices","heading":"E.1 Table of Contents","text":"document written read beginning end, except \nlast section.Orientation: approach developing \nMavericks.C++11: important info C++11 clang’s standard\nlibrary implementation.Issues specific Mavericks\nenvironment: special considerations \ntools available Mavericks.C++ Best Practices: generally applicable best\npractices C++ Bioconductor packages.Issues code external\nsources: tips using code \nwritten package contributor.Lessons learned specific issues: \nrepository knowledge specific problems.might skip lessons-learned section \ncheck issue already explored.","code":""},{"path":"cmavericks-best-practices.html","id":"orientation","chapter":"E C++/Mavericks Best Practices","heading":"E.2 Orientation","text":"Note: simplicity, guide uses ‘GCC’ (GNU Compiler Collection)\n‘clang’ refer respective collection tools (including\nC++ compilers), rather simply ‘GCC C compiler’ ‘clang C\ncompiler’. ‘Mavericks environment’ refers combination clang\nXcode versions available default Mavericks.release Mavericks\nbuild R, CRAN Bioconductor adopted Apple’s preferred\ntoolchain building packages Mavericks\nplatform. Bioconductor packages built Mavericks platform\nusing OS X default combination clang Xcode.introduction Mavericks environment revealed number \nissues building packages, due C/C++ code\nrelies heavily GCC way things. problems\nrevealed transition Mavericks caused C++ coding\npractices universally recognized problematic, \naddressed adhering established best practices.common sources problems, posed Mavericks\nenvironment contrasts GCC:Undefined behavior. GCC undefined\nbehavior might fail silently without affecting program execution,\nwhereas code Mavericks environment leads \nsegfault (“segmentation fault”).Undefined behavior. GCC undefined\nbehavior might fail silently without affecting program execution,\nwhereas code Mavericks environment leads \nsegfault (“segmentation fault”).Issues related naming, particularly \ncircumventing protections offered C++ namespaces. GCC header\norganization seems forgiving loose naming, whereas \nMavericks environment exacting.Issues related naming, particularly \ncircumventing protections offered C++ namespaces. GCC header\norganization seems forgiving loose naming, whereas \nMavericks environment exacting.C++11 default language specification, clang’s\nlibc++. libc++ implementation \nC++11 standard library written scratch. time \nwriting libc++ implementation available Mac OS X.C++11 default language specification, clang’s\nlibc++. libc++ implementation \nC++11 standard library written scratch. time \nwriting libc++ implementation available Mac OS X.Code written directly package\ncontributor(s). Many Bioconductor\npackages transition well Mavericks environment\ninclude third-party (e.g., Boost) generated (e.g., SWIG)\ncode. Many external code sources make assumptions valid\nMavericks environment. compounded difficulty \ndiagnosing problems code written package author limits\nBioconductor team’s ability help package.Code written directly package\ncontributor(s). Many Bioconductor\npackages transition well Mavericks environment\ninclude third-party (e.g., Boost) generated (e.g., SWIG)\ncode. Many external code sources make assumptions valid\nMavericks environment. compounded difficulty \ndiagnosing problems code written package author limits\nBioconductor team’s ability help package.","code":""},{"path":"cmavericks-best-practices.html","id":"what-is-different-about-developing-for-the-mavericks-environment","chapter":"E C++/Mavericks Best Practices","heading":"E.2.1 What is different about developing for the Mavericks environment?","text":"biggest change introduction clang’s\nlibc++ implementation C++11 standard\nlibrary library headers associated Xcode. clang \ngaining market share several reasons, helped fact \nclang intended compiler C-based languages. Advocates\nclang hold clang:offers better diagnostic information errors warningshas quicker compilation timessometimes yields smaller binariesin cases yields faster execution speeds (disputed)guidance compiler flags use developing, see \nrelevant section Package Guidelines page.","code":""},{"path":"cmavericks-best-practices.html","id":"differences-in-unspecified-behavior-memory-addressing-policies","chapter":"E C++/Mavericks Best Practices","heading":"E.2.1.1 Differences in unspecified behavior, memory addressing policies","text":"errors encountered transition seem attributable\nreliance non-portable unspecified behaviors. See section \nguide unspecified behavior \ninformation.example, many aspects C/C++ memory addressing \nimplementation-dependent, means expected behavior \nprescribed C/C++ standard (“unspecified”) therefore \ncompiler writers decide.foremost difference regarding memory clang seems \nrestrictive --bounds memory addressing.","code":""},{"path":"cmavericks-best-practices.html","id":"find-bugs","chapter":"E C++/Mavericks Best Practices","heading":"E.2.1.2 How to find bugs","text":"GCC preferred debugger gdb, many prefer\nlldb debugging Mavericks environment.number bugs packages related memory addressing\nlayout errors, relying debugger alone might sufficient\ntrack memory errors. Valgrind \npremier tool detecting memory errors.See Bioconductor guide debugging C/C++\ncode examples using \ndebugger Valgrind.","code":""},{"path":"cmavericks-best-practices.html","id":"what-if-i-cannot-access-a-mavericks-machine","chapter":"E C++/Mavericks Best Practices","heading":"E.2.1.3 What if I cannot access a Mavericks machine?","text":"substitute using Mavericks machine troubleshoot\npackages fail Mavericks. Many errors seen \nreproducible combination clang, Xcode, OS X 10.9.several options short procuring Mavericks machine:exploratory measure, install recent version GCC\ncompile package -std=c++11 -std=gnu++11 compiler\narguments; version\n4.8.1, GCC implements\nmajor features 2011 ISO C++ standard. Diagnostics \nerrors warnings also greatly improved recent GCC\nversions. Using C++11 implementation might reveal warnings\nerrors point issues encountered Mavericks.exploratory measure, install recent version GCC\ncompile package -std=c++11 -std=gnu++11 compiler\narguments; version\n4.8.1, GCC implements\nmajor features 2011 ISO C++ standard. Diagnostics \nerrors warnings also greatly improved recent GCC\nversions. Using C++11 implementation might reveal warnings\nerrors point issues encountered Mavericks.Install clang; limited value many errors \nunique Mavericks environment.Install clang; limited value many errors \nunique Mavericks environment.Use Valgrind memory addressing problems; many errors\nMavericks platform related memory addressing problems,\nmany errors equally discoverable using Valgrind Linux.Use Valgrind memory addressing problems; many errors\nMavericks platform related memory addressing problems,\nmany errors equally discoverable using Valgrind Linux.unable diagnose problem using combination \nbuild system output Valgrind, feel free contact \nbioc-devel mailing list.unable diagnose problem using combination \nbuild system output Valgrind, feel free contact \nbioc-devel mailing list.","code":""},{"path":"cmavericks-best-practices.html","id":"CXX11","chapter":"E C++/Mavericks Best Practices","heading":"E.3 C++11","text":"Although default version clang Mavericks includes support\nC++11 features, Bioconductor support C++11 dependent \nplatform oldest toolchain. current Snow\nLeopard (Mac OS X 10.6.8) toolchain support C++11\nfeatures, Bioconductor packages generally use C++11\nfeatures. Eventually, Mavericks widely adopted, support\nSnow Leopard dropped.C++11 completely backward-compatible older standards.possible tell clang use older versions standard\nlibrary (default libc++), \nrelying OS version-specific compilation settings workable\nlong-term solution. approach greatly increases maintenance\nburden package authors limits Bioconductor team’s ability\noffer support.insidious catastrophic consequence using non-default\nstandard libraries issue binary incompatibility. Packages\nlinked one standard library liable crash\n(mysteriously) interfacing packages linked \ndifferent standard library. also true programs OS\nlevel: program compiled linked libstdc++ \nMavericks platform , default, assumed incompatible \nprograms compiled linked libc++.Code adapted avoid constructs backward- \nforward-incompatible. See forward-incompatibility\nproblems section examples.","code":""},{"path":"cmavericks-best-practices.html","id":"issues-with-Mavericks-env","chapter":"E C++/Mavericks Best Practices","heading":"E.4 Issues specific to Mavericks environment","text":"","code":""},{"path":"cmavericks-best-practices.html","id":"c-linkage","chapter":"E C++/Mavericks Best Practices","heading":"E.4.1 C Linkage","text":"C++ uses extern \"C\" give declarations C linkage, hence make\ndeclarations accessible C code. R headers \n#included C++ include C++ system headers \nC linkage. According relevant Writing R Extensions Manual\nsection,\nR header files included within extern \"C\"\nblocks.typical symptom bad linkage package load time (\ncompilation link time) error says particular symbol \nfound.C++ mangles names, symbol name R says find \noften unrecognizable. Use c++filt program installed \nsystem online name demangler produce human-readable\nversion symbol name. Note mangled names \nenvironment-specific demangler meant GCC symbol names \nLinux demangle clang symbol names Mac.Solution: R headers #included outside extern \"C\" blocks.Example correct #include R headers:","code":"#include \nextern \"C\" {\n void foo(); // function 'foo' and other code in this block has C linkage\n ...\n}\nextern \"C\" void bar(); // function 'bar' has C linkage"},{"path":"cmavericks-best-practices.html","id":"openmp","chapter":"E C++/Mavericks Best Practices","heading":"E.4.2 OpenMP","text":"writing Mavericks environment support OpenMP,\nunknown tools released Apple ever .Code rely availability OpenMP. Independent \nconcerns OpenMP support, code written start \ndegrade nicely single-threaded environment.See Writing R Extensions Manual\nsection\ninformation OpenMP code R packages, detecting\nsupport.Solution: use preprocessor -else directives code degrades\ngracefully OpenMP support available:See ShortRead package example good practices around support OpenMP.","code":"#ifdef SUPPORT_OPENMP\n // multithreaded OpenMP version of code\n#else\n // single-threaded version of code\n#endif"},{"path":"cmavericks-best-practices.html","id":"best-practices","chapter":"E C++/Mavericks Best Practices","heading":"E.5 C++ Best Practices","text":"C++ practices applicable C++ projects, \nidentified Bioconductor community particularly helpful\navoiding issues Mavericks environment.","code":""},{"path":"cmavericks-best-practices.html","id":"use-rcpp","chapter":"E C++/Mavericks Best Practices","heading":"E.5.1 Use Rcpp","text":"Rcpp CRAN package allows seamless integration C++ R, \ncross-platform. package affords many benefits \nR C interface make C++ appealing language, \neliminating many pitfalls programming R interface.package well documented, extensive repository \nworking examples many tasks: Rcpp\nGallery.","code":""},{"path":"cmavericks-best-practices.html","id":"name-resolution-errors","chapter":"E C++/Mavericks Best Practices","heading":"E.5.2 Avoid name resolution errors","text":"name resolution error occurs compiler encounters \nidentifier (e.g., variable function name) ambiguous (\n, “collision” two identifiers), name\nlookup rules lead compiler resolve name incorrectly. clang \nexacting identifiers.typical symptom name resolution error compiler complains\ntype number arguments function got different \nexpects, compiler points C++ header file \nstandard library.two primary issues name resolution writing R\npackages:","code":""},{"path":"cmavericks-best-practices.html","id":"re-mapping-of-identifiers-from-r-headers","chapter":"E C++/Mavericks Best Practices","heading":"E.5.2.1 Re-mapping of identifiers from R headers","text":"convenience, R aliases common identifiers R\nheaders. E.g., Rf_length(SEXP) becomes length(SEXP). \nmay convenient C, organization headers \nMavericks environment seems lead collisions \nGCC. See relevant section Writing R Extensions\nManualSolution: prevent re-mapping R identifiers C++ code \ndefining R_NO_REMAP symbol. can done package level\n-DR_NO_REMAP preprocessor flag, file--file basis \n#define R_NO_REMAP. Use fully-qualified versions R identifiers,\nusually prepending Rf_.Example excerpt header file prevents re-mapping:Note Rf_length just one example many R identifiers \nmight conflict names C++ standard library headers.","code":"file CxxCode.h\n------------------\n\n#ifndef CXX_CODE_H\n#define CXX_CODE_H\n#ifdef __cplusplus\n#define R_NO_REMAP\n#endif\n\n...\n\nvoid foo(SEXP s) {\n if(Rf_length(s) > 1) // fully qualified: 'Rf_length'\n ...\n}\n\n#endif"},{"path":"cmavericks-best-practices.html","id":"namespace-hygiene","chapter":"E C++/Mavericks Best Practices","heading":"E.5.2.2 Namespace hygiene","text":"Namespaces introduced C++ limit incidence name\ncollisions. Many authors new C++, however, use\nusing-directives\n(particularly ‘using namespace std’ directive) unnecessarily,\nthereby reintroducing problems namespaces meant solve.pointed cppreference Notes\nsection\nuse using namespace std directive introduces entire\nstd namespace name resolution. high likelihood \namong headers standard library identifier\nconflicts identifiers package.Solution: avoid ‘using namespace std’ directive completely \npossible, especially header files. Prefer\nusing-declarations\nusing-directives simply use fully-qualified versions \nstandard library identifiers. New C++ authors overestimate much\nincluding scope resolution operator (namely ‘std::’) affects\nreadability.Example introducing std namespace identifiers:Many new C++ authors use using-directive introduce \nidentifiers need. Avoid possible:One alternative using-declarations (e.g., ‘using std::map;’,\nallow hand-picking identifiers introduce (opposed \nentire std namespace); just want std::map \nstd::make_pair. Even list identifiers want quite\nlong just need single using-declaration one:Using-declarations can also block-scoped. preferred \nusing-declarations global scope, prevents unnecessary\nintroduction names global scope, tenet good namespace\nhygiene:perfectly good alternative simply precede standard library\nidentifiers ‘std::’, C++ programmers accustomed\nreading:","code":"#include \n#include \n// Suppose we want to access the std::map and std::make_pair identifiersusing namespace std; // introduces entire std namespace for resolutionusing std::map; // 'map' and 'make_pair' introduced at declaration scope\nusing std::make_pair;void foo() {\n using std::map;\n using std::make_pair;\n map m;\n m.insert(make_pair(5, 7));\n ...\n}void foo() {\n std::map m;\n m.insert(std::make_pair(5, 7));\n}"},{"path":"cmavericks-best-practices.html","id":"undefined-behavior","chapter":"E C++/Mavericks Best Practices","heading":"E.5.3 Avoid undefined behavior and non-portable unspecified behavior","text":"two major categories behavior prescribed \nC C++ standards:undefined behavior specified arbitrary; code \nproduces behavior might cause program crash, \nmight execute without complaint (“silently”). effect can also\ndiffer one program execution next. Well-known examples\ninclude division zero, indexing outside array bounds, \ndereferencing null pointer.undefined behavior specified arbitrary; code \nproduces behavior might cause program crash, \nmight execute without complaint (“silently”). effect can also\ndiffer one program execution next. Well-known examples\ninclude division zero, indexing outside array bounds, \ndereferencing null pointer.unspecified behavior consistent documented, decided \nimplementation. behaviors either \nmentioned respective standard, mentioned \nsay implementation-dependent. Well-known examples\ninclude size int type size pointers.unspecified behavior consistent documented, decided \nimplementation. behaviors either \nmentioned respective standard, mentioned \nsay implementation-dependent. Well-known examples\ninclude size int type size pointers.typical symptom problematic undefined unspecified behaviors \nsegfault appears Mavericks environment. reason\nproblem discovered might GCC silently\nallows code execute instead crashing program.Solution: code defensively avoid problematic constructs use\ndebuggers find code leads errors.","code":""},{"path":"cmavericks-best-practices.html","id":"issues-external-code-sources","chapter":"E C++/Mavericks Best Practices","heading":"E.6 Issues with code from external sources","text":"packages need use code written directly \ncontributor(s). common scenario include source code\nlibrary written third party. packages also use code\nproduced code generation tools, e.g.,\nSWIG. First, see relevant [Package Guidelines\nsection][third-party-libraries] \nguidance code external sources.See lessons learned section guide \nsuggestions specific code sources.","code":""},{"path":"cmavericks-best-practices.html","id":"generated-code","chapter":"E C++/Mavericks Best Practices","heading":"E.6.1 Generated Code","text":"packages use code generated third-party tools, .e.,\ncode written machines. SWIG common example.problem code written machines code meant \nread machines. top code file produced SWIG, \nexample, states code meant read edited \nhand.many code generation tools make assumptions invalid\nMavericks environment, code needs human attention fix\nerrors; inscrutable nature machine-written code\ndifficult isolate errors.Solution: re-generate problem code possible, otherwise fix \nhand. Fixing hand strongly discouraged.","code":""},{"path":"cmavericks-best-practices.html","id":"third-party-libraries","chapter":"E C++/Mavericks Best Practices","heading":"E.6.2 Third-party libraries","text":"packages include third-party libraries written \ncompiler-independent way, build ---box \nMavericks environment.Solutions approximate order preference:Check existing CRAN \nBioconductor package provides functionality, meeting\nperformance needs use case. Eliminating third-party\ncode package greatly reduces maintenance burden.Check existing CRAN \nBioconductor package provides functionality, meeting\nperformance needs use case. Eliminating third-party\ncode package greatly reduces maintenance burden.Check library updated. libraries \nactive user community undergo updates add support \ncompilers/environments.Check library updated. libraries \nactive user community undergo updates add support \ncompilers/environments.Check maintainers aware library work \nMavericks environment, find support \nforthcoming. usually easy directly contact authors \nlibraries maintained individual small group.Check maintainers aware library work \nMavericks environment, find support \nforthcoming. usually easy directly contact authors \nlibraries maintained individual small group.Use actively maintained alternate library provides\nequivalent functionality. Sometimes library longer\nmaintained, library abandoned \nalternative project provides functionality.Use actively maintained alternate library provides\nequivalent functionality. Sometimes library longer\nmaintained, library abandoned \nalternative project provides functionality.Update library code included package \nhand. Strongly discouraged. Maintainer assumes responsibility\nkeeping code --date mainline source project. \nundertaken, record descriptions changes needed \ncodebase updated changes can easily reproduced.Update library code included package \nhand. Strongly discouraged. Maintainer assumes responsibility\nkeeping code --date mainline source project. \nundertaken, record descriptions changes needed \ncodebase updated changes can easily reproduced.","code":""},{"path":"cmavericks-best-practices.html","id":"lessons-learned","chapter":"E C++/Mavericks Best Practices","heading":"E.7 Lessons learned from specific issues","text":"section serves loosely organized repository knowledge\ngained specific problems solutions. expected\ncomprehensive. Items added knowledge base\ngrows. Bioconductor eager suggestions; please write \nbioc-devel mailing list !idea start diagnosing broken package\nmight worthwhile skim section.relevant, issue marked discoverable compile\ntime runtime.applicable, link live code demo provided.","code":""},{"path":"cmavericks-best-practices.html","id":"forward-incompatible","chapter":"E C++/Mavericks Best Practices","heading":"E.7.1 Forward-incompatibility problems with C++11","text":"C++11 completely backward-compatible. particular, API\nparts standard library changed slightly, \nperhaps subtle ways. issues require minimal tweaking fix.","code":""},{"path":"cmavericks-best-practices.html","id":"container-iterator-const-ness","chapter":"E C++/Mavericks Best Practices","heading":"E.7.1.1 Container iterator const-ness","text":"Type: compile timeA number operations standard library containers now require\niterators const. Two ready examples \ninsert\nerase\nmethods take iterator parameters.","code":""},{"path":"cmavericks-best-practices.html","id":"iterating-standard-library-containers","chapter":"E C++/Mavericks Best Practices","heading":"E.7.2 Iterating standard library containers","text":"Type: runtimeGenerally, using special\npast--end\niterator value equality checks (.e., == !=)\nresults undefined behavior. Particularly, Mavericks\nenvironment:Dereferencing iterator past--end value results \nsegfaultIncrementing iterator beyond past--end value results\nsegfault","code":""},{"path":"cmavericks-best-practices.html","id":"external-code-sources","chapter":"E C++/Mavericks Best Practices","heading":"E.7.3 External code sources","text":"Common examples external code sources \nSWIG, Boost, \nnumerous file format libraries. Code external sources \nsometimes written non-compiler-independent way. Check \ndocumentation see Mavericks environment supported.","code":""},{"path":"cmavericks-best-practices.html","id":"boost","chapter":"E C++/Mavericks Best Practices","heading":"E.7.3.1 Boost","text":"Boost source free, peer-reviewed C++\nlibraries enhance language. Many parts Boost \n“header-”, means need separately compiled\nheaders merely need appear search path order \nclient code use .Many Boost libraries platform-independent, . Boost\nlibraries either process adding Mavericks environment\nsupport, library authors announced Mavericks environment\nsupport added.Solutions approximate order preference:Use BH\npackage CRAN, possible. BH package provides several Boost\nheader-libraries. Using BH package means maintenance\ncost using Boost package virtually nothing.Use BH\npackage CRAN, possible. BH package provides several Boost\nheader-libraries. Using BH package means maintenance\ncost using Boost package virtually nothing.Update Boost libraries include package. Boost\nlibraries sometimes contain bugs, later updated add\nsupport platforms. Bioconductor package\nmaintainer’s responsibility keep code package\nupdated.Update Boost libraries include package. Boost\nlibraries sometimes contain bugs, later updated add\nsupport platforms. Bioconductor package\nmaintainer’s responsibility keep code package\nupdated.Contact authors specific Boost library. \nfind announcement regarding support Mavericks\nenvironment, might worth contacting library authors \ninquire.Contact authors specific Boost library. \nfind announcement regarding support Mavericks\nenvironment, might worth contacting library authors \ninquire.","code":""},{"path":"cmavericks-best-practices.html","id":"swig","chapter":"E C++/Mavericks Best Practices","heading":"E.7.3.2 SWIG","text":"SWIG generates code interface code written C/C++ \nlanguages. time writing, SWIG support clang\nlimited, SWIG particularly problems clang’s libc++\nversion (C++11) standard library. problems \nlimited issues can addressed tweaking function\nsignatures. problems deeply embedded way SWIG\nproduces code.time writing, thread SWIG-devel mailing\nlist\nseems -depth discussion working SWIG \nMavericks.Solutions approximate order preference:Eliminate SWIG code, possible. probably \nreducing maintenance burden.Eliminate SWIG code, possible. probably \nreducing maintenance burden.Re-generate SWIG code newest version SWIG. time\nwriting SWIG recently updated include partial\nsupport C++11, might alleviate problems clang’s\nlibc++. See SWIG document \nC++11 support. \npossible new version produce problematic\ncode. Note code must valid supported compilers.Re-generate SWIG code newest version SWIG. time\nwriting SWIG recently updated include partial\nsupport C++11, might alleviate problems clang’s\nlibc++. See SWIG document \nC++11 support. \npossible new version produce problematic\ncode. Note code must valid supported compilers.Troubleshoot fix errors hand. Strongly discouraged. \nundertaken, record descriptions changes needed \ncode regenerated changes can easily reproduced.\nRead SWIG documentation find\nguidance troubleshooting. (example, SWIG -E switch\noutputs results preprocessor run.) Perhaps start \nremoving SWIG functionality gradually adding features. Find\ninformation web fix errors \npackage.Troubleshoot fix errors hand. Strongly discouraged. \nundertaken, record descriptions changes needed \ncode regenerated changes can easily reproduced.Read SWIG documentation find\nguidance troubleshooting. (example, SWIG -E switch\noutputs results preprocessor run.) Perhaps start \nremoving SWIG functionality gradually adding features. Find\ninformation web fix errors \npackage.","code":""},{"path":"cmavericks-best-practices.html","id":"f2c","chapter":"E C++/Mavericks Best Practices","heading":"E.7.3.3 f2c","text":"f2c tool converts Fortran77\ncode C/C++ code. maintenance burden required make f2c code\ncross-platform substantial. Since fortran compiler (emulator)\nrequired install R, f2c usually unnecessary. Several\npackages use native fortran code without problem.Solution: possible, remove need f2c. \nrecourse finesse makefiles point supported\nplatform less targeted makefile. Please write \nbioc-devel mailing list trouble.","code":""},{"path":"man-links.html","id":"man-links","chapter":"F Debug: Links in Rd files","heading":"F Debug: Links in Rd files","text":"","code":""},{"path":"man-links.html","id":"context","chapter":"F Debug: Links in Rd files","heading":"F.1 Context","text":"chapter describes issue resolved 31-May-2022.objective include link man page one package\nman page SummarizedExperiment class SummarizedExperiment package.Using roxygen2, link written \nfollows R file:issue rcmdcheck::rcmdcheck() reported following WARNING:","code":"#' ... \\linkS4class{SummarizedExperiment} ...W checking Rd cross-references (<...>ms)\n Missing link or links in documentation object '<...>.Rd':\n ‘SummarizedExperiment-class’\n \n See section 'Cross-references' in the 'Writing R Extensions' manual."},{"path":"man-links.html","id":"what-worked","chapter":"F Debug: Links in Rd files","heading":"F.2 What worked","text":"First, SummarizedExperiment package added Depends: section\nDESCRIPTION file.point, rcmdcheck::rcmdcheck() dropped previous WARNING instead\ndisplayed following NOTE., following line added R script.Next, devtools::document() run, adding following line \nNAMESPACE file.point rcmdcheck::rcmdcheck() return issue.","code":"Depends:\n SummarizedExperimentN checking dependencies in R code (7.9s)\n Package in Depends field not imported from: ‘SummarizedExperiment’\n These packages need to be imported from (in the NAMESPACE file)\n for when this namespace is loaded but not attached.#' @import SummarizedExperimentimport(SummarizedExperiment)"},{"path":"man-links.html","id":"what-did-not-work","chapter":"F Debug: Links in Rd files","heading":"F.3 What did not work","text":"Adding SummarizedExperiment package Imports: section \nDESCRIPTION file, adding @import statement documentation, \nrunning devtools::document().\npoint, rcmdcheck::rcmdcheck() continued display initial WARNING.","code":""},{"path":"man-links.html","id":"additional-resources-1","chapter":"F Debug: Links in Rd files","heading":"F.4 Additional resources","text":"Rd formatting","code":""},{"path":"booknews.html","id":"booknews","chapter":"G NEWS","heading":"G NEWS","text":"","code":""},{"path":"booknews.html","id":"version-1.0.1-2021-08-19","chapter":"G NEWS","heading":"G.1 Version 1.0.1 (2021-08-19)","text":"Add dedicated section package name.","code":""},{"path":"booknews.html","id":"version-1.0.0-2021-06-02","chapter":"G NEWS","heading":"G.2 Version 1.0.0 (2021-06-02)","text":"Initial definition package development guidelines based \nBioconductor package guidelines listed main Bioconductor.org website.","code":""}] +[{"path":"index.html","id":"welcome","chapter":"Welcome","heading":"Welcome","text":"","code":""},{"path":"index.html","id":"intro","chapter":"Welcome","heading":"Introduction","text":"Bioconductor project promotes high-quality, well documented, interoperable software.\nguidelines help achieve objective; meant put undue\nburden package authors, authors difficultly satisfying guidelines\nseek advice bioc-devel mailing list.Package maintainers urged follow guidelines closely possible\ndeveloping Bioconductor packages.General instructions producing R packages can found Writing R\nExtensions manual, available within \n(RShowDoc(\"R-exts\")) R website.Remember minimum requirements package acceptance \npackage still subject guidelines formal technical\nreview trained Bioconductor package reviewer .","code":""},{"path":"index.html","id":"contribute","chapter":"Welcome","heading":"Contribute","text":"book open-source hosted https://github.com/Bioconductor/pkgrevdocs.\nContributions welcome encouraged form forks pull requests.","code":""},{"path":"submission-overview.html","id":"submission-overview","chapter":"Overview","heading":"Overview","text":"following page gives overview submission process along key\nprinciples follow. See also Package Guidelines \npackage specific guidelines requirement \nBioconductor new package submission tracker.","code":""},{"path":"bioconductor-package-submissions.html","id":"bioconductor-package-submissions","chapter":"1 Bioconductor Package Submissions","heading":"1 Bioconductor Package Submissions","text":"IntroductionTypes PackagesPackage Naming PolicyAuthor/Maintainer ExpectationsSubmissionExperiment data packageAnnotation packageWorkflow packageReview ProcessFollowing AcceptanceAdditional Support","code":""},{"path":"bioconductor-package-submissions.html","id":"subintro","chapter":"1 Bioconductor Package Submissions","heading":"1.1 Introduction","text":"submit package Bioconductor package :Address areas high-throughput genomic analysis, e.g., sequencing,\nexpression microarrays, flow cytometry, mass spectrometry,\nimage analysis; see biocViews.Interoperate Bioconductor packages re-using common data\nstructures (see Common Bioconductor Methods Classes) \nexisting infrastructure (e.g., rtracklayer::import() input common\ngenomic files).Adopt software best practices enable reproducible research \nuse, full documentation vignettes (including fully\nevaluated code) well commitment long-term user support\nBioconductor support site.exist CRAN. package can submitted one .Comply Package Guidelines.package depend package (version package)\n(yet) available CRAN Bioconductor. package work\nwhatever current version package publically available.","code":""},{"path":"bioconductor-package-submissions.html","id":"type","chapter":"1 Bioconductor Package Submissions","heading":"1.2 Types of Packages","text":"Bioconductor packages broadly defined four main package types:\nSoftware, Experiment Data,\nAnnotation Workflow.Software Packages. packages contributed users software\npackages. Software packages provide implementation algorithms\n(e.g. statistical analysis), access resources (e.g. biomart, NCBI) \nvisualizations (e.g. volcano plots, pathways plots). Instructions creating\nSoftware packages can found : Package guidelines.Software Packages. packages contributed users software\npackages. Software packages provide implementation algorithms\n(e.g. statistical analysis), access resources (e.g. biomart, NCBI) \nvisualizations (e.g. volcano plots, pathways plots). Instructions creating\nSoftware packages can found : Package guidelines.Annotation packages database-like packages provide\ninformation linking identifiers (e.g., Entrez gene names Affymetrix\nprobe ids) information (e.g., chromosomal location, Gene\nOntology category). also encouraged utilize AnnotationHub \nstorage access large raw data files conversion \nstandard R formats. Instructions adding data AnnotationHub \ndesigning annotation package use AnnotationHub can found :\nCreate Hub Package.Annotation packages database-like packages provide\ninformation linking identifiers (e.g., Entrez gene names Affymetrix\nprobe ids) information (e.g., chromosomal location, Gene\nOntology category). also encouraged utilize AnnotationHub \nstorage access large raw data files conversion \nstandard R formats. Instructions adding data AnnotationHub \ndesigning annotation package use AnnotationHub can found :\nCreate Hub Package.Experiment data packages provide data sets used,\noften software packages, illustrate particular analyses. packages\ncontain curated data experiment, teaching course publication \ncases contain single data set. also encouraged utilize\nExperimentHub storage access larger data files. ExperimentHub \nalso particularly useful hosting collections related data sets.\nInstructions adding data ExperimentHub designing experiment data\npackage use ExperimentHub can found :\nCreate Hub Package.Experiment data packages provide data sets used,\noften software packages, illustrate particular analyses. packages\ncontain curated data experiment, teaching course publication \ncases contain single data set. also encouraged utilize\nExperimentHub storage access larger data files. ExperimentHub \nalso particularly useful hosting collections related data sets.\nInstructions adding data ExperimentHub designing experiment data\npackage use ExperimentHub can found :\nCreate Hub Package.Workflow packages contain vignettes describe \nbioinformatics workflow involves multiple Bioconductor packages. \nvignettes usually extensive vignettes accompany\nsoftware packages. packages need man/ R/ directories \ndata/ directory ideally workflows make use existing data \nBioconductor package. See development section Workflows \ndetails.Workflow packages contain vignettes describe \nbioinformatics workflow involves multiple Bioconductor packages. \nvignettes usually extensive vignettes accompany\nsoftware packages. packages need man/ R/ directories \ndata/ directory ideally workflows make use existing data \nBioconductor package. See development section Workflows \ndetails.See Package Guidelines details package format syntax.","code":""},{"path":"bioconductor-package-submissions.html","id":"naming","chapter":"1 Bioconductor Package Submissions","heading":"1.3 Package Naming Policy","text":"Package naming:Ownership package name. Bioconductor follows CRAN’s\npolicy requiring contributors give right use package name\nBioconductor time submission, Bioconductor team can orphan\npackage allow another maintainer take event \npackage contributor discontinues package maintenance. See Bioconductor’s package\nend--life policy details.Ownership package name. Bioconductor follows CRAN’s\npolicy requiring contributors give right use package name\nBioconductor time submission, Bioconductor team can orphan\npackage allow another maintainer take event \npackage contributor discontinues package maintenance. See Bioconductor’s package\nend--life policy details.Uniqueness package name. Packages named way \nconflict (irrespective case) current past BIOCONDUCTOR package,\ncurrent past CRAN package.Uniqueness package name. Packages named way \nconflict (irrespective case) current past BIOCONDUCTOR package,\ncurrent past CRAN package.See Package naming guidelines guidelines.","code":""},{"path":"bioconductor-package-submissions.html","id":"author","chapter":"1 Bioconductor Package Submissions","heading":"1.4 Author / Maintainer Expectations","text":"Acceptance packages Bioconductor brings ongoing\npackage maintenance responsibilities. Package authors expected :Follow Bioconductor guidelines\ninclude standard guidelines, version numbering,\ncoding style, code performance\nrequirements, memory usage, using\nexisting data classes, requirements described\n.Follow Bioconductor guidelinesThese include standard guidelines, version numbering,\ncoding style, code performance\nrequirements, memory usage, using\nexisting data classes, requirements described\n.Follow release cycle Bioconductor\ntwo releases year, around April October. \nrelease schedule indicate timetables \ndeadlines release. release cycle typically produces two\nversions packages, ‘devel’ ‘release’. important familiar\nbranch concepts. package accepted, \ninitially ‘devel’ branch. current devel branch becomes \nnext release. users expected use release branch, \nimmediately access package next release.\nBug fixes can fixed branches, new features \nadded ‘devel’ branch.Follow release cycle BioconductorThere two releases year, around April October. \nrelease schedule indicate timetables \ndeadlines release. release cycle typically produces two\nversions packages, ‘devel’ ‘release’. important familiar\nbranch concepts. package accepted, \ninitially ‘devel’ branch. current devel branch becomes \nnext release. users expected use release branch, \nimmediately access package next release.\nBug fixes can fixed branches, new features \nadded ‘devel’ branch.Maintain package using version control\nRealize Bioconductor, unlike CRAN, maintains package source code\ngit version control. means make changes \npackage using git. package accepted, receive\ninstructions typical git operations (see \nacceptance section). Package maintenance software\nrelease cycles, including prompt updates software documentation,\nneeded due possible underlying changes R /package\ndependencies.Maintain package using version controlRealize Bioconductor, unlike CRAN, maintains package source code\ngit version control. means make changes \npackage using git. package accepted, receive\ninstructions typical git operations (see \nacceptance section). Package maintenance software\nrelease cycles, including prompt updates software documentation,\nneeded due possible underlying changes R /package\ndependencies.Check Build Reports Fix Issues Promptly\nBioconductor weekly daily build reports package types. \nmaintainers responsibility check build reports respond \nERROR/Warning/Notes produced install, build, check process \npackage. maintainer receive automatic build notifications \npackage starts fail linux BBS-noreply@bioconductor.org;\nmaintainers check emails email address can delivered.Check Build Reports Fix Issues PromptlyBioconductor weekly daily build reports package types. \nmaintainers responsibility check build reports respond \nERROR/Warning/Notes produced install, build, check process \npackage. maintainer receive automatic build notifications \npackage starts fail linux BBS-noreply@bioconductor.org;\nmaintainers check emails email address can delivered.Subscribe bioc-devel mailing list\nBioconductor team communicates developers list.\nalso good channel communicate changes developers.\nAddressing Bioconductor team requests timely manner guarantees \npackage remains available Bioconductor.Subscribe bioc-devel mailing listThe Bioconductor team communicates developers list.\nalso good channel communicate changes developers.\nAddressing Bioconductor team requests timely manner guarantees \npackage remains available Bioconductor.Register use support site\nsupport site official support channel users. Users even\ndevelopers may ask questions regarding package platform.\nsure include packages maintain “Watched Tags”\nsection support site profile. notify questions\nposted regarding package(s).\nimportant promptly respond bug reports questions either \nBioconductor support site post directly developers.\nmaintainers prefer indicate BugReports: field package’s\nDESCRIPTION file. field indicates particular web page submitting\nbug reports questions.Register use support siteThe support site official support channel users. Users even\ndevelopers may ask questions regarding package platform.\nsure include packages maintain “Watched Tags”\nsection support site profile. notify questions\nposted regarding package(s).\nimportant promptly respond bug reports questions either \nBioconductor support site post directly developers.\nmaintainers prefer indicate BugReports: field package’s\nDESCRIPTION file. field indicates particular web page submitting\nbug reports questions.Ensure maintainer email DESCRIPTIONS stays accurate \nreachable. maintainer email DESCRIPTION definitive contact\nBioconductor use. important keep email --date \nensure can contact package failing notify \nimportant upcoming impactful events. email reachable \npackage jeopardy removal.Ensure maintainer email DESCRIPTIONS stays accurate \nreachable. maintainer email DESCRIPTION definitive contact\nBioconductor use. important keep email --date \nensure can contact package failing notify \nimportant upcoming impactful events. email reachable \npackage jeopardy removal.","code":""},{"path":"bioconductor-package-submissions.html","id":"submission","chapter":"1 Bioconductor Package Submissions","heading":"1.5 Submission","text":"Read follow full Contributor Guidelines section.Read follow full Contributor Guidelines section.Submit opening new issue Bioconductor\nContributions repository, following guidelines \nREADME.md file.\nAssuming package GitHub Repository \ndefault branch, add link repository \nissue opening. specify alternative branches; \ndefault branch utilized. default branch must contain package\ncode. files directories applications (Github Actions,\ndevtool, etc) different branch. submitting two\nhighly related packages circular dependent packages please see\n. lighter dependent package can installed without\ndependency submitted first; generally associated data\npackage software package.Submit opening new issue Bioconductor\nContributions repository, following guidelines \nREADME.md file.\nAssuming package GitHub Repository \ndefault branch, add link repository \nissue opening. specify alternative branches; \ndefault branch utilized. default branch must contain package\ncode. files directories applications (Github Actions,\ndevtool, etc) different branch. submitting two\nhighly related packages circular dependent packages please see\n. lighter dependent package can installed without\ndependency submitted first; generally associated data\npackage software package.","code":""},{"path":"bioconductor-package-submissions.html","id":"experPackage","chapter":"1 Bioconductor Package Submissions","heading":"1.6 Experiment Data Packages","text":"Experimental data packages contain data specific particular\nanalysis experiment. often accompany software package \nuse examples vignettes general updated\nregularly. need general subset data workflows \nexamples first check AnnotationHub resource available files\n(e.g., BAM, FASTA, BigWig, etc.) ExperimentHub available processed\nexample data set already included Bioconductor. current files data\nsets appropriate consider associated Experiment Data Package \nutilizes ExperimentHub.associated data package software package,\nplease create separate issue tracker repository\n. Instead, please add data package repository \nissue software package. process \ndocumented . Generally data package submitted first.HubPub package helpful creating template\nhub package. vignette Create Hub Package provides full details.","code":""},{"path":"bioconductor-package-submissions.html","id":"annPackage","chapter":"1 Bioconductor Package Submissions","heading":"1.7 Annotation Packages","text":"Annotation packages contain lightly non-curated data public\nsource updated Bioconductor release (every 6\nmonths). source general annotation one many\norganisms specific particular experiment. \npossible, support select() interface \nAnnotationDbi.Annotation packages posted tracker repository.\nInstead send email packages@bioconductor.org \ndescription proposed annotation package instructions\nsend package provided. Whenever possible Annotation\nPackages use AnnotationHub managing\nfiles.HubPub package helpful creating template\nhub package. vignette Create Hub Package provides full details.","code":""},{"path":"bioconductor-package-submissions.html","id":"workPackage","chapter":"1 Bioconductor Package Submissions","heading":"1.8 Workflow Packages","text":"Workflow packages contain vignettes describe bioinformatics workflow \ninvolves multiple Bioconductor packages. vignettes usually \nextensive vignettes accompany software packages. packages \nneed man/ R/ directories data/ directory ideally workflows make\nuse existing data Bioconductor package. See development section \nWorkflows details","code":""},{"path":"bioconductor-package-submissions.html","id":"whattoexpect","chapter":"1 Bioconductor Package Submissions","heading":"1.9 Review Process","text":"new package initially labeled 1. awaiting moderation.\nBioconductor team member take brief look \npackage, ensure anything malicious \ninappropriate. Packages pass stage labelled\npre-check passed.new package initially labeled 1. awaiting moderation.\nBioconductor team member take brief look \npackage, ensure anything malicious \ninappropriate. Packages pass stage labelled\npre-check passed.moderator add package repository \ngit.bioconductor.org git server, copy SSH keys github\naccount BiocCredentials application application issue labelled\npre-review.\nCHANGES PACKAGE must pushed \ngit.bioconductor.org repository created step. See New package\nworkflow instructions pushing changes git.bioconductor.org\nrepository.moderator add package repository \ngit.bioconductor.org git server, copy SSH keys github\naccount BiocCredentials application application issue labelled\npre-review.CHANGES PACKAGE must pushed \ngit.bioconductor.org repository created step. See New package\nworkflow instructions pushing changes git.bioconductor.org\nrepository.package submitted Bioconductor build\nsystem (BBS). system check package GitHub move \ngit.bioconductor.org git server. Please familiarize \ngit git.bioconductor.org versions (BBS) \nalways use. run R CMD build create ‘tarball’ source code,\nvignettes, man pages. run R CMD check tarball,\nensure package conforms standard R programming best\npractices. Bioconductor chosen utilize custom R CMD check\nenvironment; See R CMD check environment details. Finally, \nbuild system run BiocCheckGitClone() BiocCheck('new-package'=TRUE) ensure \npackage conforms Bioconductor BiocCheck\nstandards. system perform steps using ‘devel’\nversion Bioconductor, three platforms\n(Linux, Mac OS X, Windows). steps complete, link \nbuild report appended new package issue. Avoid surprises \nrunning checks computer, ‘devel’ version\nBioconductor, submitting package.package submitted Bioconductor build\nsystem (BBS). system check package GitHub move \ngit.bioconductor.org git server. Please familiarize \ngit git.bioconductor.org versions (BBS) \nalways use. run R CMD build create ‘tarball’ source code,\nvignettes, man pages. run R CMD check tarball,\nensure package conforms standard R programming best\npractices. Bioconductor chosen utilize custom R CMD check\nenvironment; See R CMD check environment details. Finally, \nbuild system run BiocCheckGitClone() BiocCheck('new-package'=TRUE) ensure \npackage conforms Bioconductor BiocCheck\nstandards. system perform steps using ‘devel’\nversion Bioconductor, three platforms\n(Linux, Mac OS X, Windows). steps complete, link \nbuild report appended new package issue. Avoid surprises \nrunning checks computer, ‘devel’ version\nBioconductor, submitting package.build report indicates problems, modify package \ncommit changes git.bioconductor.org version package \ndescribed new package git workflow. \nproblems understand, seek help \nbioc-devel mailing list.build report indicates problems, modify package \ncommit changes git.bioconductor.org version package \ndescribed new package git workflow. \nproblems understand, seek help \nbioc-devel mailing list.trigger new build, include version bump commit, e.g.,\nVersion: 0.99.0 Version: 0.99.1. Pre-release versions utilize \n0.99.z format. accepted released, package’s version number\nautomatically incremented 1.0.0.trigger new build, include version bump commit, e.g.,\nVersion: 0.99.0 Version: 0.99.1. Pre-release versions utilize \n0.99.z format. accepted released, package’s version number\nautomatically incremented 1.0.0.pre-review process identified larger issues \npackage, label 3e. pending pre-review changes specific flag \npackage issue assigned. Please address pre-review identified\nissues comment back package administrators re-evaluate.pre-review process identified larger issues \npackage, label 3e. pending pre-review changes specific flag \npackage issue assigned. Please address pre-review identified\nissues comment back package administrators re-evaluate.package builds checks without errors (avoidable)\nwarnings, package assigned reviewer. package \nlabelled 2. Review progress.package builds checks without errors (avoidable)\nwarnings, package assigned reviewer. package \nlabelled 2. Review progress.reviewer provide technical review package. \nBioconductor developers users domain expertise encouraged \nprovide additional community commentary. Reviewers add comments \nissue created.reviewer provide technical review package. \nBioconductor developers users domain expertise encouraged \nprovide additional community commentary. Reviewers add comments \nissue created.Please courteous package reviewers always follow \nBioconductor Code Conduct correspondence. Please allow 2-3 weeks\nreviewers assess package.Please courteous package reviewers always follow \nBioconductor Code Conduct correspondence. Please allow 2-3 weeks\nreviewers assess package.Respond issues raised reviewers. must respond \nprimary reviewer, strongly encouraged consider\ncommunity commentary. Typically response involve code\nmodifications; commit default branch git.bioconductor.org. \naddressed concerns, add comment issue created step 2\nexplain response.Respond issues raised reviewers. must respond \nprimary reviewer, strongly encouraged consider\ncommunity commentary. Typically response involve code\nmodifications; commit default branch git.bioconductor.org. \naddressed concerns, add comment issue created step 2\nexplain response.reviewer assess responses, perhaps suggesting \nmodifications clarification. reviewer accept \npackage inclusion Bioconductor, decline . label\n2. review progress replaced 3a. accepted \n3b. declined.reviewer assess responses, perhaps suggesting \nmodifications clarification. reviewer accept \npackage inclusion Bioconductor, decline . label\n2. review progress replaced 3a. accepted \n3b. declined.package accepted, added Bioconductor’s\nnightly ‘devel’ builds. packages ‘devel’ branch repository\n‘released’ user community every six months, \napproximately April October.package accepted, added Bioconductor’s\nnightly ‘devel’ builds. packages ‘devel’ branch repository\n‘released’ user community every six months, \napproximately April October.review process complete, issue created \nclosed. updates package \nBioconductor Git Server.review process complete, issue created \nclosed. updates package \nBioconductor Git Server.Please mindful reviewers volunteers package reviews \nresponsibility Bioconductor team members. like see \nreview process progress updates submitter comments \nreviewer within 2-3 weeks. entire review process typically takes 2\n6 weeks. response 3 4 weeks, package reviewers may\nclose issue updates, changes, /commentary received.","code":""},{"path":"bioconductor-package-submissions.html","id":"afteraccept","chapter":"1 Bioconductor Package Submissions","heading":"1.10 Following Acceptance","text":"Following acceptance package:Packages accepted tracker repository added ‘devel’\nbranch Bioconductor GIT repository, current version\nnumber accepted package.Packages built Bioconductor nightly build\nprocess. -demand builds accepted packages occur. Please see \nbuild reports often different package types built. \nchanges pushed ‘devel’ version package can take 24-28 hours \nappear. See build timings. build successful, package \n‘landing page’ created, package made available users\n‘devel’ branch Bioconductor via BiocManager::install().Changes package (), done version \nBioconductor git server.Developers bump z portion version number every\ntime commit changes package, following \nVersion numbering guidelines. developers don’t\nbump version, changes made package propagate\nBioconductor web site package repository.Devlopers make sure maintainer email DESCRIPTION stays\naccurate reachable.","code":""},{"path":"bioconductor-package-submissions.html","id":"support","chapter":"1 Bioconductor Package Submissions","heading":"1.11 Additional Support","text":"eager enhance quality interoperability \nBioconductor software provide additional support \nrequested package developers. Example areas assistance include\nuse appropriate S4 structures, specific guidance efficient\nimplementation, guidance code structure, critical assessment \npackage documentation structure. Use \nbioc-devel mailing list email\nmaintainer@bioconductor.org obtain additional support.Support Email: maintainer@bioconductor.org","code":""},{"path":"develop-overview.html","id":"develop-overview","chapter":"Overview","heading":"Overview","text":"following chapters go general package development guidelines \nexpected different parts \nBioconductor package.","code":""},{"path":"package-name.html","id":"package-name","chapter":"2 Package name","heading":"2 Package name","text":"package name match GitHub\nrepository name case-sensitive. package name descriptive \nalready exist current package (case-insensitive) \nBioconductor CRAN. Reusing\narchived deprecated package names also strongly discouraged often \nallowed. submission please inquire using legacy package\nname bioc-devel@r-project.org mailing list.easy way check whether name already use check \nfollowing command fails using ‘devel’ version Bioconductor:One also search Bioconductor browsable code\nbase search similar existing names \npackages, functions, classes.addition, avoid package names :easily confused existing package names, function names, class names.Imply temporal (e.g. ExistingPackage2) qualitative\n(e.g. ExistingPackagePlus) relationship.Suggest hate speech, slurs profanity, either implicitly explicitly.Invoke refer historical, ethical, political contexts.Reference well known people, characters, brands, places icons.Also, avoid unwanted meanings foreign languages, name checkers \nwordsafety might used proposed package name.Please consider name package carefully. Bioconductor discourage\nrenaming package acceptance. process renaming package \ndeprecate old named package re-submit newly named package \nreview tracker subject new review. timely process \nundertaken lightly.","code":"\nif (!require(\"BiocManager\")) {\n install.packages(\"BiocManager\")\n}\nBiocManager::install(\"MyPackage\")"},{"path":"general.html","id":"general","chapter":"3 General Bioconductor Package Development","heading":"3 General Bioconductor Package Development","text":"","code":""},{"path":"general.html","id":"version-of-bioconductor-and","chapter":"3 General Bioconductor Package Development","heading":"3.1 Version of Bioconductor and ","text":"Package developers always use devel version Bioconductor \nBioconductor packages developing testing packages contributed.Depending release cycle, using\nBioconductor devel may may involve also using devel version \n. See -using devel version \nBioconductor --date information.","code":""},{"path":"general.html","id":"correctness-space-and-time","chapter":"3 General Bioconductor Package Development","heading":"3.2 Correctness, Space and Time","text":"","code":""},{"path":"general.html","id":"r-cmd-build","chapter":"3 General Bioconductor Package Development","heading":"3.2.1 R CMD build","text":"Bioconductor packages must minimally pass R CMD build (R CMD INSTALL --build) pass R CMD check errors warnings using recent\nR-devel. Authors also try address errors, warnings, notes \narise build check.","code":""},{"path":"general.html","id":"bioccheck","chapter":"3 General Bioconductor Package Development","heading":"3.2.2 BiocCheck","text":"Packages must also pass BiocCheck::BiocCheckGitClone() \nBiocCheck::BiocCheck('new-package'=TRUE) errors warnings. \nBiocCheck package set tests encompass\nBioconductor Best Practices. Every effort made address \nerrors, warnings, notes arise build check.","code":""},{"path":"general.html","id":"error-warning-and-notes","chapter":"3 General Bioconductor Package Development","heading":"3.2.3 ERROR, WARNING, and NOTES","text":"Bioconductor team member assigned review\npackage submission process expect ERROR, WARNINGS, \nNOTES addressed R CMD build, R CMD check, BiocCheck. \nremaining, justification corrected \nexpected.","code":""},{"path":"general.html","id":"file-names","chapter":"3 General Bioconductor Package Development","heading":"3.2.4 File names","text":"use filenames differ case, file systems case-sensitive.","code":""},{"path":"general.html","id":"package-size","chapter":"3 General Bioconductor Package Development","heading":"3.2.5 Package size","text":"source package resulting running R CMD build occupy less 5 MB disk.\npackage includes (e.g. vignettes) screenshots, limit can reached quite quickly. size can reduced (often much 70%) lossy quality-preserving manner using tools pngquant (available command line utility GUI systems).","code":""},{"path":"general.html","id":"check-duration","chapter":"3 General Bioconductor Package Development","heading":"3.2.6 Check duration","text":"package require less 10 minutes run R CMD check ---build-vignettes.\nUsing ---build-vignettes option ensures vignette built .\n1","code":""},{"path":"general.html","id":"memory","chapter":"3 General Bioconductor Package Development","heading":"3.2.7 Memory","text":"Vignette man page examples use 3 GB memory since allocate 32-bit Windows.","code":""},{"path":"general.html","id":"individual-file-size","chapter":"3 General Bioconductor Package Development","heading":"3.2.8 Individual file size","text":"software packages, individual files must <= 5MB.\nrestriction exists even package accepted added \nBioconductor repository. See data section \nadvice packages using large data files.","code":""},{"path":"general.html","id":"undesirable-files","chapter":"3 General Bioconductor Package Development","heading":"3.2.9 Undesirable files","text":"raw package directory contain unnecessary files, system files, \nhidden files .DS_Store, .project, .git, cache files, log files,\n*.Rproj, *., etc. files may present local directory commited \ngit (see .gitignore). files directories \napplications (Github Actions, devtool, etc) ideally different\nbranch submitted Bioconductor version package.","code":""},{"path":"general.html","id":"r-cmd-check-environment","chapter":"3 General Bioconductor Package Development","heading":"3.3 R CMD check environment","text":"possible activate deactivate number options R CMD build R CMD check.\nOptions can set individual environment variables can listed file.\nDescriptions different options available can found .\nBioconductor chosen customize options incoming submission R CMD check.\nfile utilized flags can downloaded GitHub.\nfile can either placed default directory directed can set environment variable R_CHECK_ENVIRON command similar :","code":"export R_CHECK_ENVIRON = "},{"path":"important-bioconductor-package-development-features.html","id":"important-bioconductor-package-development-features","chapter":"4 Important Bioconductor Package Development Features","heading":"4 Important Bioconductor Package Development Features","text":"","code":""},{"path":"important-bioconductor-package-development-features.html","id":"biocviews","chapter":"4 Important Bioconductor Package Development Features","heading":"4.1 biocViews","text":"Packages added Bioconductor Project require biocViews:\nfield DESCRIPTION file. field name “biocViews” \ncase-sensitive must begin lower-case ‘b’.biocViews terms “keywords” used describe given package. \nbroadly divided four categories, representing type \npackages present Bioconductor ProjectSoftwareAnnotation DataExperiment DataWorkflowbiocViews available release devel branches \nBioconductor. devel branch check box tree\nstructure , checked, displays biocViews defined \nused package, addition biocViews use. See also\ndescription section","code":""},{"path":"important-bioconductor-package-development-features.html","id":"biocviews-motivation","chapter":"4 Important Bioconductor Package Development Features","heading":"4.1.1 Motivation","text":"One can use biocViews two broad purposes.researcher might want identify packages \nBioconductor Project related specific purpose.\nexample, one may want look packages related “Copy\nNumber Variants”.researcher might want identify packages \nBioconductor Project related specific purpose.\nexample, one may want look packages related “Copy\nNumber Variants”.development, package contributor can “tag” package\nbiocViews someone looking packages (like \nscenario 1) can easily find package.development, package contributor can “tag” package\nbiocViews someone looking packages (like \nscenario 1) can easily find package.","code":""},{"path":"important-bioconductor-package-development-features.html","id":"biocviews-pkg-devel","chapter":"4 Important Bioconductor Package Development Features","heading":"4.1.2 biocViews during new package development","text":"Visit ‘devel’ biocViews process \nadding biocViews new package. Identify many terms \nappropriate hierarchy. Prefer ‘leaf’ terms end \nhierarchy, inclusive terms. Remember check box\ndisplaying available terms.Please Note:package belong one part Bioconductor Project\n(Software, Annotation Data, Experiment Data, Workflow), choose \nbiocViews category.package belong one part Bioconductor Project\n(Software, Annotation Data, Experiment Data, Workflow), choose \nbiocViews category.biocViews listed package must match exactly (e.g.,\nspelling, capitalization) terms biocViews hierarchy.biocViews listed package must match exactly (e.g.,\nspelling, capitalization) terms biocViews hierarchy.submit new package review , package checked\nbuilt Bioconductor Project. check following \nbiocViews:Package contributor added biocViews.Package contributor added biocViews.biocViews valid.biocViews valid.Package contributor added biocViews one categories.Package contributor added biocViews one categories.receive “RECOMMENDED” direction biocViews\nsubmitted package, can try correcting \nfollowing directions given ask package\nreviewer information.developer thinks biocViews term added current acceptable\nlist, please email bioc-devel@r-project.org requesting new biocView, \nhierarchy term placed, justification new\nterm.","code":""},{"path":"important-bioconductor-package-development-features.html","id":"reusebioc","chapter":"4 Important Bioconductor Package Development Features","heading":"4.2 Common Bioconductor Methods and Classes","text":"strongly recommend reusing existing methods importing data, \nreusing established classes representing data. \nsuggestions importing different file types commonly used\nBioconductor classes. classes functionality also try\nsearching biocViews data type.","code":""},{"path":"important-bioconductor-package-development-features.html","id":"commonimport","chapter":"4 Important Bioconductor Package Development Features","heading":"4.2.1 Importing data","text":"GTF, GFF, BED, BigWig, etc., – rtracklayer ::import()VCF – VariantAnnotation ::readVcf()SAM / BAM – Rsamtools ::scanBam(),\nGenomicAlignments ::readGAlignment*()FASTA – Biostrings ::readDNAStringSet()FASTQ – ShortRead ::readFastq()MS data (XML-based mgf formats) – Spectra ::Spectra(),\nSpectra ::Spectra(source = MsBackendMgf::MsBackendMgf())","code":""},{"path":"important-bioconductor-package-development-features.html","id":"commonclass","chapter":"4 Important Bioconductor Package Development Features","heading":"4.2.2 Common Classes","text":"Rectangular feature x sample data –\nSummarizedExperiment ::SummarizedExperiment()\n(RNAseq count matrix, microarray, …)Genomic coordinates – GenomicRanges ::GRanges()\n(1-based, closed interval)Genomic coordinates multiple samples –\nGenomicRanges ::GRangesList()Ragged genomic coordinates – RaggedExperiment\n::RaggedExperiment()DNA / RNA / AA sequences – Biostrings\n::*StringSet()Gene sets – BiocSet ::BiocSet(),\nGSEABase ::GeneSet(),\nGSEABase ::GeneSetCollection()Multi-omics data –\nMultiAssayExperiment ::MultiAssayExperiment()Single cell data –\nSingleCellExperiment ::SingleCellExperiment()Mass spec data – Spectra ::Spectra()File formats – BiocIO ::`BiocFile-class`general, package accepted show interoperability\ncurrent Bioconductor ecosystem.","code":""},{"path":"important-bioconductor-package-development-features.html","id":"bioc-vignette","chapter":"4 Important Bioconductor Package Development Features","heading":"4.3 Vignette","text":"Every submitted Bioconductor package least one Rmd (preferred) \nRnw vignette, ideally utilizing BiocStyle::html_document output\nrendering. include evaluated R package code detailed\nintroduction/abstract section provides motivation inclusion \nBioconductor appropriate review comparison existing\nBioconductor packages similar functionality scope. See vignette\ndocumentation section details.","code":""},{"path":"readme.html","id":"readme","chapter":"5 The README file","heading":"5 The README file","text":"README files required Bioconductor packages.README file included package Github repository provides installation instructions,\ninstruction also include\nBioconductor installation instructions. See\nBioconductor package installation instructions current Bioconductor\npackage landing page (e.g. GenomicRanges).README.Rmd provided (rather README.md, ) \ninstallation instructions eval=FALSE code chunk.Nowhere code ( code, man pages,\nvignettes, Rmd files) someone try install download system\ndependencies, applications, packages, etc.Developers can provide instructions follow executed assume\nnecessary dependencies, applications, packages already set \nuser’s system. See also INSTALL file system dependencies\nrequirements.","code":""},{"path":"description.html","id":"description","chapter":"6 The DESCRIPTION file","heading":"6 The DESCRIPTION file","text":"DESCRIPTION file must properly formatted.\nfollowing sections review important notes regarding fields \nDESCRIPTION file associated files.","code":""},{"path":"description.html","id":"description-pkg","chapter":"6 The DESCRIPTION file","heading":"6.1 Package","text":"name package. repository name name Package\ndescription match (including case-sensitive).","code":""},{"path":"description.html","id":"description-title","chapter":"6 The DESCRIPTION file","heading":"6.2 Title","text":"brief descriptive title package.","code":""},{"path":"description.html","id":"description-ver","chapter":"6 The DESCRIPTION file","heading":"6.3 Version","text":"Bioconductor packages use x.y.z version scheme.\nSee Version Numbering specifics release\ndevel Bioconductor versioning proceeds. \nfirst submitted Bioconductor, package pre-release version\n0.99.0.following rules apply:x usually 0 packages yet released.y even packages release, odd packages devel.\nGenerally, bump number especially pre-release.z incremented whenever committing changes package.","code":""},{"path":"description.html","id":"description-description","chapter":"6 The DESCRIPTION file","heading":"6.4 Description","text":"description relatively short detailed overview \npackage functionality entails. least three complete sentences.","code":""},{"path":"description.html","id":"description-authors","chapter":"6 The DESCRIPTION file","heading":"6.5 Authors@R","text":"Authors@R field used.\nmaintainer designation (cre Authors@R) required actively\nmaintained email address. email address used contact\nregarding issues arise package future.persons ORCiD identifier provide \nidentifier via element named “ORCID” comment argument person().one person listed Maintainer ensure single point\ncontact. person default commit access git\nrepository git.bioconductor.org. Commit access can given \ndevelopers request bioc-devel mailing list.Another option add collaborators \nGitHub repository. approach enables development many restricts\npush access git.bioconductor.org.","code":"\nperson(\"Lori\", \"Shepherd\",\n email = Lori.Shepherd@roswellpark.org,\n role = c(\"cre\", \"aut\"),\n comment = c(ORCID = \"0000-0002-5910-4010\"))"},{"path":"description.html","id":"description-license","chapter":"6 The DESCRIPTION file","heading":"6.6 License","text":"license field preferably refer standard license (see\nwikipedia) using one ’s\nstandard specifications. ships \nfollowing standard licensesBe specific version applies (e.g., GPL-2).\nLicenses restricting use, e.g., academic non-profit researchers, \nsuitable Bioconductor. Core Bioconductor packages typically\nlicensed Artistic-2.0.specify non-standard license, include file named LICENSE \npackage (containing full terms license) use string file LICENSE License: field.package contain code can redistributed according \npackage license. aware licensing agreements packages \ndepending package. packages open source even \npublicly available.","code":""},{"path":"description.html","id":"description-lazydata","chapter":"6 The DESCRIPTION file","heading":"6.7 LazyData","text":"packages include data, recommend including LazyData: TRUE.\nexperience slows loading packages large\ndata. course exceptions; please provide reasoning included.","code":""},{"path":"description.html","id":"depends-imports-suggests-enhances","chapter":"6 The DESCRIPTION file","heading":"6.8 Depends, Imports, Suggests, Enhances","text":"packages must available via Bioconductor’s biocViews \nCRAN; use Remotes: field supported, hence dependencies \navailable repositories (e.g.  GitHub) \nallowed specify explicit version package.Reuse, rather re-implement duplicate, well-tested functionality \npackages. Make use appropriate existing packages (e.g.,\nbiomaRt,\nAnnotationDbi,\nBiostrings, etc.) classes (e.g.,\nSummarizedExperiment,\nGenomicRanges::GRanges,\nS4Vectors::Rle,\nBiostrings::DNAStringSet, etc.), \navoid duplication functionality available Bioconductor packages.\nSee Common Bioconductor Methods Classes.\nBioconductor reviewers strict point! New packages \ninteroperable existing Bioconductor classes reimplement\nfunctionality especially regards importing/reading data.package can listed Depends:, Imports:, Suggests:,\nEnhances:. Determine placement package based following\nguidelines:Imports: packages provide functions, methods, classes \nused inside package name space. packages listed .Imports: packages provide functions, methods, classes \nused inside package name space. packages listed .Depends: packages provide essential functionality users \npackage, e.g., GenomicRanges package listed Depends:\nfield GenomicAlignments.\nunusual three packages listed Depends:.Depends: packages provide essential functionality users \npackage, e.g., GenomicRanges package listed Depends:\nfield GenomicAlignments.\nunusual three packages listed Depends:.Suggests: packages used vignettes, examples, conditional\ncode.Commonly, annotation experiment packages (e.g., TxDb*) used \nvignette example code included field thus avoiding costly\ndownload. case external one-function required \npackage code, package availability usage can done via:\n(!requireNamespace('suggPKG', quietly = TRUE))\n stop(\"Install 'suggPKG' use function.\")\nsuggPKG::function()Suggests: packages used vignettes, examples, conditional\ncode.Commonly, annotation experiment packages (e.g., TxDb*) used \nvignette example code included field thus avoiding costly\ndownload. case external one-function required \npackage code, package availability usage can done via:Enhances: packages Rmpi parallel enhance \nperformance package, strictly needed \nfunctionality.Enhances: packages Rmpi parallel enhance \nperformance package, strictly needed \nfunctionality.seldom necessary specify specific\nversions dependencies, since Bioconductor release strategy \nstandard installation instructions guarantee constraints. Repositories\nmirrored outside Bioconductor include branches \nBioconductor release, may find useful fully specify versions \nenforce constraints otherwise guaranteed Bioconductor installation\npractices.additional information regarding Depends, Imports, Suggest \npackage placed see Connecting \npackages package\ndependency\nsection Writing R Extensions.","code":"if (!requireNamespace('suggPKG', quietly = TRUE))\n stop(\"Install 'suggPKG' to use this function.\")\nsuggPKG::function()"},{"path":"description.html","id":"description-sysdep","chapter":"6 The DESCRIPTION file","heading":"6.9 SystemRequirements","text":"field listing external software required, \nautomatically installed normal package installation process.installation process non-trivial, top-level INSTALL file \nincluded document process. user facing README included \nalso recommended document process ; try install \ndependency user anywhere package (.e. readme, r code, man pages,\nvignette). may show instructions unevaluated sections. See also\nAdditional files dependencies","code":""},{"path":"description.html","id":"description-biocviews","chapter":"6 The DESCRIPTION file","heading":"6.10 biocViews","text":"field required!Specify least two leaf node biocViews.\nMultiple leaf terms encouraged terms must come trunk \npackage type (.e., Software, AnnotationData, ExperimentData, \nWorkflow). biocViews terms case-sensitive.field name “biocViews” case-sensitive must begin lower-case\n‘b’. Please use single line biocViews seperated commas(.e,biocViews: GeneTarget, SingleCell).","code":""},{"path":"description.html","id":"description-bugreport","chapter":"6 The DESCRIPTION file","heading":"6.11 BugReports","text":"encouraged include relevant links \nGitHub reporting issues.","code":""},{"path":"description.html","id":"description-url","chapter":"6 The DESCRIPTION file","heading":"6.12 URL","text":"field directs users source code repositories, additional help\nresources, etc; details provided Writing R Extensions\nmanual, RShowDoc(\"R-exts\").","code":""},{"path":"description.html","id":"description-video","chapter":"6 The DESCRIPTION file","heading":"6.13 Video","text":"field displays links instructional videos.","code":""},{"path":"description.html","id":"description-collate","chapter":"6 The DESCRIPTION file","heading":"6.14 Collate","text":"may necessary order class method definitions appropriately\npackage installation.","code":""},{"path":"description.html","id":"description-bioctype","chapter":"6 The DESCRIPTION file","heading":"6.15 BiocType","text":"required submitting Docker Workflow.\nOtherwise field optionally define type Bioconductor package\nSoftware, ExperimentData, Annotation.","code":""},{"path":"namespace.html","id":"namespace","chapter":"7 The NAMESPACE file","heading":"7 The NAMESPACE file","text":"NAMESPACE file defines functions, classes, methods imported namespace, exported users.following section describe Bioconductor reviewers looking file.","code":""},{"path":"namespace.html","id":"function-names","chapter":"7 The NAMESPACE file","heading":"7.1 Function names","text":"Exported functions use camel case underscoring include .,\nindicates S3 dispatch. Functions starting . exported\nindicates internal function.","code":""},{"path":"namespace.html","id":"imported-functions","chapter":"7 The NAMESPACE file","heading":"7.2 Imported functions","text":"Generally importFrom() encouraged importing entire package.\nHowever, many functions single package, import() can \nacceptable. particular Bioconductor class used extended \nhighly recommended import() full package full class\nfunctionality inherited automatically; exceptions depending \nimplementation necessity.","code":""},{"path":"namespace.html","id":"exported-functions","chapter":"7 The NAMESPACE file","heading":"7.3 Exported functions","text":"Exporting functions exportPattern(\"^[[:alpha:]]+\") strongly\ndiscouraged almost always allowed. Functions generics \nexported individually, clarity control.","code":""},{"path":"news.html","id":"news","chapter":"8 The NEWS file","heading":"8 The NEWS file","text":"NEWS file informs user changes software may impact user\nexpectations. highly recommended developer use plain \nconcise language communicate changes.NEWS file keep track changes, non-technical language, \ncode one release version next. file can reside either\npackage’s top level directory inst/ directory. \none NEWS file per package.following acceptable locations formats:Specifics formatting can found help page ?news.\nBioconductor compiles NEWS files updated packages create\nsemi-annual release announcement.\nNEWS files must include list elements plain text files.version 1.24.0 NEWS file SummarizedExperiment:Note version documented forthcoming release version \npackage. developer, NEWS file running log \nchanges lead next release package.user can read release notes SummarizedExperiment version\n1.24.0 running following:development package re-installation, NEWS file’s\nformatting can checked :function fail directly show output similar \none formatting errors need corrected.\nNote bullet points embedded within first Text field:","code":"CHANGES IN VERSION 1.24.0\n-------------------------\n\nNEW FEATURES\n\n o Add 'checkDimnames' argument to SummarizedExperiment() constructor\n function\n\n o Add showAsCell() method for SummarizedExperiment objects.\n\nSIGNIFICANT USER-VISIBLE CHANGES\n\n o Check the assay dimnames at SummarizedExperiment construction time:\n The SummarizedExperiment() constructor function now raises an error\n if one of the supplied assays has rownames and/or colnames that don't\n match those of the SummarizedExperiment object to construct.\n\nutils::news(package = \"SummarizedExperiment\", Version == \"1.24.0\")\nutils::news(package=\"\")Version: 1.2.0\nDate: 2018-07-15\nText: Made the following significant changes o added a subsetting\n method o added a new field to database\n\nVersion: 1.0.0\nDate: 2018-06-15\nText: Fixed bug. Begin indexing from 1 instead of 2\n\nVersion: 0.99.0\nDate: 2018-05-15\nText: Submitted to Bioconductor"},{"path":"license.html","id":"license","chapter":"9 The LICENSE file","heading":"9 The LICENSE file","text":"license field preferably refer standard license (see\nwikipedia)\nusing one ’s standard specifications.Licenses restricting use, e.g., academic non-profit researchers, \nsuitable Bioconductor. Core Bioconductor packages typically\nlicensed Artistic-2.0.specify non-standard license, include LICENSE file \npackage (containing full terms license) use string file LICENSE License: field. LICENSE file provided match \nLicense field Description fileThe package contain code can redistributed according \npackage license. aware licensing agreements packages \ndepending package. packages open source even \npublicly available.","code":""},{"path":"citation.html","id":"citation","chapter":"10 The CITATION file","heading":"10 The CITATION file","text":"Appropriate citations must included help pages (e.g., see also\nsection) vignettes; aspect documentation different \nscientific endeavor. file inst/CITATION can used specify \npackage cited. option utilized, maintainer can check\nproper formatting CITATION file running\nreadCitationFile(\"inst/CITATION\") WITHOUT package loaded \nlibrary call; must run without error citation accurately\ndisplayed package landing page.Whether CITATION file present, automatically-generated citation\nappear package landing page Bioconductor web site. \noptimal formatting author names (CITATION file present),\nspecify package author maintainer using Authors@R field \ndescribed Writing R Extensions manual.","code":""},{"path":"sysdep.html","id":"sysdep","chapter":"11 The INSTALL file","heading":"11 The INSTALL file","text":"INSTALL file included package. INSTALL file\nutilized specifying external system requirements needed. \nused combination SystemRequirements field Description\nfile. file provide instructions installing\nexternal software 3 major OS support: Linux, Windows, \nMac. help users get external software \nmachines, also help us install build machines ’s \nalready .Specifying requirement guarantee Bioconductor agree \ninstall external system requirement. encouraged discuss \nadditional system requirements bioc-devel@r-project.org \ndevelopment.System requirements never exclusive particular\nversion. Maintainers expected package work whatever \ncurrent version external software available.See also third party code","code":""},{"path":"docs.html","id":"docs","chapter":"12 Documentation","heading":"12 Documentation","text":"Package documentation important users understand work code.","code":""},{"path":"docs.html","id":"doc-require","chapter":"12 Documentation","heading":"12.1 Bioconductor documentation minimal requirements:","text":"vignette Rmd Rnw format executable code \ndemonstrates use package accomplish task,vignette Rmd Rnw format executable code \ndemonstrates use package accomplish task,man pages exported functions runnable examples, well\ndocumented data structures especially pre-exiting\nclassman pages exported functions runnable examples, well\ndocumented data structures especially pre-exiting\nclasswell documented datasets data provided data/ inst/extdata/.well documented datasets data provided data/ inst/extdata/.References methods used well similar related projects\npackages also expected.data structures differ similar packages, Bioconductor\nreviewers expect justification . Keep mind\nalways possible extend existing classes.","code":""},{"path":"docs.html","id":"vignettes","chapter":"12 Documentation","heading":"12.2 Vignettes","text":"vignette demonstrates accomplish non-trivial tasks embodying core\nfunctionality package. two common types vignettes.(Recommended) R markdown vignette similar Sweave vignette, uses\nmarkdown instead \\(\\LaTeX\\)\nstructuring text sections resulting HTML output. r BiocStyle::CRANpkg(\"knitr\") package can process Sweave R\nmarkdown vignettes, producing pleasing output. Refer Writing package\nvignettes technical details. See r BiocStyle::Biocpkg(\"BiocStyle\") package convenient way use common\nmacros standard Bioconductor style vignette.(Recommended) R markdown vignette similar Sweave vignette, uses\nmarkdown instead \\(\\LaTeX\\)\nstructuring text sections resulting HTML output. r BiocStyle::CRANpkg(\"knitr\") package can process Sweave R\nmarkdown vignettes, producing pleasing output. Refer Writing package\nvignettes technical details. See r BiocStyle::Biocpkg(\"BiocStyle\") package convenient way use common\nmacros standard Bioconductor style vignette.Sweave vignette .Rnw file contains \\(\\LaTeX\\) chunks code. code chunk starts line\n<<>>=, ends @. chunk evaluated R CMD build,\nprior \\(\\LaTeX\\) compilation PDF document.Sweave vignette .Rnw file contains \\(\\LaTeX\\) chunks code. code chunk starts line\n<<>>=, ends @. chunk evaluated R CMD build,\nprior \\(\\LaTeX\\) compilation PDF document.vignette provides reproducibility: vignette produces results \ncopying corresponding commands \nsession. therefore essential vignette embed executed code. Shortcuts (e.g., using \\(\\LaTeX\\) verbatim\nenvironment, using Sweave eval=FALSE flag, equivalent tricks \nmarkdown) undermine benefit vignettes generally allowed;\nexceptions can made proper justification discretion \nBioconductor reviewers.packages required least one Rmd Rnw vignette. Vignettes go\nvignettes/ directory package. Vignettes often used \nstandalone documents, best practices include informative title, \nprimary author vignette, last modification date vignette, \nlink package landing page. encourage use r BiocStyle::Biocpkg(\"BiocStyle\") formatting html_document \nrendering target. Something like following vignette accomplish\nsuggestion:want write one vignette, may want control\norder displayed package homepage \nbrowseVignettes() function called. Vignettes show \nalphabetical order, may logical ordering without\nspecification. One approach controlling order \nvignettes use number VignettteIndexEntry setting,\ne.g. using numbers 1-9, single digit number \nvignettes, 01-99 ten vignettes. example,\nfirst vignette specify header:best practices requirements writing Bioconductor vignettes \ndetailed following sections.","code":"output:\n BiocStyle::html_document:\n toc: true\n toc_depth: 2\nvignette: >\n %\\VignetteEngine{knitr::rmarkdown}\n %\\VignetteIndexEntry{1. Quick start to MyPackage}\n %\\VignetteEncoding{UTF-8}"},{"path":"docs.html","id":"vignette-introduction","chapter":"12 Documentation","heading":"12.2.1 Introduction","text":"Add “Introduction” section serves abstract introduce \nobjective, models, unique functions, key points, etc distinguish \npackage packages area. requirement \nBioconductor package vignettes. include short motivation \npackage general well motivation inclusion package \nBiconductor. relevant, brief review comparison packages \nsimilar functionality scope provided either Introduction \nseparate dedicated vignette section.","code":""},{"path":"docs.html","id":"installation","chapter":"12 Documentation","heading":"12.2.2 Installation","text":"Add “Installation” section show users download load \npackage Bioconductor.instructions installations instructions \neval=FALSE code chunk. code (\ncode, man pages, vignettes, Rmd files) someone try install download\nsystem dependencies, applications, packages, etc. Developers can provide\ninstructions follow unevaluated code chunks, assume \nnecessary dependencies, applications packages already set user’s\nsystem.","code":""},{"path":"docs.html","id":"table-of-contents","chapter":"12 Documentation","heading":"12.2.3 Table of contents","text":"appropriate, strongly encourage table contents","code":""},{"path":"docs.html","id":"evaluated-code-chunks","chapter":"12 Documentation","heading":"12.2.4 Evaluated code chunks","text":"Non-trivial executable code must!!!Static vignettes acceptable.","code":""},{"path":"docs.html","id":"session-information","chapter":"12 Documentation","heading":"12.2.5 Session information","text":"Include section SessionInfo() end vignette.","code":""},{"path":"docs.html","id":"vignettes-directory-and-intermediate-files","chapter":"12 Documentation","heading":"12.2.6 vignettes/ directory and intermediate files","text":"source vignette file (.Rnw .Rmd) necessary static images\nvignette directory. intermediate files \npresent. include complete processed vignette products well; vignette\ncreated R CMD build package. include types\ndocumentation please use inst/doc appropriately named inst\ndirectory.","code":""},{"path":"docs.html","id":"references","chapter":"12 Documentation","heading":"12.2.7 References","text":"Remember include relevant references methods.","code":""},{"path":"docs.html","id":"man-pages","chapter":"12 Documentation","heading":"12.3 Man pages","text":"See Writing R Extensions section man pages detailed\ninstruction format information documenting package, functions, classes,\ndata sets.help pages comprehensive.","code":""},{"path":"docs.html","id":"package-level-documentation","chapter":"12 Documentation","heading":"12.3.1 Package-level documentation","text":"Bioconductor encourages package man page overview \npackage links main functions. Users able relevant\npage display ?","code":""},{"path":"docs.html","id":"functions-and-classes","chapter":"12 Documentation","heading":"12.3.2 Functions and classes","text":"exported functions classes need man page. Man pages\ndescribing new classes must detailed structure type \ninformation stored.","code":""},{"path":"docs.html","id":"data-man","chapter":"12 Documentation","heading":"12.3.3 Data","text":"Data man pages must include provenance information data structure information.","code":""},{"path":"docs.html","id":"examples","chapter":"12 Documentation","heading":"12.3.4 Examples","text":"man pages runnable examples.use donttest dontrun discouraged generally allowed;\nexceptions can made proper justification discretion \nBioconductor reviewers.option used also preferable use donttest instead \ndontrun; donttest requires valid code \ndontrun .","code":""},{"path":"docs.html","id":"doc-inst-script","chapter":"12 Documentation","heading":"12.4 The inst/script/ directory","text":"scripts directory can vary.importantly data included inst/extdata/ directory, \nrelated script must present directory documenting clearly \ndata generated source information.include source URLs key information regarding filtering processing.can executable code, sudo code, text description.Users able download able roughly reproduce file \nobject present data.","code":""},{"path":"docs.html","id":"other-doc","chapter":"12 Documentation","heading":"12.5 Other","text":"types documentation (e.g. static files, jupyter notebooks, etc.) can \nprovided inst subdirectories substitute \nBioconductor documentation requirements listed .","code":""},{"path":"data.html","id":"data","chapter":"13 Package data","heading":"13 Package data","text":"developing software package, excellent practice give \ncomprehensive illustration methods package using existing\nexperiment data package, annotation data\ndata ExperimentHub AnnotationHub,\nsubmitting new data resources .existing data available applicable, new smaller dataset \nneeded examples package, data can included either separate\ndata package (larger amounts data) within package (smaller\ndatasets).Bioconductor Build system support git-lfs. current\noption storing large data. Large data sets must included \nExperimentHub. See additional information Create \nHub Package.","code":""},{"path":"data.html","id":"experiment-data-package","chapter":"13 Package data","heading":"13.1 Experiment Data Package","text":"Experimental data packages contain data specific particular analysis \nexperiment. often accompany software package use examples \nvignettes general updated regularly. need general subset\ndata workflows examples first check AnnotationHub\nresource available files (e.g., BAM, FASTA, BigWig, etc.) \nExperimentHub processed predefined\nBioconductor class structures.Bioconductor strongly encourages creating experiment data package \nutilizes ExperimentHub AnnotationHub\n(See Create Hub Package) traditional package encapsulates \ndata also acceptable pre-approval bioc-devel\nmailing list.See Package Submission guidelines \nsubmission procedures submitting related circular dependent\npackages please read related package submission procedure","code":""},{"path":"data.html","id":"adding-data-to-existing-package","chapter":"13 Package data","heading":"13.2 Adding Data to Existing Package","text":"Bioconductor strongly encourages use existing datasets, \navailable data can included directly package use examples\nfound man pages, vignettes, tests package. good\nreference Hadley Wickham package data.However, mentioned DESCRIPTION file chapter,\nBioconductor encourage using LazyData: True despite \nrecommendation article.Note. might modify usage section @usage data(\"mydata\")key points summarized following sections.","code":""},{"path":"data.html","id":"exported-data-and-the-data-directory","chapter":"13 Package data","heading":"13.2.1 Exported Data and the data/ directory","text":"Data data/ exported user readily available.\nmade available session use data().\nrequire documentation concerning creation source information.\noften .RData file created save() types acceptable well, see ?data().Please remember compress data.packages need use documented data within function, recommend\ncreating environment holding data avoid polluting \nglobal environment using data().create new empty environment. Extract data within \nenvironment finally extract data object environment using\ndouble brackets.","code":"\ndata_env <- new.env(parent = emptyenv())\ndata(\"mydata\", envir = data_env, package = \"mypackage\")\nmydata <- data_env[[\"mydata\"]]"},{"path":"data.html","id":"raw-data-and-the-instextdata-directory","chapter":"13 Package data","heading":"13.2.2 Raw Data and the inst/extdata/ directory","text":"often desirable show workflow involves parsing loading raw files.\nBioconductor recommends finding existing raw data already provided \nanother package hubs previously stated.However, applicable, raw data files included \ninst/extdata directory. Files type often accessed utilizing\nsystem.file(). Bioconductor requires documentation files \ninst/script/ directory. See data documentation.","code":""},{"path":"data.html","id":"internal-data","chapter":"13 Package data","heading":"13.2.3 Internal data","text":"Rarely, package may require parsed data used internal \nexported user. R/sysdata.rda often best place include\ntype data. Proper documentation data required.","code":""},{"path":"data.html","id":"other-data","chapter":"13 Package data","heading":"13.2.4 Other data","text":"Downloads files external data web avoided.necessary, minimum files cached.\nSee BiocFileCache Bioconductor recommended package\ncaching files. maintainer creates caching directory, \nutilize standard caching directories tools::R_user_dir(package, =\"cache\"). allowed download write files users\nhome directory, working directory, installed package directory. Files \ncached stated BiocFileCache (preferred) R_user_dir \ntempdir()/tempfile() files persistent. Please also see\nsections querying web resources file\ndownloads.","code":""},{"path":"tests.html","id":"tests","chapter":"14 Unit tests","heading":"14 Unit tests","text":"Unit tests simple write, easily invoked, confer large\nbenefits throughout software development process, early stage\nexploratory code, late stage maintenance long-established\nproject. Unit testing often becomes indispensable give\ntry. explain write unit tests, run ,\nwoven standard Bioconductor build process.\nhope unit tests become standard part software\ndevelopment, integral part Bioconductor package.recommend either RUnit, tinytest, testthat packages \nCRAN write unit tests. RUnit R implementation agile\nsoftware development ‘XUnit’ tools (see also JUnit, PyUnit) \ntries encourage, respective language, rapid development \nrobust useful software. tinytest lightweight (zero-dependency) \neasy--use unit testing framework. testthat also draws inspiration \n‘XUnit’ family testing packages, well many innovative ruby\ntesting libraries, like rspec, testy, bacon cucumber.","code":""},{"path":"tests.html","id":"tests-motivation","chapter":"14 Unit tests","heading":"14.1 Motivation","text":"bother unit testing?Imagine need function divideBy taking two arguments,\nmight define like :develop function likely test \nvariety ways, using different arguments, checking results,\neventually satisfied performs properly. Unless\nadopt sort software testing protocol, however, tests\nunlikely become integral part code. may \nscattered across different files, may exist re-runnable\ncode file , just ad hoc command-line function calls \nsometimes remember make.far better approach, propose, use lightweight,\nformalized unit testing. requires conventions\npractices:Store test functions standard directory.Use simple functions RUnit, tinytest, testthat packages \ncheck results.Run tests routine part development process.RUnit test divideBy:equivalent test using tinytest:equivalent test using testthat:Adopting practices cost little. developers\nfind practices simplify shorten development time. \naddition, create executable contract — concise \nverifiable description code supposed . \nexperienced unit-testing programmer create test function\naccompany every function, method class write. (don’t\nlet scare . Even adding single test package \nworthwhile, reasons explained .)Developers often rebel unit tests recommended ,\ncalculating creating unit tests existing code \nlengthy tedious job, productivity suffer.Unit tests, however, best written develop code, rather\npackage written. Replace informal testing\nlightweight formal practices, see \nimmediate long-term productivity increase.Consider every unit software (every function, method, \nclass) designed job, return specific outputs \nspecific inputs, cause specific side effects. unit test\nspecifies behaviors, provides single mechanism — one\ntest functions residing one files, within \nstandard directory structure — ensure target\nfunction, method class job. assurance, \nprogrammer (collaborators) can , confidence, proceed\nuse larger program. bug appears, new features\nneeded added, one adds new tests existing collection.\ncode becomes progressively powerful, robust, yet\nremains easily automatically validated.proponents suggest benefits unit testing extend\n: code design improves. argue \noperational definition function tests encourages\nclean design, ‘separation concerns’, sensible handling \nedge cases.Finally, unit testing can adopted piecemeal. Add single test\npackage, even test minor feature, \nusers benefit. Add tests go, bugs arise,\nnew features added, find puzzling code\nwrote months . Soon, unit testing part \nstandard practice, package increasingly\ncomplete set tests.","code":"divideBy <- function(dividend, divisor) {\n if (divisor == 0)\n return(NA)\n dividend / divisor\n}test_divideBy <- function() {\n checkEquals(divideBy(4, 2), 2)\n checkTrue(is.na(divideBy(4, 0)))\n checkEqualsNumeric(divideBy(4, 1.2345), 3.24, tolerance=1.0e-4)\n}expect_equal(divideBy(4, 2), 2)\nexpect_true(is.na(divideBy(4, 0)))\nexpect_equal(divideBy(4, 1.2345), 3.24, tolerance=1.0e-4)test_that(\"divideBy works properly\", {\n expect_equal(divideBy(4, 2), 2)\n expect_true(is.na(divideBy(4, 0)))\n expect_equal(divideBy(4, 1.2345), 3.24, tolerance = 1.0e-4)\n})"},{"path":"tests.html","id":"which-tests","chapter":"14 Unit tests","heading":"14.2 Deciding Which Test Framework To Use","text":"RUnit, tinytest, testthat robust testing solutions great tools\npackage development, choose use package largely comes\npersonal preference. However brief list strengths \nweaknesses .","code":""},{"path":"tests.html","id":"runit-strengths","chapter":"14 Unit tests","heading":"14.2.1 RUnit Strengths","text":"Longer history (first release 2005)Direct analog xUnit projects languages.need learn small set check functions.Used extensively Bioconductor (210 Bioconductor packages, overall 339 circa May 2015), particularly \ncore packages.","code":""},{"path":"tests.html","id":"runit-weaknesses","chapter":"14 Unit tests","heading":"14.2.2 RUnit Weaknesses","text":"RUnit development activity since 2010, active maintainer.Need manually source package test code run interactively.difficult setup run natively (although see\nBiocGenerics:::testPackage() handles ).","code":""},{"path":"tests.html","id":"tinytest-strengths","chapter":"14 Unit tests","heading":"14.2.3 tinytest Strengths","text":"Easy setup use; tests written scriptsTests can run interactively well via R CMD checkTest results can treated data","code":""},{"path":"tests.html","id":"tinytest-weaknesses","chapter":"14 Unit tests","heading":"14.2.4 tinytest Weaknesses","text":"Minimally necessary functionality available","code":""},{"path":"tests.html","id":"testthat-strengths","chapter":"14 Unit tests","heading":"14.2.5 Testthat Strengths","text":"Active development 39 contributors.Greater variety test functions available, including partial matching \ncatching errors, warnings messages.Easy setup devtools::use_testthat().Integrates devtools::test() automatically reload package source \nrun tests development.Test failures errors informative RUnit.number different reporting functions available, including visual\nreal-time test results.Used extensively CRAN (546 CRAN packages, overall 598 circa May 2015).","code":""},{"path":"tests.html","id":"testthat-weaknesses","chapter":"14 Unit tests","heading":"14.2.6 Testthat Weaknesses","text":"Test code slightly verbose equivalent RUnit tests.available less time (since 2009).","code":""},{"path":"tests.html","id":"runit-usage","chapter":"14 Unit tests","heading":"14.3 RUnit Usage","text":"","code":""},{"path":"tests.html","id":"adding-tests-for-your-code","chapter":"14 Unit tests","heading":"14.3.1 Adding Tests For Your Code","text":"Three things required:Create file containing functions style test_dividesBy\nfunction want test, using RUnit-provided check\nfunctions.Add small (idiosyncratic) files directories.Make sure RUnit BiocGenerics packages \navailable.Steps two three explained conventions build\nprocess.RUnit check methods:typical test function, can see test_divideBy, \ninvoke one program’s functions methods, call \nappropriate RUnit check function make sure result \ncorrect. RUnit reports failures, , enough\ncontext track error.RUnit can test exception (error) occurs withbut often convenient test specific exceptions, e.g., \nwarning “unusual condition” generated function f <- function() { warning(\"unusual condition\"); 1 } withuse error=... test specific errors.","code":"checkEquals(expression-A, expression-B)\ncheckTrue(condition)\ncheckEqualsNumeric(a, b, tolerance)checkException(expr, msg)obs <- tryCatch(f(), warning=conditionMessage)\ncheckIdentical(\"unusual condition\", obs)"},{"path":"tests.html","id":"conventions","chapter":"14 Unit tests","heading":"14.3.2 Conventions for the Build Process","text":"Writing unit tests easy, though Bioconductor package must \nset properly R CMD check MyPackage finds run \ntests. take pains describe exactly things \nset , going behind scenes. (See next\nsection simple technique use \nwant test small part code).standard command R CMD check MyPackage sources runs R\nfiles found MyPackage/tests/ directory. Historically, \nsometimes still, R package developers place test code \ninvention style one files tests directory.RUnit added already-existing structure practice\n2005, additions can confusing, beginning \nindirect way test functions found executed. (\nfollow steps well. Post [bioc-devel][] \nrun difficulty.)two steps:Create file MyPackage/tests/runTests.R contents:\nBiocGenerics:::testPackage(\"MyPackage\")Create file MyPackage/tests/runTests.R contents:Create number files MyPackage/inst/unitTests/ \nunit test functions. can put tests one file \ndirectory, distributed among multiple files. files\nmust follow naming convention specified regular\nexpression:\npattern=\"^test_.*\\\\.R$\"\nexample, therefore, good choice \nMyPackage/inst/unitTests/test_divideBy.R dividesBy\nfunction one several home-brewed arithmetic functions \nwrote, provide tests, descriptive filename\n(practice always recommend) might \nMyPackage/inst/unitTests/test_homeBrewArithmetic.RCreate number files MyPackage/inst/unitTests/ \nunit test functions. can put tests one file \ndirectory, distributed among multiple files. files\nmust follow naming convention specified regular\nexpression:example, therefore, good choice \nMyPackage/inst/unitTests/test_divideBy.R dividesBy\nfunction one several home-brewed arithmetic functions \nwrote, provide tests, descriptive filename\n(practice always recommend) might \nMyPackage/inst/unitTests/test_homeBrewArithmetic.R","code":"BiocGenerics:::testPackage(\"MyPackage\")pattern=\"^test_.*\\\\.R$\""},{"path":"tests.html","id":"r-unit-during-develoment","chapter":"14 Unit tests","heading":"14.3.3 Using Tests During Development","text":"run tests. developing class, debugging\nmethod function, probably want run just one test \ntime, earlier version package \ninstalled, making local exploratory\nchanges. Assuming followed directory structure naming\nconventions recommended , current working directory \ninst, :failed test reported like :","code":"R CMD check MyPackagelibrary(RUnit)\nlibrary(MyPackage)\n\nsource('../R/divideBy.R')\nsource('unitTests/test_divideBy.R')\ntest_divideBy()\n[1] TRUEError in checkEquals(divideBy(4, 2), 3) : Mean relative difference: 0.5"},{"path":"tests.html","id":"summary-the-minimal-setup","chapter":"14 Unit tests","heading":"14.3.4 Summary: the minimal setup","text":"minimal Bioconductor unitTest setup requires one-line addition \nMyPackage/DESCRIPTION fileand two files, MyPackage/tests/runTests.R:MyPackage/inst/unitTests/test_divideBy.R:Remember unitTests/test_XXXX.R file, files, can \nname(s), long start test_.","code":"Suggests: RUnit, BiocGenericsBiocGenerics:::testPackage(\"MyPackage\")test_divideBy <- function() {\n checkEquals(divideBy(4, 2), 2)\n checkTrue(is.na(divideBy(4, 0)))\n checkEqualsNumeric(divideBy(4, 1.2345), 3.24, tolerance=1.0e-4)\n}"},{"path":"tests.html","id":"testthat-usage","chapter":"14 Unit tests","heading":"14.4 Testthat Usage","text":"Hadley Wickham, primary author testthat comprehensive chapter \nTesting testthat R packages book. also article\ntestthat: Get Started Testing R-Journal.easiest way setup testthat infrastructure package using\ndevtools::use_testthat().can automatically reload code tests re-run using\ndevtools::test().","code":""},{"path":"tests.html","id":"conversion-from-runit-to-testthat","chapter":"14 Unit tests","heading":"14.4.1 Conversion from RUnit to testthat","text":"existing RUnit project like convert using\ntestthat need change following things package\nstructure.devtools::use_testthat() can used setup testthat testing structure.Test files stored tests/testthat rather inst/unitTests \nstart test. Richard Cotton’s\nrunittotesthat package\ncan used programmatically convert RUnit tests testthat format.need add Suggests: testthat DESCRIPTION file rather \nSuggests: RUnit, BiocGenerics.","code":""},{"path":"tests.html","id":"conversion-from-runit-to-tinytest","chapter":"14 Unit tests","heading":"14.4.2 Conversion from RUnit to tinytest","text":"Test files placed inst/tinytest directory names \ntest_FILE.R.Remove RUnit function shells extract function bodies single\nscript.Include tinytest.R file tests folder runs:Add Suggests: testthat DESCRIPTION file.","code":"if (requireNamespace(\"tinytest\", quietly = TRUE))\n tinytest::test_package(\"PACKAGE\")"},{"path":"tests.html","id":"test-coverage","chapter":"14 Unit tests","heading":"14.5 Test Coverage","text":"Test coverage\nrefers percentage package code\ntested unit tests. Packages higher coverage\nlower chance containing bugs.tests taking long achieve full test coverage, see long tests.\nimplementing long tests highly recommend reaching \nbioconductor team bioc-devel mailing list ensure\nproper use justification.","code":""},{"path":"tests.html","id":"additional-resources","chapter":"14 Unit tests","heading":"14.6 Additional Resources","text":"web resources worth reading:Unit Testing WikipediaAn informal accountTest-driven developmentAgile software developmentTesting testthattestthat: Get Started Testing","code":""},{"path":"r-code.html","id":"r-code","chapter":"15 R code","heading":"15 R code","text":"Everyone coding style formats. however best\npractice guidelines Bioconductor reviewers look . can robust, fast efficient programming\nlanguage often coding practices result less ideal use \nresources.section review key points, suggestions, best practices \naid package review process assist making code \nrobust efficient.","code":""},{"path":"r-code.html","id":"rcode-license","chapter":"15 R code","heading":"15.1 License","text":"contain code can distributed license specified (see also\nDESCRIPTION file).","code":""},{"path":"r-code.html","id":"r-code-development","chapter":"15 R code","heading":"15.2 R Code Development","text":"","code":""},{"path":"r-code.html","id":"rcode-reuse","chapter":"15 R code","heading":"15.2.1 Re-use of functionality, classes, and generics","text":"Avoid re-implementing functionality classes (see also\nDESCRIPTION file).\nMake use appropriate existing packages (e.g.,\nbiomaRt,\nAnnotationDbi,\nBiostrings,\nGenomicRanges) classes (e.g.,\nSummarizedExperiment,\nBiobase::AnnotatedDataFrame,\nGenomicRanges:;GRanges,\nBiostrings::DNAStringSet) avoid duplication functionality\navailable Bioconductor packages. See\nalso Common Bioconductor Methods Classes.encourages interoperability simplifies package development.\nnew representation needed, see class development section.\ngeneral, Bioconductor insist interoperability Common\nClasses acceptance.Developers make effort re-use generics fit generic\ncontract proposed class-method pair .e., behavior method\naligns originally proposed behavior generic. Specifically,\nbehavior can one return value class across\nmethods. method behavior can also performant conceptual transformation\nprocedure across classes described generic.\nBiocGenerics lists commonly used generics \nBioconductor. One example generic method implementation \nrowSums generic corresponding method within \nDelayedArray package. generic contract returns \nnumeric vector length rows adhered across classes\nincluding DelayedMatrix class. Re-using generics reduces amount \nnew generics consolidating existing operations avoids mistake \nintroducing “new” generic name. Generic name collisions may\nmask masked previous definitions ways hard diagnose.\nrecently, recommend use conflicted \nidentify namespace collisions.problems, e.g., performance parsing particular\nfile type, ask input developers \nbioc-devel mailing list. Common disadvantages \n‘implementing ’ introduction non-standard data\nrepresentations (e.g., neglecting translate coordinate systems file\nformats Bioconductor objects) user bewilderment. Therefore, case,\nrecommend use standard file format classes inheriting \nBiocIO’s BiocFile class packages \nrtracklayer BiocIO.","code":""},{"path":"r-code.html","id":"naming-functions","chapter":"15 R code","heading":"15.2.2 Naming of packages, functions, and classes","text":"See section package naming. concepts also\napply function names, class names, etc.Avoid names :easily confused existing package names, function names, class names.Imply temporal (e.g. ExistingPackage2) qualitative\n(e.g. ExistingPackagePlus) relationship.Suggest hate speech, slurs profanity, either implicitly explicitly.Invoke refer historical, ethical, political contexts.Reference well known people, characters, brands, places icons.","code":""},{"path":"r-code.html","id":"rcode-method-development","chapter":"15 R code","heading":"15.2.3 Methods development","text":"encourage maintainers create new methods classes exported within\npackages. discourage generation methods external classes,\n.e., classes outside package NAMESPACE. can\npotentially cause method name collisions (.e., two methods defined \nobject different packages) pollute methods environment\nexternal classes. New methods established classes can also cause\nconfusion among users given new method class definition \nseparate packages.","code":""},{"path":"r-code.html","id":"rcode-file-names","chapter":"15 R code","heading":"15.2.4 File names","text":"Filename extension R code ‘.R’. Use prefix\n‘methods-’ S4 class methods, e.g., ‘methods-coverage.R’. Generic\ndefinitions can listed single file, ‘AllGenerics.R’, \nclass definitions ‘AllClasses.R’.Filename extension man pages ‘.Rd’.","code":""},{"path":"r-code.html","id":"class-development","chapter":"15 R code","heading":"15.2.5 Class development","text":"Remember re-use common Bioconductor methods classes\nimplementing new representations. encourages\ninteroperability simplifies package development.","code":""},{"path":"r-code.html","id":"class-names","chapter":"15 R code","heading":"15.2.5.1 Class Names","text":"Use CamelCaps: initial upper case, alternate case words.","code":""},{"path":"r-code.html","id":"class-design","chapter":"15 R code","heading":"15.2.5.2 Class design","text":"Bioconductor prefers use S4 classes S3 class. Please use S4\nrepresentation designing new classes. , can emphasize enough \nreuse existing class structure possible. existing class\nstructure sufficient, also encouraged look extending \ncontaining existing Bioconductor class.data requires new representation function, carefully\ndesign S4 class generic package developers \nsimilar needs able re-use hard work, users\nrelated packages able seamlessly use data\nstructures. hesitate ask Bioc-devel mailing list \nadvice.class define, implement use ‘constructor’ object\ncreation. constructor usually plain-old-function (rather ,\ne.g., generic methods). provides documented \nuser-friendly arguments, allowing developer-friendly\nimplementation. Use constructor throughout code,\nexamples, vignette.Implement show() method effectively convey information \nusers without overwhelming detail.Accessors (simple functions return components object)\nrather direct slot access (using @) help isolate \nimplementation class interface. Generally @ \nused accessor, code use \naccessor. accessor need exported class \nuser need business accessing parts data\nobject. Plain-old-functions (rather generic + method) often\nsufficient accessors; ’s often useful employ (consistently) \nlightweight name mangling scheme (e.g., starting accessor method\nname 2 3 letter acronym package) avoid name\ncollisions similarly named functions packages.following layout sometimes used organize classes \nmethods; approaches possible acceptable.class definitions R/AllClasses.RAll generic function definitions R/AllGenerics.RMethods defined file named generic function. \nexample, show methods go R/show-methods.R.Collate: field DESCRIPTION file may necessary order\nclass method definitions appropriately package\ninstallation.","code":""},{"path":"r-code.html","id":"function-development","chapter":"15 R code","heading":"15.2.6 Function development","text":"","code":""},{"path":"r-code.html","id":"rcode-function-names","chapter":"15 R code","heading":"15.2.6.1 Functions Names","text":"Function names follow following conventions:Use camelCase: initial lower case, alternate case words.use ‘.’ (S3 class system, (x) x class dispatch .).Prefix non-exported functions ‘.’.","code":""},{"path":"r-code.html","id":"functional-programming-and-length","chapter":"15 R code","heading":"15.2.6.2 Functional Programming and Length","text":"Guiding principle: Smaller functions easier read, test, debug reuse.Avoid large chunks repeated code. code repeated \ngenerally good indication helper function implemented.Avoid large chunks repeated code. code repeated \ngenerally good indication helper function implemented.Excessively long functions also avoided. Write small functions.Excessively long functions also avoided. Write small functions.best function one job needs . \nalso best function job lines code possible.\nfind writing great long functions extend \nscreen, probably take moment split smaller\nhelper functions.best function one job needs . \nalso best function job lines code possible.\nfind writing great long functions extend \nscreen, probably take moment split smaller\nhelper functions.Nesting functions avoiding. unnecessarily increases main\nfunction length makes main function harder read. Helper functions\ninternal functions avoid nested include end \nfile seperate file (e.g. internal.R, helpers.R, utils.R)Nesting functions avoiding. unnecessarily increases main\nfunction length makes main function harder read. Helper functions\ninternal functions avoid nested include end \nfile seperate file (e.g. internal.R, helpers.R, utils.R)","code":""},{"path":"r-code.html","id":"function-arguments","chapter":"15 R code","heading":"15.2.6.3 Function arguments","text":"Argument names functions descriptive well documented.Arguments generally default values.Check arguments validity check stopifnot","code":""},{"path":"r-code.html","id":"variable-names","chapter":"15 R code","heading":"15.2.6.4 Variable names","text":"Use camelCase: initial lowercase, alternate case words.","code":""},{"path":"r-code.html","id":"rcode-sysdep","chapter":"15 R code","heading":"15.2.6.5 Additional files and dependencies","text":"install anything users system! System dependencies, applications,\nadditionally needed packages assumed already present user’s\nsystem.Direct calls external commands via\nsystem() system2() ideal used \nalternative. example, CRAN Bioconductor package already\nprovides functionality , use instead.Now package absolutely must rely external software \nneed make sure requirements listed \nSystemRequirements field DESCRIPTION file package. \nrequirements “reasonable” requirements, , trusted software\n, open source, relatively easy install.Additionally ask package contains INSTALL file (\ntop-level folder) provides instructions installing external\nsoftware 3 major OS support: Linux, Windows, Mac. \nhelp users get external software machines,\nalso help us install build machines ’s \nalready .system package dependencies latest publically available\nversion. package dependencies must actively CRAN \nBioconductor. Bioconductor recognize Remotes Description \ninstall lower version package dependency.","code":""},{"path":"r-code.html","id":"rcode-namespaces","chapter":"15 R code","heading":"15.2.6.6 Namespaces","text":"Import symbols used packages “base”. Except \ndefault packages (base, graphics, stats, etc.) overly\ntedious, fully enumerate imports.Export symbols useful end users. Fully enumerate exports.","code":""},{"path":"r-code.html","id":"coding-style","chapter":"15 R code","heading":"15.2.7 Coding Style","text":"may seem arbitrary, consistent coding style helps \nunderstand, evaluate, debug code easier. optional, \nhighly encouraged.","code":""},{"path":"r-code.html","id":"indentation","chapter":"15 R code","heading":"15.2.7.1 Indentation","text":"Use 4 spaces indenting. tabs.lines longer 80 characters.","code":""},{"path":"r-code.html","id":"use-of-space","chapter":"15 R code","heading":"15.2.7.2 Use of space","text":"Always use space comma. : , b, c.space around “=” using named arguments functions. :\nsomefunc(=1, b=2)Space around binary operators: == b.","code":""},{"path":"r-code.html","id":"rcode-comments","chapter":"15 R code","heading":"15.2.7.3 Comments","text":"Use “##” start full-line comments.Indent level surrounding code.Comments clarification, notes, documentation .leave commented code chunks utilizedCommenting TODO’s avoided published package code","code":""},{"path":"r-code.html","id":"additonal-style-and-formatting-references","chapter":"15 R code","heading":"15.2.7.4 Additonal style and formatting references","text":"formatR package assists formatting.formatR package assists formatting.Hadley Wickhams’s R Style Guide.Hadley Wickhams’s R Style Guide.","code":""},{"path":"r-code.html","id":"r-code-best-practices-and-guidelines","chapter":"15 R code","heading":"15.3 R Code Best Practices and Guidelines","text":"Many common coding syntax issues flagged R CMD check \nBiocCheck() (see R CMD check\ncheatsheet BiocCheck vignette. Every\neffort made clear ERROR, WARNING, NOTEs produced \nchecks.","code":""},{"path":"r-code.html","id":"code-syntax-and-efficiency","chapter":"15 R code","heading":"15.3.1 Code syntax and efficiency","text":"Use vapply() instead sapply(), use various apply functions instead loops. See section vectorize.Use seq_len() seq_along() instead 1:.... See section avoid 1:n style iterationsUse TRUE FALSE instead T F.Use numeric indices lower level interfaces (e.g., internal subset ops) computational efficiency.Use named indices higher level interfaces (e.g., function arguments) robustness.Use () instead class() == class() !=.Use system2() instead system().use set.seed() internal code.use browser() internal code.Avoid use <<-.Avoid use direct slot access @ slot(). Accessor methods created utilizedUse packages ExperimentHub AnnotationHub instead downloading external data unsanctioned providers GitHub, <* class=“fa fa-dropbox” aria-hidden=“true”> Dropbox, etc. general, data utlilized packages downloaded trusted public databases. See also section web querying file caching.Use <- instead = assigning variables except function arguments.","code":""},{"path":"r-code.html","id":"cyclomatic-complexity","chapter":"15 R code","heading":"15.3.2 Cyclomatic Complexity","text":"metric developed Thomas J. McCabe, cyclomatic complexity describes \ncontrol-flow program. higher value, complex code \nsaid .BiocCheck example , series control-flow statements\ncheck multiple conditions return value \nconditions true. function hasValueSection checking \ndocumentation contains ‘value’ Rd tag .e., return section \ndocumentation.can see, code quite complex, creating statements \nspecific conditions. measured cyclomatic complexity given \ncyclocomp package value 16.Let’s re-write function reduce complexity use base character\nvector representation.internalizing base character vector representation code, \nsuccessive functions operate representation. gives us code\nless complex easier understand maintain complexity\nmetric value 2.Note. Switches based docType outside function filter\nmanpage input instead.","code":"\nhasValueSection <- function(manpage) {\n rd <- tools::parse_Rd(manpage)\n type <- BiocCheck:::docType(rd)\n if (identical(type, \"data\"))\n return(TRUE)\n tags <- tools:::RdTags(rd)\n if (\"\\\\usage\" %in% tags && (!\"\\\\value\" %in% tags))\n return(FALSE)\n value <- NULL\n if (\"\\\\value\" %in% tags)\n value <- rd[grep(\"\\\\value\", tags)]\n if (\"\\\\usage\" %in% tags && (!\"\\\\value\" %in% tags)) {\n values <- paste(unlist(value), collapse='')\n test <- (is.list(value[[1]]) && length(value[[1]]) == 0) ||\n nchar(gsub(\" \", \"\", values)) == 0\n if (test)\n return(FALSE)\n }\n TRUE\n}\nlibrary(cyclocomp)\ncyclocomp(hasValueSection)\n#> [1] 16\nhasValueSection2 <- function(manpage) {\n rd <- tools::parse_Rd(manpage)\n tags <- tools:::RdTags(rd)\n value <- rd[grepl(\"\\\\value\", tags)]\n value <- unlist(value, recursive = FALSE)\n value <- Filter(function(x) attr(x, \"Rd_tag\") != \"COMMENT\", value)\n values <- paste(value, collapse='')\n nzchar(trimws(values)) && length(value)\n}\ncyclocomp(hasValueSection2)\n#> [1] 2"},{"path":"r-code.html","id":"end-user-messages","chapter":"15 R code","heading":"15.3.2.1 End-User messages","text":"Use functions message(), warning() error(), instead \ncat() function (except customized show() methods). paste0() \ngenerally used methods except collapsing multiple values\nvariable.message() communicates diagnostic messages (e.g., progress \nlengthy computations) code evaluation.warning() communicates unusual situations handled code.stop() indicates error condition.cat() print() used displaying object user show method.","code":""},{"path":"r-code.html","id":"graphic-device","chapter":"15 R code","heading":"15.3.2.2 Graphic Device","text":"Use dev.new() start graphics drive necessary. Avoid using x11()\nX11(), can called machines access X\nserver.","code":""},{"path":"r-code.html","id":"web-querying-and-file-caching","chapter":"15 R code","heading":"15.3.2.3 Web Querying and File caching","text":"Files downloaded cached.\nPlease use BiocFileCache.\nmaintainer creates caching directory, utilize standard\ncaching directories tools::R_user_dir(package, =\"cache\"). \nallowed download write files users home directory, working\ndirectory, installed package directory. Files cached stated\nBiocFileCache (preferred) R_user_dir tempdir()/tempfile()\nfiles persistent.Please also follow guiding principles Appendix section Querying Web\nResources, applicable.","code":""},{"path":"r-code.html","id":"robust-and-efficient-r-code","chapter":"15 R code","heading":"15.4 Robust and Efficient R Code","text":"R can robust, fast efficient programming language, \ncoding practices can unfortunate. suggestions.","code":""},{"path":"r-code.html","id":"guiding-principles","chapter":"15 R code","heading":"15.4.1 Guiding Principles","text":"primary principle make sure code correct. Use\nidentical() .equal() ensure correctness, \nunit tests ensure consistent results across code revisions.primary principle make sure code correct. Use\nidentical() .equal() ensure correctness, \nunit tests ensure consistent results across code revisions.Write robust code. Avoid efficiencies easily handle\nedge cases 0 length NA values.Write robust code. Avoid efficiencies easily handle\nedge cases 0 length NA values.Know stop trying efficient. code takes \nfraction second evaluate, sense trying \nimprovement. Use system.time() package like\nmicrobenchmark quantify performance gains.Know stop trying efficient. code takes \nfraction second evaluate, sense trying \nimprovement. Use system.time() package like\nmicrobenchmark quantify performance gains.","code":""},{"path":"r-code.html","id":"reuse-existing-functionality-and-classes","chapter":"15 R code","heading":"15.4.2 Reuse Existing Functionality and Classes","text":"Emphasized good measure! Reuse existing import/export methods,\nfunctionality, classes whenever possible.","code":""},{"path":"r-code.html","id":"vectorize","chapter":"15 R code","heading":"15.4.3 Vectorize","text":"Many R operations performed whole object, just elements \nobject (e.g., sum(x) instead x[1] + x[2] + x[2] + ...). \nparticular, relatively situations require explicit loop.Vectorize, rather iterate (loops, lapply(), apply() \ncommon iteration idioms R). single call y <- sqrt(x) \nvector x length n example vectorized function. \ncall y <- sapply(x, sqrt) loop (seq_along(x)) y[] <- sqrt(x[]) iterative version \ncall, avoided. Often, iterative calculations can \nvectorized “hidden” body loopand can ‘hoisted’ loopOften principle can applied repeatedly, iterative\nloop becomes lines vectorized function calls.","code":"for (i in seq_len(n)) {\n ## ...\n tmp <- foo(x[i])\n y <- tmp + ## ...\n}tmp <- foo(x)\nfor (i in seq_len(n)) {\n ## ...\n y <- tmp[i] + ##\n}"},{"path":"r-code.html","id":"pre-allocate-and-fill-if-iterations-are-necessary","chapter":"15 R code","heading":"15.4.4 ‘Pre-allocate and fill’ if iterations are necessary","text":"Preallocate--fill (usually via lapply() vapply()) rather\ncopy--append. creating vector list results, use\nlapply() (create list) vapply() (create vector)\nrather loop. instance,manages memory allocation x compactly represents \ntransformation performed. loop might appropriate \niteration side effects (e.g., displaying plot) \ncalculation one value depends previous value. creating \nvector loop, always pre-allocate resultNever adopt strategy ‘copy--append’pattern copies current value x time \nloop, making n^2 / 2 total copies, scale poorly even \ntrivial computations:","code":"n <- 10000\nx <- vapply(seq_len(n), function(i) {\n ## ...\n}, integer(1))x <- integer(n)\nif (n > 0) x[1] <- 0\nfor (i in seq_len(n - 1)) {\n ## x[i + 1] <- ...\n}not_this <- function(n) {\n x <- integer()\n for (i in seq_len(n))\n x[i] = i\n x\n}> system.time(not_this(1000)\n user system elapsed\n 0.004 0.000 0.004\n> system.time(not_this(10000))\n user system elapsed\n 0.169 0.000 0.168\n> system.time(not_this(100000))\n user system elapsed\n 22.827 1.120 23.936"},{"path":"r-code.html","id":"avoid-1n-style-iterations","chapter":"15 R code","heading":"15.4.5 Avoid 1:n style iterations","text":"Write seq_len(n) seq_along(x) rather 1:n \n1:length(x). protects case n length(x)\n0 (often occurs unexpected ‘edge case’ real code) \nnegative.","code":""},{"path":"r-code.html","id":"parallel-recommendations","chapter":"15 R code","heading":"15.4.6 Parallel Recommendations","text":"recommend using BiocParallel. provides \nconsistent interface user supports major parallel computing\nstyles: forks processes single computer, ad hoc clusters,\nbatch schedulers cloud computing. default, BiocParallel\nchooses parallel back-end appropriate OS supported\nacross Unix, Mac Windows. Coding requirements BiocParallel\n:Use lapply()-style iteration instead explicit loops.FUN argument bplapply() must self-contained\nfunction; symbols used function default R\npackages, packages require()’ed function, passed \narguments.Allow user specify BiocParallel back-end. \ninvoking bplapply() without specifying BPPARAM; user can\noverride default choice BiocParallel::register().information see BiocParallel vignette.implementing package development, minimal number cores (1 2)\nset default.","code":""},{"path":"other-than-Rcode.html","id":"other-than-Rcode","chapter":"16 Fortran / C / C++ / Python / Third-Party Code","heading":"16 Fortran / C / C++ / Python / Third-Party Code","text":"package contains C Fortran code, adhere standards \nmethods described System foreign language interfaces\nsection Writing R Extensions manual.","code":""},{"path":"other-than-Rcode.html","id":"makevars","chapter":"16 Fortran / C / C++ / Python / Third-Party Code","heading":"16.1 Makevars","text":"Make judicious use Makevars Makefile files within package.\noften required (See Configure cleanup section Writing R Extensions manual).","code":""},{"path":"other-than-Rcode.html","id":"fortran","chapter":"16 Fortran / C / C++ / Python / Third-Party Code","heading":"16.2 Fortran","text":"Consider utilizing dotCall64 CRAN package.","code":""},{"path":"other-than-Rcode.html","id":"ccode","chapter":"16 Fortran / C / C++ / Python / Third-Party Code","heading":"16.3 C / C++","text":"Rcpp CRAN package allows seamless integration C++ R, \ncross-platform. package affords many benefits \nR C interface make C++ appealing language, \neliminating many pitfalls programming R interface.package well documented, extensive repository \nworking examples many tasks: Rcpp Gallery.","code":""},{"path":"other-than-Rcode.html","id":"python","chapter":"16 Fortran / C / C++ / Python / Third-Party Code","heading":"16.4 Python","text":"basilisk package required integrate python R packages. \nreticulate alternative, developer must make strong argument \nbasilisk used.","code":""},{"path":"other-than-Rcode.html","id":"third-party-code","chapter":"16 Fortran / C / C++ / Python / Third-Party Code","heading":"16.5 Other","text":"Use external libraries whose functionality redundant libraries\nalready supported strongly discouraged. cases external library\ncomplex, author may need supply pre-built binary versions \nplatforms.including third-party code package maintainer assumes responsibility \nmaintenance code. Part maintenance responsibility includes\nkeeping code date bug fixes updates released \nmainline third-party project.","code":""},{"path":"shiny.html","id":"shiny","chapter":"17 Shiny apps","heading":"17 Shiny apps","text":"Shiny apps can submitted Bioconductor software packages documented tested functions within packages.","code":""},{"path":"shiny.html","id":"code-organisation","chapter":"17 Shiny apps","heading":"17.1 Code organisation","text":"Shiny apps divided two parts:User interface (UI)ServerShiny apps submitted Bioconductor must store code UI server code R/ directory package.bulk package code implemented directly within shinyApp() function call.\nInstead, internal package functions developed produce return individual components UI server sides Shiny app.Shiny apps can also written using shiny modules allow \nbetter code organisation re-usability.recommend following file naming scheme source files:Place internal functions create observers – e.g., shiny::observeEvent() – files named observers_*.R.\nobservers reacting Shiny server input object, reactive values stored lists reactive values (e.g., shiny::reactiveValues()).Place internal functions create UI elements – e.g., shiny::checkboxInput() – files named interface_*.R.Place internal functions update Shiny server output object files named outputs_*.R.Place internal functions perform miscellaneous processing steps files named utils_*.R.","code":""},{"path":"shiny.html","id":"running-app","chapter":"17 Shiny apps","heading":"17.2 Running app","text":"Functions package return Shiny apps, launch .words, function shiny::runApp() found anywhere package source code.\nInstead, users left call function, using Shiny app objects returned package functions options control app run (e.g., launch.browser = TRUE).instance, package source code look follows:user’s code look follows:","code":"\nbuild_app <- function(...) {\n ui <- .build_ui(...)\n server <- .build_server(...)\n app <- shinyApp(ui = ui, server = server)\n}\napp <- build_app(...)\nshiny::runApp(app, ...)"},{"path":"shiny.html","id":"building-the-package","chapter":"17 Shiny apps","heading":"17.3 Building the package","text":"Packages shiny apps built using standard R CMD build\ncommand. package structure follow standard R package structure,\nShiny app code stored R/ directory.:optional app.R file can added base directory package \nlaunch Shiny app using shiny::runApp() main shiny app deployment\nfunction.","code":"MyShinyPackage/\n|-- app.R\n|-- DESCRIPTION\n|-- NAMESPACE\n|-- R/\n| |-- interface_*.R\n| |-- observers_*.R\n| |-- outputs_*.R\n| |- server_*.R\n| └- utils.R\n|-- tests/\n|-- vignettes/\n|-- man/\n|-- inst/\n[...]"},{"path":"shiny.html","id":"testing","chapter":"17 Shiny apps","heading":"17.4 Testing","text":"plain non-reactive functions package testable using\nstandard unit testing tools (e.g., testthat).use # nocov start # nocov end allowed ignore part code tested using traditional unit tests (e.g., observeEvent).instance:Use files setup-*.R subdirectory tests/testthat/ generate objects used repeatedly input unit tests.recommended use shinytest2 package \ntest visual computational aspects Shiny apps.","code":"\n# nocov start\nobserveEvent(input$example_input, {\n # \n})\n# nocov end"},{"path":"shiny.html","id":"documentation","chapter":"17 Shiny apps","heading":"17.5 Documentation","text":"Man pages documenting functions return Shiny apps use interactive() function demonstrate usage app.instance, typical ‘Example’ section man page look follows:Although optional, highly recommend documenting internal functions \npackages contain Shiny apps. recommend way visible\ndevelopers users:using roxygen2, use tag @keywords internal\nRoxygen block. keep documentation package \nremove help page index. may want increase visibility \ninternal documentation linking help pages within package\n(e.g., within “developers” section).example:Alternatively (though less common), prefix manual pages INTERNAL_*\nadd man/.gitignore.set name Rd document, use @name tag Roxygen block:Additionally, vignette shiny app package might include screenshots, either generated manually programmatically.\ngenerated manually, developers can use tools pngquant (available command line utility GUI systems) reduce size (70%) without much loss quality.\nProgrammatically generated screenshots can realized means Webshot2 package, using webshot2::appshot() function.","code":"\nlibrary(MyShinyPackage)\n\napp <- build_app(...)\n\nif (interactive()) {\n shiny::runApp(app, ...)\n}\n#' @keywords internal\n.build_app <- function(...) {\n ...\n}\n#' @name INTERNAL_build_app\n.build_app <- function(...) {\n ...\n}"},{"path":"shiny.html","id":"review","chapter":"17 Shiny apps","heading":"17.6 Review","text":"reviewing shiny app package, reviewer check package\nfollows guidelines outlined document.highly recommend reviewers use shinytest2\npackage test visual computational aspects Shiny app \naddition standard unit tests plain functions.Reviewers also check package documentation complete \naccurate, package passes BiocCheck \naddition R CMD build check.user experience important. Reviewers ensure app \nresponsive user interface intuitive easy--use. app\ncrash hang user interacts .Errors warnings handled gracefully visible \nintelligible user. recommend using\nshinytoastr display error, warning, info\nmessages user.","code":""},{"path":"non-software.html","id":"non-software","chapter":"18 Non-Software Packages","heading":"18 Non-Software Packages","text":"packages contributed users software packages. However, \ninstances package types submitted. following sections \ngo specifics look non-software type packages.","code":""},{"path":"non-software.html","id":"annotation-and-experiment-data-packages","chapter":"18 Non-Software Packages","heading":"18.1 Annotation and Experiment data packages","text":"Annotation packages database-like packages provide information linking\nidentifies (e.g., Entrez gene names Affymetrix probe ids) \ninformation (e.g., chromosomal location, Gene Ontology category).Experiment data packages provide data sets used, often software\npackages, illustrate particular analyses. packages contain curated\ndata experiment, teaching course publication cases\ncontain single data set.look similar requirements software packages, importantly \nproper documentation data included within package. Traditional\nAnnotation Experiment packages ideal; AnnotationHub \nExperimentHub interfaces packages desirable.","code":""},{"path":"non-software.html","id":"annotationexperiment-hub-packages","chapter":"18 Non-Software Packages","heading":"18.2 Annotation/Experiment Hub packages","text":"light weight packages related resources added \nAnnotationHub \nExperimentHub. package minimally contain\nresource metadata, man pages describing resources, vignette. \nmay also contain supporting R function author wants provide. \npackages similar Annotation Experiment data packages except\ndata stored provided Bioconductor Microsoft Azure Data Lakes\npublicly accessibly sites (ensembl, AWS S3 buckets, etc) instead \npackage .information creating hub packages well contents\nCreate Hub Package vignette within \nHubPub Bioconductor package.","code":""},{"path":"non-software.html","id":"workflow-packages","chapter":"18 Non-Software Packages","heading":"18.3 Workflow packages","text":"Workflow packages contain vignettes describe bioinformatics workflow\ninvolves multiple Bioconductor packages. vignettes usually \nextensive vignettes accompany software packages. packages \nneed man/ R/ directories data/ directory ideally\nworkflows make use existing data Bioconductor package.Existing WorkflowsWorkflow vignettes may deal larger data sets /computationally intensive\ntypical Bioconductor package vignettes. reason, automated builder \nproduces vignettes time limit (contrast Bioconductor package\nbuilding system time package building takes long). \nexpected majority vignette code chunks evaluated.","code":""},{"path":"non-software.html","id":"submit-workflow","chapter":"18 Non-Software Packages","heading":"18.3.1 How do I write and submit a workflow vignette?","text":"Write package name workflow. workflow vignette\nwritten Markdown, using rmarkdown package included \nvignette directory. may include one vignette please use\nuseful identifying names.Write package name workflow. workflow vignette\nwritten Markdown, using rmarkdown package included \nvignette directory. may include one vignette please use\nuseful identifying names.package need man/ R/ directories data/ directory \nideally workflows make use existing data Bioconductor repository \nweb; workflow package contain large data files.package need man/ R/ directories data/ directory \nideally workflows make use existing data Bioconductor repository \nweb; workflow package contain large data files.DESCRIPTION file, include line “BiocType: Workflow”. Please also\ninclude detailed Description field DESCRIPTION file. DESCRIPTION\nfile contain biocViews Workflow\nbranch. think new term relevant please reach \nlori.shepherd@roswellpark.org.DESCRIPTION file, include line “BiocType: Workflow”. Please also\ninclude detailed Description field DESCRIPTION file. DESCRIPTION\nfile contain biocViews Workflow\nbranch. think new term relevant please reach \nlori.shepherd@roswellpark.org.Submit package GitHub submission tracker formal\nreview. Please also indicate tracker issue package \nworkflow.Submit package GitHub submission tracker formal\nreview. Please also indicate tracker issue package \nworkflow.Workflows git version controlled. package accepted \nadded git repository git@git.bioconductor.org instructions \nsent gaining access maintainence.Workflows git version controlled. package accepted \nadded git repository git@git.bioconductor.org instructions \nsent gaining access maintainence.","code":""},{"path":"non-software.html","id":"consistent-formatting","chapter":"18 Non-Software Packages","heading":"18.3.2 Consistent formatting","text":"effort standardize workflow vignette format, strongly\nencouraged use either BiocStyle formatting \nutilize BiocWorkflowTools. following header\nshows use BiocStyle vignette:\noutput:\n BiocStyle::html_documentIn effort standardize workflow vignette format, strongly\nencouraged use either BiocStyle formatting \nutilize BiocWorkflowTools. following header\nshows use BiocStyle vignette:following also include\n- author affiliations\n- date representing workflow vignette modifiedThe following also includeThe first section versioning information. R version,\nBioconductor version, package version visible.\nfollowing example achieved:first section versioning information. R version,\nBioconductor version, package version visible.\nfollowing example achieved:example start workflow vignette:following taken example header variants workflow package:","code":"output:\n BiocStyle::html_document- author affiliations\n- a date representing when the workflow vignette has been modified\n \n

\n**R version**: `r R.version.string`\n
\n**Bioconductor version**: `r BiocManager::version()`\n
\n**Package version**: `r packageVersion(\"annotation\")`\n<\/p>\n \n\n \n– – –\ntitle: Annotating Genomic Variants\nauthor: \n–name: Valerie Obenchain\n affiliation: Fred Hutchinson Cancer Research Center, 1100 Fairview Ave. N., P.O. Box 19024, Seattle, WA, USA 98109–1024\ndate: 11 April 2018\nvignette: >\n %\\VignetteIndexEntry{Annotating Genomic Variants}\n %\\VignetteEngine{knitr::rmarkdown}\noutput: \n BiocStyle::html_document\n– – –\n\n\n# Version Info\n```{r, echo=FALSE, results=\"hide\", warning=FALSE}\nsuppressPackageStartupMessages({library('variants')})\n```\n

\n**R version**: `r R.version.string`\n
\n**Bioconductor version**: `r BiocManager::version()`\n
\n**Package version**: `r packageVersion(\"variants\")`\n<\/p>\n\n\n \n"},{"path":"non-software.html","id":"tidying-package-loading-output","chapter":"18 Non-Software Packages","heading":"18.3.3 Tidying package loading output","text":"workflows load number packages want\noutput loading packages clutter workflow\ndocument. ’s solve markdown; can\nsomething similar Latex.First, set code chunk evaluated echoed, whose\nresults hidden. also set warning=FALSE sure \noutput chunk ends document:can set another code chunk echoed,\nalmost contents. second invocation library()\nproduce output since package already loaded:","code":"```{r, echo=FALSE, results=\"hide\", warning=FALSE}\nsuppressPackageStartupMessages({\nlibrary(GenomicRanges)\nlibrary(GenomicAlignments)\nlibrary(Biostrings)\nlibrary(Rsamtools)\nlibrary(ShortRead)\nlibrary(BiocParallel)\nlibrary(rtracklayer)\nlibrary(VariantAnnotation)\nlibrary(AnnotationHub)\nlibrary(BSgenome.Hsapiens.UCSC.hg19)\nlibrary(RNAseqData.HNRNPC.bam.chr14)\n})\n``````{r}\nlibrary(GenomicRanges)\nlibrary(GenomicAlignments)\nlibrary(Biostrings)\nlibrary(Rsamtools)\nlibrary(ShortRead)\nlibrary(BiocParallel)\nlibrary(rtracklayer)\nlibrary(VariantAnnotation)\nlibrary(AnnotationHub)\nlibrary(BSgenome.Hsapiens.UCSC.hg19)\nlibrary(RNAseqData.HNRNPC.bam.chr14)\n```"},{"path":"non-software.html","id":"citations","chapter":"18 Non-Software Packages","heading":"18.3.4 Citations","text":"manage citations workflow document,\nspecify bibliography file document metadata header.can use citation keys form [@label] cite entry identifier “label”.Normally, want end document section header “References” similar, bibliography appended.details see rmarkdown documentation.","code":"bibliography: references.bib"},{"path":"gitignore.html","id":"gitignore","chapter":"19 The .gitignore file","heading":"19 The .gitignore file","text":"Bioconductor requires Git repository submission.certain system files tracked repository \nunacceptable include. files can remain local system \nexcluded Git repository possible including \n.gitignore file.following files checked BiocCheck flagged unacceptable:one .gitignore file top level package\ndirectory.","code":"\nhidden_file_ext = c(\n \".renviron\", \".rprofile\", \".rproj\", \".rproj.user\", \".rhistory\",\n \".rapp.history\", \".o\", \".sl\", \".so\", \".dylib\", \".a\", \".dll\",\n \".def\", \".ds_store\", \"unsrturl.bst\", \".log\", \".aux\", \".backups\",\n \".cproject\", \".directory\", \".dropbox\", \".exrc\", \".gdb.history\",\n \".gitattributes\", \".gitmodules\", \".hgtags\", \".project\", \".seed\",\n \".settings\", \".tm_properties\"\n)"},{"path":"conclusion.html","id":"conclusion","chapter":"20 Conclusion","heading":"20 Conclusion","text":"exercise Build Bioconductor Package RStudio may also helpful.Remember every Bioconductor package goes formal review\nprocess may still receive technical feedback assigned\nBioconductor reviewer.overview submission process may found previous\nsection package may submitted \nGitHub package submission repository.Thank reading guidelines, welcome Bioconductor\ncommunity users developers!","code":""},{"path":"package-maintenance.html","id":"package-maintenance","chapter":"Overview","heading":"Overview","text":"section offers useful tools help pages continued maintenance \ndevelopment packages already existing Bioconductor.","code":""},{"path":"git-version-control.html","id":"git-version-control","chapter":"21 Git Version Control","heading":"21 Git Version Control","text":"Bioconductor project maintained Git source control\nsystem. Package maintainers update packages pushing changes\ngit repositories.chapter contains several sections cover typical scenarios\nencountered adding maintaining Bioconductor package.","code":""},{"path":"git-version-control.html","id":"essential-work-flow","chapter":"21 Git Version Control","heading":"21.1 Essential work flow","text":"minimal workflow checkout, update, commit, push changes \nrepository. Using BiocGenerics example:requires Bioconductor knows SSH keys use \nestablish identity.Two useful commands areIf repository already cloned, work flow make sure\n‘devel’ branch, pull changes, introduce\nedits.","code":"git clone git@git.bioconductor.org:packages/BiocGenerics\ncd BiocGenerics\n## add a file, e.g., `touch README`\n## edit file, e.g., `vi DESCRIPTION`\nBiocGenerics$ git commit README DESCRIPTION\nBiocGenerics$ git pushBiocGenerics$ git diff # review changes prior to commit\nBiocGenerics$ git log # review recent commitsBiocGenerics$ git checkout devel\nBiocGenerics$ git pull\n## add, edit, commit, and push as above"},{"path":"git-version-control.html","id":"where-to-commit-changes","chapter":"21 Git Version Control","heading":"21.2 Where to Commit Changes","text":"New features bug fixes introduced devel branch GIT\nrepository.make extensive changes see Fix bugs devel release.Bug fixes can ported current release branch. Use\ncherry-pick identify commmit(s) like port. E.g.,\nrelease 3.6, porting recent commit devel","code":"BiocGenerics$ git checkout devel\nBiocGenerics$ git pull\n## edit 'R/foo.R' and commit on devel\nBiocGenerics$ git commit R/foo.R #\n[devel c955179] your commit message\n1 file changed, 10 insertions(+), 3 deletions(-)\nBiocGenerics$ git pushBiocGenerics$ git checkout RELEASE_3_6\nBiocGenerics$ git cherry-pick devel\nBiocGenerics$ git push"},{"path":"git-version-control.html","id":"checks-and-version-bumps","chapter":"21 Git Version Control","heading":"21.3 Checks and version bumps","text":"commit pushed Bioconductor repository build \ncheck without errors warningsEach commit, either release devel, include bump \nz portion x.y.z package versioning scheme.Builds occur per day, take approximately 24 hours. See \nbuild report git commits captured recent build\n(upper left corner)","code":"BiocGenerics$ cd ..\nR CMD build BiocGenerics\nR CMD check BiocGenerics_1.22.3.tar.gz"},{"path":"git-version-control.html","id":"annotation-packages","chapter":"21 Git Version Control","heading":"21.4 Annotation packages","text":"Traditional Annotation packages stored GIT due size \nannotation files. update existing Annotation package please send email\nmaintainer@bioconductor.org. member Bioconductor team \ncontact receive updated package.Newer annotation packages can stored GIT requirement use \nAnnotationHub server hosted data. larger sized\nfiles included directly package. contribute new Annotation\npackage please contact hubs@bioconductor.org guidance read \ndocumentation Create Hub Package.Currently direct updates annotation packages, even stored git, \nsupported. wish updated annotation package, make required\nchanges push git.bioconductor.org. send email \nhubs@bioconductor.org maintainer@bioconductor.org requesting package propagated.","code":""},{"path":"git-version-control.html","id":"subversion-to-git-transition","chapter":"21 Git Version Control","heading":"21.5 Subversion to Git Transition","text":"essential steps transitioning SVN git summarized\ninNew package workflow: update GitHub repository \npackage acceptance.Create new GitHub repository existing package.Maintain Bioconductor-repository existing\npackage.","code":""},{"path":"git-version-control.html","id":"new-package-workflow","chapter":"21 Git Version Control","heading":"21.5.1 New package workflow","text":"Goal: developed package GitHub, following \nBioconductor new package Contributions README guidelines,\nsubmitted Bioconductor, package \nmoderated. part moderation process, package reviewed\nadded repository Bioconductor git server.review process, package authors must push changes\ninclude version number ‘bump’ Bioconductor git\nrepository. causes package built checked Linux,\nmacOS, Windows operating systems, forms basis \nreview process.document, package authors learn best practices \npushing Bioconductor git repository.SSH keys. part initial moderation step,\nBioconductor use SSH ‘public key’ keys available \nhttps://github.com/<-github-id>.keys.\nreview process , additional SSH keys can added\ncontact information edited using BiocCredentials\napplication.SSH keys. part initial moderation step,\nBioconductor use SSH ‘public key’ keys available \nhttps://github.com/<-github-id>.keys.review process , additional SSH keys can added\ncontact information edited using BiocCredentials\napplication.Configure “remotes” local git repository. need\npush future changes package Bioconductor git\nrepository issue new build package.\nAdd remote named upstream package’s local git\nrepository using:\n git remote add upstream git@git.bioconductor.org:packages/<-REPOSITORY-NAME>.git\nCheck updated remotes repository; ’ll\nsee origin remote pointing github.com, upstream remote\npointing bioconductor.org\n $ git remote -v\n\n origin (fetch)\n origin (push)\n upstream git@git.bioconductor.org:packages/<-REPOSITORY-NAME>.git (fetch)\n upstream git@git.bioconductor.org:packages/<-REPOSITORY-NAME>.git (push)\nNOTE: package developer, must use SSH protocol (\ncommand) gain read/write access package \nBioconductor git repository.Configure “remotes” local git repository. need\npush future changes package Bioconductor git\nrepository issue new build package.Add remote named upstream package’s local git\nrepository using:Check updated remotes repository; ’ll\nsee origin remote pointing github.com, upstream remote\npointing bioconductor.orgNOTE: package developer, must use SSH protocol (\ncommand) gain read/write access package \nBioconductor git repository.Add commit changes local repository. \nreview process likely need update package. \nlocal repository first making sure repository \n--date github.com git.bioconductor.org\nrepositories.\n git fetch --\n\n ## merge changes Bioc (upstream remote git@git.bioconductor.org)\n git merge upstream/devel\n\n ## merge changes GitHub (origin remote)\n git merge origin/devel\nNote. GitHub default branch main, replace devel \nmain:\n ## merge changes GitHub (origin remote)\n git merge origin/main\nMake changes package devel branch commit \nlocal repository\n git add \n git commit -m \"\"Add commit changes local repository. \nreview process likely need update package. \nlocal repository first making sure repository \n--date github.com git.bioconductor.org\nrepositories.Note. GitHub default branch main, replace devel \nmain:Make changes package devel branch commit \nlocal repository‘Bump’ package version. package version number \nformat ‘major.minor.patch’. Initial package submissions \nversion number 0.99.0, indicated Version field \nDESCRIPTION file. Increment patch version number 1, e.g., \n0.99.1, 0.99.2, …, 0.99.9, 0.99.10, …\nBumping version number pushing essential. ensures\npackage built across platforms.\nRemember add commit changes local repository.‘Bump’ package version. package version number \nformat ‘major.minor.patch’. Initial package submissions \nversion number 0.99.0, indicated Version field \nDESCRIPTION file. Increment patch version number 1, e.g., \n0.99.1, 0.99.2, …, 0.99.9, 0.99.10, …Bumping version number pushing essential. ensures\npackage built across platforms.Remember add commit changes local repository.Push changes Bioconductor GitHub repositories. Push\nchanges local repository Bioconductor \nGitHub repositories.\n ## push BioC (upstream remote git@git.bioconductor.org)\n git push upstream devel\n\n ## push GitHub (origin remote)\n git push origin devel\nNote. GitHub default branch main, replace devel \nmain:\n ## push Bioc (upstream remote git@git.bioconductor.org)\n git push upstream main:devel\n\n ## push GitHub (origin remote)\n git push origin mainPush changes Bioconductor GitHub repositories. Push\nchanges local repository Bioconductor \nGitHub repositories.Note. GitHub default branch main, replace devel \nmain:Check updated build report. push \ngit.bioconductor.org included version bump, ’ll receive \nemail directing visit issue github.com,\nhttps://github.com/Bioconductor/Contributions/issues/; comment\nalso posted issue indicating build started.\nseveral minutes second email comment indicate \nbuild completed, build report \navailable. comment includes link build report. Follow\nlink see whether changes necessary.Check updated build report. push \ngit.bioconductor.org included version bump, ’ll receive \nemail directing visit issue github.com,\nhttps://github.com/Bioconductor/Contributions/issues/; comment\nalso posted issue indicating build started.several minutes second email comment indicate \nbuild completed, build report \navailable. comment includes link build report. Follow\nlink see whether changes necessary.See scenarios working Bioconductor GitHub repositories, particular:\nMaintain GitHub Bioconductor repositories.\nFix bugs devel release.\nResolve merge conflicts.\nSee scenarios working Bioconductor GitHub repositories, particular:Maintain GitHub Bioconductor repositories.Fix bugs devel release.Resolve merge conflicts.","code":" git remote add upstream git@git.bioconductor.org:packages/.git $ git remote -v\n\n origin (fetch)\n origin (push)\n upstream git@git.bioconductor.org:packages/.git (fetch)\n upstream git@git.bioconductor.org:packages/.git (push) git fetch --all\n\n ## merge changes from Bioc (upstream remote at git@git.bioconductor.org)\n git merge upstream/devel\n\n ## merge changes from GitHub (origin remote)\n git merge origin/devel ## merge changes from GitHub (origin remote)\n git merge origin/main git add \n git commit -m \"\" ## push to BioC (upstream remote at git@git.bioconductor.org)\n git push upstream devel\n\n ## push to GitHub (origin remote)\n git push origin devel ## push to Bioc (upstream remote at git@git.bioconductor.org)\n git push upstream main:devel\n\n ## push to GitHub (origin remote)\n git push origin main"},{"path":"git-version-control.html","id":"maintain-github-bioc","chapter":"21 Git Version Control","heading":"21.5.2 Create a new GitHub repository for an existing Bioconductor package","text":"Goal: maintainer, ’d like create new GitHub\nrepository existing Bioconductor repository, \nuser community can engage development package.Create new GitHub account don’t one.Create new GitHub account don’t one.Set remote access GitHub via SSH Https. Please check\n-remote-url---use \nadd public key GitHub account.Set remote access GitHub via SSH Https. Please check\n-remote-url---use \nadd public key GitHub account.submitted keys, can login \nBiocCredentials application check correct\nkeys file Bioconductor.submitted keys, can login \nBiocCredentials application check correct\nkeys file Bioconductor.Create new GitHub repo account, name\nexisting Bioconductor package.\nuse “BiocGenerics” example scenario.\n\npressing ‘Create repository’ button, ignore \ninstructions GitHub provides, follow rest \ndocument.Create new GitHub repo account, name\nexisting Bioconductor package.use “BiocGenerics” example scenario.pressing ‘Create repository’ button, ignore \ninstructions GitHub provides, follow rest \ndocument.local machine, clone empty repository GitHub.\nUse https URL (replace GitHub username)\ngit clone https://github.com//BiocGenerics.git\nSSH URL\ngit clone git@github.com:/BiocGenerics.gitOn local machine, clone empty repository GitHub.Use https URL (replace GitHub username)SSH URLAdd remote cloned repository.\nChange current working directory local repository\ncloned previous step.\ncd BiocGenerics\ngit remote add upstream git@git.bioconductor.org:packages/BiocGenerics.gitAdd remote cloned repository.Change current working directory local repository\ncloned previous step.Fetch content remote upstream,\ngit fetch upstreamFetch content remote upstream,Merge upstream origin’s devel branch,\ngit merge upstream/devel\nNOTE: error fatal: refusing merge unrelated histories, repository cloned step 4 \nempty. Either clone empty repository, see\nSync existing repositories.Merge upstream origin’s devel branch,NOTE: error fatal: refusing merge unrelated histories, repository cloned step 4 \nempty. Either clone empty repository, see\nSync existing repositories.Push changes origin devel,\n git push origin devel\nNOTE: Run command git config --global push.default matching always push local branches remote branch \nname, allowing use git push origin rather git push origin devel.Push changes origin devel,NOTE: Run command git config --global push.default matching always push local branches remote branch \nname, allowing use git push origin rather git push origin devel.(Optional) Add branch GitHub,\n## Fetch updates\ngit fetch upstream\n\n## Checkout new branch RELEASE_3_6, upstream/RELEASE_3_6\ngit checkout -b RELEASE_3_6 upstream/RELEASE_3_6\n\n## Push updates remote origin's new branch RELEASE_3_6\ngit push -u origin RELEASE_3_6(Optional) Add branch GitHub,Check GitHub repository confirm devel (\noptionally RELEASE_3_6) branches present.Check GitHub repository confirm devel (\noptionally RELEASE_3_6) branches present.GitHub repository established follow\nPush GitHub Bioconductor maintain repository\nGitHub Bioconductor.GitHub repository established follow\nPush GitHub Bioconductor maintain repository\nGitHub Bioconductor.","code":"git clone https://github.com//BiocGenerics.gitgit clone git@github.com:/BiocGenerics.gitcd BiocGenerics\ngit remote add upstream git@git.bioconductor.org:packages/BiocGenerics.gitgit fetch upstreamgit merge upstream/devel git push origin devel## Fetch all updates\ngit fetch upstream\n\n## Checkout new branch RELEASE_3_6, from upstream/RELEASE_3_6\ngit checkout -b RELEASE_3_6 upstream/RELEASE_3_6\n\n## Push updates to remote origin's new branch RELEASE_3_6\ngit push -u origin RELEASE_3_6"},{"path":"git-version-control.html","id":"maintain-bioc-only","chapter":"21 Git Version Control","heading":"21.5.3 Maintain a Bioconductor-only repository for an existing package","text":"Goal: Developer wishes maintain Bioconductor repository\nwithout using GitHub.","code":""},{"path":"git-version-control.html","id":"clone-and-setup-the-package-on-your-local-machine.","chapter":"21 Git Version Control","heading":"21.5.3.1 Clone and setup the package on your local machine.","text":"Make sure SSH access Bioconductor\nrepository; sure submit SSH public key \ngithub id Bioconductor.Make sure SSH access Bioconductor\nrepository; sure submit SSH public key \ngithub id Bioconductor.Clone package local machine,\n git clone git@git.bioconductor.org:packages/\nNOTE: clone https get read+write\naccess.Clone package local machine,NOTE: clone https get read+write\naccess.View existing remotes\n git remote -v\ndisplay\n origin git@git.bioconductor.org:packages/.git (fetch)\n origin git@git.bioconductor.org:packages/.git (push)\nindicates git repository one remote\norigin, Bioconductor repository.View existing remoteswhich displayThis indicates git repository one remote\norigin, Bioconductor repository.work flows, origin remote renamed \nupstream. may convenient make change \nrepository\n git remote rename origin upstream\nconfirm git remote -v now associates upstream\nrepository name git@git.bioconductor.org.work flows, origin remote renamed \nupstream. may convenient make change \nrepositoryand confirm git remote -v now associates upstream\nrepository name git@git.bioconductor.org.","code":" git clone git@git.bioconductor.org:packages/ git remote -v origin git@git.bioconductor.org:packages/.git (fetch)\n origin git@git.bioconductor.org:packages/.git (push) git remote rename origin upstream"},{"path":"git-version-control.html","id":"commit-changes-to-your-local-repository","chapter":"21 Git Version Control","heading":"21.5.3.2 Commit changes to your local repository","text":"making changes repository, make sure pull\nchanges updates Bioconductor repository. \nneeded avoid conflicts.\n git pullBefore making changes repository, make sure pull\nchanges updates Bioconductor repository. \nneeded avoid conflicts.Make required changes, add commit changes \ndevel branch.\n git add \n git commit -m \"informative commit message\"Make required changes, add commit changes \ndevel branch.(Alternative) changes non-trivial, create new branch\ncan easily abandon false starts. Merge final\nversion onto devel\n git checkout -b feature--feature\n ## add commit branch. change complete...\n git checkout devel\n git merge feature--feature(Alternative) changes non-trivial, create new branch\ncan easily abandon false starts. Merge final\nversion onto devel","code":" git pull git add \n git commit -m \"My informative commit message\" git checkout -b feature-my-feature\n ## add and commit to this branch. When the change is complete...\n git checkout devel\n git merge feature-my-feature"},{"path":"git-version-control.html","id":"push-your-local-commits-to-the-bioconductor-repository","chapter":"21 Git Version Control","heading":"21.5.3.3 Push your local commits to the Bioconductor repository","text":"Push commits Bioconductor repository make \navailable user community.\nPush changes devel branch using:\n git checkout devel\n git push upstream develPush commits Bioconductor repository make \navailable user community.Push changes devel branch using:Make sure valid version bump changes propagate users.","code":" git checkout devel\n git push upstream devel"},{"path":"git-version-control.html","id":"optional-merge-changes-to-the-current-release-branch","chapter":"21 Git Version Control","heading":"21.5.3.4 (Optional) Merge changes to the current release branch","text":"Merging devel release branch avoided. Select bug fixes \ncherry-picked devel release. See section Bug Fixes Release Devel","code":""},{"path":"git-version-control.html","id":"more-scenarios-for-repository-creation","chapter":"21 Git Version Control","heading":"21.6 More scenarios for repository creation","text":"Sync existing GitHub repository Bioconductor.Create local repository private use.","code":""},{"path":"git-version-control.html","id":"sync-existing-repositories","chapter":"21 Git Version Control","heading":"21.6.1 Sync an existing GitHub repository with Bioconductor","text":"Goal: Ensure local, Bioconductor, GitHub\nrepositories sync.Clone GitHub repository local machine. Change \ndirectory containing repository.Clone GitHub repository local machine. Change \ndirectory containing repository.Configure “remotes” GitHub clone.\n git remote add upstream git@git.bioconductor.org:packages/<-REPOSITORY>.gitConfigure “remotes” GitHub clone.Fetch updates (Bioconductor GitHub) remotes. may\nsee “warning: common commits”; addressed \nresolving conflicts, .\n git fetch --allFetch updates (Bioconductor GitHub) remotes. may\nsee “warning: common commits”; addressed \nresolving conflicts, .Make sure devel branch.\n git checkout develMake sure devel branch.Merge updates GitHub (origin) remote\n git merge origin/develMerge updates GitHub (origin) remoteMerge updates Bioconductor (upstream) remote\n git merge upstream/devel\nUsers git version >= 2.9 see error message (“fatal:\nrefusing merge unrelated histories”) need use\n git merge --allow-unrelated-histories upstream/develMerge updates Bioconductor (upstream) remoteUsers git version >= 2.9 see error message (“fatal:\nrefusing merge unrelated histories”) need useResolve merge conflicts necessary.Resolve merge conflicts necessary.resolving conflicts committing changes, look duplicate\ncommits (e.g., git log --oneline | wc returns twice many\ncommits SVN) consider following steps \nforce Bioconductor devel GitHub devel.resolving conflicts committing changes, look duplicate\ncommits (e.g., git log --oneline | wc returns twice many\ncommits SVN) consider following steps \nforce Bioconductor devel GitHub devel.Push Bioconductor GitHub repositories.\n git push upstream devel\n git push origin develPush Bioconductor GitHub repositories.Repeat release branch, replacing devel name \nrelease branch, e.g., RELEASE_3_6. may necessary \ncreate release branch local repository.\n git checkout RELEASE_3_6\n git merge upstream/RELEASE_3_6\n git merge origin/RELEASE_3_6\n git push upstream RELEASE_3_6\n git push origin RELEASE_3_6\nNOTE: syncing release branch first time,\nmake local copy RELEASE_X_Y branch, \n git checkout -b upstream/\nFollowing one time local checkout, may switch \nRELEASE_X_Y devel git checkout . \nuse command get local copy release branch, \nget message,\n(HEAD detached origin/RELEASE_X_Y)\nRemember devel current release branch \nBioconductor repositories can updated.Repeat release branch, replacing devel name \nrelease branch, e.g., RELEASE_3_6. may necessary \ncreate release branch local repository.NOTE: syncing release branch first time,\nmake local copy RELEASE_X_Y branch, byFollowing one time local checkout, may switch \nRELEASE_X_Y devel git checkout . \nuse command get local copy release branch, \nget message,Remember devel current release branch \nBioconductor repositories can updated.","code":" git remote add upstream git@git.bioconductor.org:packages/.git git fetch --all git checkout devel git merge origin/devel git merge upstream/devel git merge --allow-unrelated-histories upstream/devel git push upstream devel\n git push origin devel git checkout RELEASE_3_6\n git merge upstream/RELEASE_3_6\n git merge origin/RELEASE_3_6\n git push upstream RELEASE_3_6\n git push origin RELEASE_3_6 git checkout -b upstream/(HEAD detached from origin/RELEASE_X_Y)"},{"path":"git-version-control.html","id":"create-local-repository","chapter":"21 Git Version Control","heading":"21.6.2 Create a local repository for private use","text":"Goal: user (package developer) like modify\nfunctions package meet needs. GitHub\nrepository package.Clone package Bioconductor repository. end\nuser, write access repository, use \nhttps protocol\n git clone https://git@git.bioconductor.org/packages/Clone package Bioconductor repository. end\nuser, write access repository, use \nhttps protocolMake changes local repository. Commit changes \nlocal repository. best practice might modify changes new\nbranch\n git checkout -b feature--feature\n ## modify\n git commit --m \"feature: new feature\"\nmerge feature onto branch corresponding \nrelease use, e.g.,\n git checkout \n git merge feature--featureMake changes local repository. Commit changes \nlocal repository. best practice might modify changes new\nbranchand merge feature onto branch corresponding \nrelease use, e.g.,Rebuild (create vignette help pages) reinstall \npackage local machine running parent directory \nExamplePackage\n R CMD build ExamplePackage\n R CMD INSTALL ExamplePackage_.tar.gzRebuild (create vignette help pages) reinstall \npackage local machine running parent directory \nExamplePackageThe package changes available local R\ninstallation.package changes available local R\ninstallation.","code":" git clone https://git@git.bioconductor.org/packages/ git checkout -b feature-my-feature\n ## modify\n git commit -a -m \"feature: a new feature\" git checkout \n git merge feature-my-feature R CMD build ExamplePackage\n R CMD INSTALL ExamplePackage_.tar.gz"},{"path":"git-version-control.html","id":"scenarios-for-code-update","chapter":"21 Git Version Control","heading":"21.7 Scenarios for code update:","text":"Pull upstream changes, e.g., introduced core team.Push GitHub Bioconductor repositories.Resolve merge conflicts.Abandon changes.Fix bugs devel release.Resolve duplicate commits","code":""},{"path":"git-version-control.html","id":"pull-upstream-changes","chapter":"21 Git Version Control","heading":"21.7.1 Pull upstream changes","text":"Goal: Bioconductor repository updated core\nteam. want fetch commits Bioconductor, merge \nlocal repository, push GitHub.NOTE: always good idea fetch updates \nBioconductor making changes. help prevent\nmerge conflicts.steps update devel branch.Make sure appropriate branch.\n git checkout develMake sure appropriate branch.Fetch content Bioconductor\n git fetch upstreamFetch content BioconductorMerge upstream appropriate local branch\n git merge upstream/devel\nGet help Resolve merge conflicts occur.Merge upstream appropriate local branchGet help Resolve merge conflicts occur.also maintain GitHub repository, push changes GitHub’s\n(origin) devel branch\n git push origin develIf also maintain GitHub repository, push changes GitHub’s\n(origin) devel branchTo pull updates current RELEASE_X_Y branch, replace devel\nRELEASE_X_Y lines .See instructions Sync existing repositories \nchanges Bioconductor GitHub repositories.","code":" git checkout devel git fetch upstream git merge upstream/devel git push origin devel"},{"path":"git-version-control.html","id":"push-to-github-bioc","chapter":"21 Git Version Control","heading":"21.7.2 Push to GitHub and Bioconductor repositories","text":"Goal: everyday development, commit changes \nlocal repository devel branch, wish push commits \nGitHub Bioconductor repositories.NOTE: See Pull upstream changes best practices \ncommitting local changes.assume already GitHub repository right setup\npush Bioconductor’s git server\n(git@git.bioconductor.org). please see FAQ’s get\naccess follow instructions \nMaintain GitHub Bioconductor repositories. use clone\nBiocGenerics package following example.assume already GitHub repository right setup\npush Bioconductor’s git server\n(git@git.bioconductor.org). please see FAQ’s get\naccess follow instructions \nMaintain GitHub Bioconductor repositories. use clone\nBiocGenerics package following example.check remotes set properly, run command inside\nlocal machine’s clone.\ngit remote -v\nproduce result ( GitHub\nusername):\norigin git@github.com:/BiocGenerics.git (fetch)\norigin git@github.com:/BiocGenerics.git (push)\nupstream git@git.bioconductor.org:packages/BiocGenerics.git (fetch)\nupstream git@git.bioconductor.org:packages/BiocGenerics.git (push)check remotes set properly, run command inside\nlocal machine’s clone.produce result ( GitHub\nusername):Make commit changes devel branch\n git checkout devel\n ## edit files, etc.\n git add \n git commit -m \"informative commit message describing change\"Make commit changes devel branch(Alternative) changes elaborate, best practice \nuse local branch development.\n git checkout devel\n git checkout -b feature--feature\n ## multiple rounds edit, add, commit\nMerge local branch devel feature ‘complete’.\n git checkout devel\n\n # Pull upstream changes merging\n # http://bioconductor.org/developers/-/git/pull-upstream-changes/\n\n git merge feature--feature(Alternative) changes elaborate, best practice \nuse local branch development.Merge local branch devel feature ‘complete’.Push updates GitHub’s (origin) devel branch\n git push origin develPush updates GitHub’s (origin) devel branchNext, push updates Bioconductor’s (upstream) devel branch\ngit push upstream develNext, push updates Bioconductor’s (upstream) devel branchConfirm changes, e.g., visiting GitHub web page repository.Confirm changes, e.g., visiting GitHub web page repository.","code":"git remote -vorigin git@github.com:/BiocGenerics.git (fetch)\norigin git@github.com:/BiocGenerics.git (push)\nupstream git@git.bioconductor.org:packages/BiocGenerics.git (fetch)\nupstream git@git.bioconductor.org:packages/BiocGenerics.git (push) git checkout devel\n ## edit files, etc.\n git add \n git commit -m \"My informative commit message describing the change\" git checkout devel\n git checkout -b feature-my-feature\n ## multiple rounds of edit, add, commit git checkout devel\n\n # Pull upstream changes before merging\n # http://bioconductor.org/developers/how-to/git/pull-upstream-changes/\n\n git merge feature-my-feature git push origin develgit push upstream devel"},{"path":"git-version-control.html","id":"resolve-merge-conflicts","chapter":"21 Git Version Control","heading":"21.7.3 Resolve merge conflicts","text":"Goal: Resolve merge conflicts branch push GitHub \nBioconductor repositories.know merge conflict see something like\n:\n git merge upstream/devel\n Auto-merging DESCRIPTION\n CONFLICT (content): Merge conflict DESCRIPTION\n Automatic merge failed; fix conflicts commit result\nmerge conflict occurs package developer makes \nchange, also collaborator Bioconductor core team\nmember makes change file (case \nDESCRIPTION file).\ncan avoid ? Pull upstream changes \ncommitting changes. words, fetch merge remote\nbranches push.know merge conflict see something like\n:merge conflict occurs package developer makes \nchange, also collaborator Bioconductor core team\nmember makes change file (case \nDESCRIPTION file).can avoid ? Pull upstream changes \ncommitting changes. words, fetch merge remote\nbranches push.spite conflicts, need fix . See\nfile conflict,\n git status\nshow something like :\n branch devel\n branch ahead 'origin/devel' 1 commit.\n (use \"git push\" publish local commits)\n un-merged paths.\n (fix conflicts run \"git commit\")\n (use \"git merge --abort\" abort merge)\n\n Un-merged paths:\n (use \"git add ...\" mark resolution)\n\n modified: DESCRIPTION\n\n changes added commit (use \"git add\" /\"git commit -\")spite conflicts, need fix . See\nfile conflict,show something like :Open file favorite editor. Conflicts look like:\n <<<<<<< HEAD\n Version: 0.23.2\n =======\n Version: 0.23.3\n >>>>>>> upstream/devel\nEverything <<<< ===== refers HEAD, .e \ncurrent change. everything ===== >>>>> refers\nremote/branch shown , .e upstream/devel.\nwant keep accurate change, deleting \nnecessary. case, keep latest version:\n Version: 0.23.3Open file favorite editor. Conflicts look like:Everything <<<< ===== refers HEAD, .e \ncurrent change. everything ===== >>>>> refers\nremote/branch shown , .e upstream/devel.want keep accurate change, deleting \nnecessary. case, keep latest version:Add commit file change.\n git add DESCRIPTION\n git commit -m \"Fixed conflicts version change\"Add commit file change.Push GitHub Bioconductor repositories,\ngit push origin devel\ngit push upstream develPush GitHub Bioconductor repositories,","code":" git merge upstream/devel\n Auto-merging DESCRIPTION\n CONFLICT (content): Merge conflict in DESCRIPTION\n Automatic merge failed; fix conflicts and then commit the result git status On branch devel\n Your branch is ahead of 'origin/devel' by 1 commit.\n (use \"git push\" to publish your local commits)\n You have un-merged paths.\n (fix conflicts and run \"git commit\")\n (use \"git merge --abort\" to abort the merge)\n\n Un-merged paths:\n (use \"git add ...\" to mark resolution)\n\n both modified: DESCRIPTION\n\n no changes added to commit (use \"git add\" and/or \"git commit -a\") <<<<<<< HEAD\n Version: 0.23.2\n =======\n Version: 0.23.3\n >>>>>>> upstream/devel Version: 0.23.3 git add DESCRIPTION\n git commit -m \"Fixed conflicts in version change\"git push origin devel\ngit push upstream devel"},{"path":"git-version-control.html","id":"extra-resources","chapter":"21 Git Version Control","heading":"21.7.3.1 Extra Resources","text":"Resolving merge conflict using command lineBased : Resolving merge conflict","code":""},{"path":"git-version-control.html","id":"abandon-changes","chapter":"21 Git Version Control","heading":"21.7.4 Abandon changes","text":"Goal: want start fresh failing resolve conflicts\nissue. intend go nuclear, please contact \nbioc-devel@bioconductor.org mailing list.","code":""},{"path":"git-version-control.html","id":"force-bioconductor-devel-to-github-devel","chapter":"21 Git Version Control","heading":"21.7.4.1 Force Bioconductor devel to GitHub devel","text":"One way can ignore work make new branch replacing\nlocal GitHub repository devel branch \nBioconductor devel branch.Note: works haven’t pushed change causing \nissue Bioconductor repository.Note: references commits current devel (e.g., GitHub\nissues) invalidated.Checkout new branch, e.g., devel_backup, tracking set \ntrack Bioconductor devel branch upstream/devel.\n git checkout -b devel_backup upstream/develCheckout new branch, e.g., devel_backup, tracking set \ntrack Bioconductor devel branch upstream/devel.Rename branches currently local\nmachine. First, rename devel devel_deprecated. Second,\nrename devel_backup devel. process called \nclassic Switcheroo.\n git branch -m devel devel_deprecated\n git branch -m devel_backup develRename branches currently local\nmachine. First, rename devel devel_deprecated. Second,\nrename devel_backup devel. process called \nclassic Switcheroo.now “force push” changes GitHub\n(origin) devel branch.\n git push -f origin develYou now “force push” changes GitHub\n(origin) devel branch.(Optional) commits devel_deprecated\nbranch like ported new devel\nbranch. Git special feature called cherry-pick\nTake look commit want cherry-pick new\ndevel branch, using git log devel_deprecated, copy correct\ncommit id, use:\n git cherry-pick \nPush cherry-picked changes GitHub Bioconductor\nrepositories.(Optional) commits devel_deprecated\nbranch like ported new devel\nbranch. Git special feature called cherry-pickTake look commit want cherry-pick new\ndevel branch, using git log devel_deprecated, copy correct\ncommit id, use:Push cherry-picked changes GitHub Bioconductor\nrepositories.","code":" git checkout -b devel_backup upstream/devel git branch -m devel devel_deprecated\n git branch -m devel_backup devel git push -f origin devel git cherry-pick "},{"path":"git-version-control.html","id":"reset-to-a-previous-commit","chapter":"21 Git Version Control","heading":"21.7.4.2 Reset to a previous commit","text":"find place want abandon changes\nalready committed Bioconductor GitHub, use reset undo\ncommits local repository push -f force \nchanges remotes. Remember HEAD commit id \nrecent parent commit current state local\nrepository.Example:make changes permanent, need push changes\nGitHub, email Bioconductor core team force push \nrepository Bioconductor.Bioconductor core team rest email.","code":"git reset --hard git reset --hard e02e4d86812457fd9fdd43adae5761f5946fdfb3\nHEAD is now at e02e4d8 version bump by bioc core## You\n\ngit push -f origin"},{"path":"git-version-control.html","id":"delete-your-local-copy-and-github-repo-because-nothing-is-working","chapter":"21 Git Version Control","heading":"21.7.4.3 Delete your local copy and GitHub repo, because nothing is working","text":"CAUTION: instructions come many disadvantages. \nwarned.Delete local repository, e.g., rm -rf BiocGenericsDelete local repository, e.g., rm -rf BiocGenericsDelete (rename) GitHub repository.Delete (rename) GitHub repository.Maintain GitHub Bioconductor repositories existing\nBioconductor repository, Pull upstream changes.Maintain GitHub Bioconductor repositories existing\nBioconductor repository, Pull upstream changes.","code":""},{"path":"git-version-control.html","id":"disadvantages-of-going-nuclear","chapter":"21 Git Version Control","heading":"21.7.4.3.1 Disadvantages of going “nuclear”","text":"lose GitHub issuesYou lose GitHub issuesYou lose custom collaborator settings GitHub.lose custom collaborator settings GitHub.lose GitHub-specific changes.lose GitHub-specific changes.","code":""},{"path":"git-version-control.html","id":"bug-fix-in-release-and-devel","chapter":"21 Git Version Control","heading":"21.7.5 Fix bugs in devel and release","text":"Goal: bug present release devel branches \nBioconductor, maintainer introduce patch default\ngit branch current release branch (e.g., RELEASE_3_14).First Sync existing repositories.\n git fetch --\n git checkout devel\n git merge upstream/devel\n git merge origin/devel\n git checkout \n git merge upstream/\n git merge origin/First Sync existing repositories.local machine, sure devel branch.\n git checkout devel\nMake changes needed fix bug add modified files\ncommit. Remember bump version number DESCRIPTION file\nseparate commit. bug-fix changes introduced \ncommit.\n git add \nCommit modified files. helpful tag commit message “bug\nfix”.\n git commit -m \"bug fix: bug fix\"\nBump version package editing Version field \nDESCRIPTION commit change separate commit. allows \ncherry-pick bug correction avoid version number conflicts \nBioconductor branches /bug fixes ported release.\n ## version bump\n git add DESCRIPTION\n git commit -m \"version bump devel\"local machine, sure devel branch.Make changes needed fix bug add modified files\ncommit. Remember bump version number DESCRIPTION file\nseparate commit. bug-fix changes introduced \ncommit.Commit modified files. helpful tag commit message “bug\nfix”.Bump version package editing Version field \nDESCRIPTION commit change separate commit. allows \ncherry-pick bug correction avoid version number conflicts \nBioconductor branches /bug fixes ported release.(Alternative) changes non-trivial .e., multiple commits,\ncreate new branch can easily abandon false starts.\n git checkout devel\n git checkout -b bugfix--bug\n ## add commit branch fix bug\nMerge final version branch default branch.\n git checkout devel\n git merge bugfix--bug(Alternative) changes non-trivial .e., multiple commits,\ncreate new branch can easily abandon false starts.Merge final version branch default branch.Switch release branch cherry-pick commit hash range \nhashes default branch correspond bug fix (examples\ngit cherry-pick --help). Remember edit DESCRIPTION file \nupdate release version package according Bioconductor’s\nversion numbering scheme.\n git checkout \n ## example hash git log: 2644710\n git cherry-pick \n ## Bump version commit change\n git add DESCRIPTION\n git commit -m \"version bump release\"\nNOTE: patching release first time, \nmake local copy RELEASE_X_Y branch \n git checkout -b upstream/\nFollowing one time local checkout, may switch RELEASE_X_Y\ndevel git checkout . use command\nget local checkout release branch, get message:\n (HEAD detached origin/RELEASE_X_Y)Switch release branch cherry-pick commit hash range \nhashes default branch correspond bug fix (examples\ngit cherry-pick --help). Remember edit DESCRIPTION file \nupdate release version package according Bioconductor’s\nversion numbering scheme.NOTE: patching release first time, \nmake local copy RELEASE_X_Y branch withFollowing one time local checkout, may switch RELEASE_X_Y\ndevel git checkout . use command\nget local checkout release branch, get message:Push changes GitHub Bioconductor devel\n branches. Make sure correct\nbranch local machine.\ndevel branch,\n git checkout devel\n git push upstream devel\n git push origin devel\nrelease branch,\n git checkout \n git push upstream \n git push origin Push changes GitHub Bioconductor devel\n branches. Make sure correct\nbranch local machine.devel branch,release branch,See video tutorial :","code":" git fetch --all\n git checkout devel\n git merge upstream/devel\n git merge origin/devel\n git checkout \n git merge upstream/\n git merge origin/ git checkout devel git add git commit -m \"bug fix: my bug fix\" ## after version bump\n git add DESCRIPTION\n git commit -m \"version bump in devel\" git checkout devel\n git checkout -b bugfix-my-bug\n ## add and commit to this branch to fix the bug git checkout devel\n git merge bugfix-my-bug git checkout \n ## example hash from git log: 2644710\n git cherry-pick \n ## Bump the version and commit the change\n git add DESCRIPTION\n git commit -m \"version bump in release\" git checkout -b upstream/ (HEAD detached from origin/RELEASE_X_Y) git checkout devel\n git push upstream devel\n git push origin devel git checkout \n git push upstream \n git push origin "},{"path":"git-version-control.html","id":"resolve-duplicate-commits","chapter":"21 Git Version Control","heading":"21.7.6 Resolve Duplicate Commits","text":"Goal: want get rid duplicate (triplicate) commits\ngit commit history.begin Update package existing version \nBioconductor.","code":""},{"path":"git-version-control.html","id":"steps","chapter":"21 Git Version Control","heading":"21.7.6.1 Steps:","text":"IMPORTANT Make backup branch duplicate commits,\ncall devel_backup (RELEASE_3_7_backup). name \nback branch identifiable specific \nbranch trying fix (.e want fix devel\nbranch branch).\ndevel, (make sure devel git checkout devel)\n git branch devel_backupIMPORTANT Make backup branch duplicate commits,\ncall devel_backup (RELEASE_3_7_backup). name \nback branch identifiable specific \nbranch trying fix (.e want fix devel\nbranch branch).devel, (make sure devel git checkout devel)Identify commit duplicates \noriginated. commits often , merge commits.Identify commit duplicates \noriginated. commits often , merge commits.Reset branch commit merge commit.\n git reset —hard Reset branch commit merge commit.Now cherry pick commits devel_backup branch.\n git cherry-pick \ncommits cherry-pick 1 version \nduplicate commit, .e don’t cherry-pick commit twice.\nInclude branching version bump commits \ncherry-pick. Make package history look normal possible.\nNow cherry pick commits devel_backup branch.commits cherry-pick 1 version \nduplicate commit, .e don’t cherry-pick commit twice.commits cherry-pick 1 version \nduplicate commit, .e don’t cherry-pick commit twice.Include branching version bump commits \ncherry-pick. Make package history look normal possible.Include branching version bump commits \ncherry-pick. Make package history look normal possible.(Optional) cases, conflicts need fix \ncherry-pick succeed. Please read documentation \nresolve conflicts(Optional) cases, conflicts need fix \ncherry-pick succeed. Please read documentation \nresolve conflictsFinally, need contact bioc-devel mailing list \nreach Bioconductor core team sync repository \nversion Bioconductor. possible --force pushes\nalter git timeline possible maintainers.Finally, need contact bioc-devel mailing list \nreach Bioconductor core team sync repository \nversion Bioconductor. possible --force pushes\nalter git timeline possible maintainers.","code":" git branch devel_backup git reset —hard git cherry-pick "},{"path":"git-version-control.html","id":"how-to-check-if-your-package-has-duplicate-commits","chapter":"21 Git Version Control","heading":"21.7.6.2 How to check if your package has duplicate commits","text":"One way check log. see commit message\nchanges, different commit ID, tryor","code":"git loggit log --oneline"},{"path":"git-version-control.html","id":"script-to-detect-duplicate-commits","chapter":"21 Git Version Control","heading":"21.7.6.3 Script to detect duplicate commits","text":"Run script written python detect duplicate commits\nspecific Bioconductor repositories.Usage example:","code":"python detect_duplicate_commits.py /BiocGenerics 1000\n\npython detect_duplicate_commits.py '"},{"path":"git-version-control.html","id":"github-scenarios","chapter":"21 Git Version Control","heading":"21.8 Github scenarios","text":"Add collaborators use Github social coding features.Change Package MaintainerRemove Large Data Files clean git tree","code":""},{"path":"git-version-control.html","id":"add-collaborators-and-leverage-github-features","chapter":"21 Git Version Control","heading":"21.8.1 Add collaborators and leverage GitHub features","text":"Goal: like take advantage social coding\nfeatures provided GitHub, continuing update \nBioconductor repository.","code":""},{"path":"git-version-control.html","id":"maintaining-collaborators-on-github","chapter":"21 Git Version Control","heading":"21.8.1.1 Maintaining Collaborators on GitHub","text":"Adding new collaboratorAdding new collaboratorRemoving collaboratorRemoving collaborator","code":""},{"path":"git-version-control.html","id":"pull-requests-on-github","chapter":"21 Git Version Control","heading":"21.8.1.2 Pull requests on GitHub","text":"Merging pull request","code":""},{"path":"git-version-control.html","id":"push-github-changes-to-the-bioconductor-repository","chapter":"21 Git Version Control","heading":"21.8.1.3 Push GitHub changes to the Bioconductor repository","text":"accepted pull requests package community \nGitHub, can push changes Bioconductor.Make sure branch changes \napplied, example devel.\n git checkout develMake sure branch changes \napplied, example devel.Fetch merge GitHub changes local repository.\n git fetch origin\n git merge\nResolve merge conflicts necessary.Fetch merge GitHub changes local repository.Resolve merge conflicts necessary.Push local repository upstream Bioconductor repository.\n git push upstream devel\npush GitHub release branch updates Bioconductor\nrelease branch, replace devel name release branch,\ne.g.: RELEASE_3_6.Push local repository upstream Bioconductor repository.push GitHub release branch updates Bioconductor\nrelease branch, replace devel name release branch,\ne.g.: RELEASE_3_6.","code":" git checkout devel git fetch origin\n git merge git push upstream devel"},{"path":"git-version-control.html","id":"change-maintainer","chapter":"21 Git Version Control","heading":"21.8.2 Add or Transfer Maintainership of a Package","text":"Goal: Perhaps point time can longer maintain \npackage accordance Bioconductor package guidelines. may \nnecessary add transfer maintainer-ship package order properly\nmaintain package avoid deprecation removal.Find new maintainer\nmay collaborator colleague volunteer take . , ask\nbioc-devel mailing list.Find new maintainerYou may collaborator colleague volunteer take . , ask\nbioc-devel mailing list.Email maintainer@bioconductor.org bioc-devel@r-project.org\noriginal maintainer email request maintainer \npackage updated. Include package name contact information \nnew maintainer.Email maintainer@bioconductor.org bioc-devel@r-project.orgThe original maintainer email request maintainer \npackage updated. Include package name contact information \nnew maintainer.Update Package DESCRIPTION file\nDESCRIPTION file package updated new maintainer\ninformation pushed Bioconductor git.bioconductor.org repository.Update Package DESCRIPTION fileThe DESCRIPTION file package updated new maintainer\ninformation pushed Bioconductor git.bioconductor.org repository.","code":""},{"path":"git-version-control.html","id":"remove-large-data-files-and-clean-git-tree","chapter":"21 Git Version Control","heading":"21.8.3 Remove Large Data Files and Clean Git Tree","text":"Goal: Git remembers. Sometimes large data files added git\nrepository (intentionally unintentionally) causing size repository\nbecome large. happens, ’s enough just remove files.\nalso must remove git tree (repository history), else\nrepository remain large.ways remove large files git history. , ’ll\noutline two options: 1) git filter-repo, 2) BFG repo cleaner.\nsteps run local copy (necessary) pushed \ngithub repository.","code":""},{"path":"git-version-control.html","id":"removing-large-files-from-history-with-filter-repo","chapter":"21 Git Version Control","heading":"21.8.3.1 Removing Large Files from History with filter-repo","text":"2023, recommended way first locate large files, \nremove git filter-repo.Identify large files using git rev-list script:list objects repository, including objects \nhistory, order file size. Use identify names files remove.Remove filter-repo.separate tool ’ll install\n(e.g. pip3 install git-filter-repo). , can rewrite repository\nhistory remove files like , identifies files:example, remove .RData files, use:command may reset remotes. Check git remote \nneeded, can add remotes back using something like :Finally, push --mirror reset remote.Now, just notify everyone ’ll re-clone new repository, since\nhistory rewritten, existing clones longer compatible\nrepo.","code":"git rev-list --objects --all \\\n| git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' \\\n| sed -n 's/^blob //p' \\\n| sort --numeric-sort --key=2 \\\n| cut -c 1-12,41- \\\n| $(command -v gnumfmt || echo numfmt) --field=2 --to=iec-i --suffix=B --padding=7 --round=nearestgit filter-repo --path-glob '' --invert-pathsgit filter-repo --path-glob '*.RData' --invert-pathsgit remote add origin git@github.com:/\ngit push --set-upstream origin devel --forcegit push --force --mirror"},{"path":"git-version-control.html","id":"removing-large-files-from-history-with-bfg-repo-cleaner","chapter":"21 Git Version Control","heading":"21.8.3.2 Removing Large Files from History with BFG repo cleaner","text":"Another option use BFG. steps assume origin user-maintained github\nrepository.NOTE: Anyone maintaining package repository (local copy)\nrun steps 1-3.Download BFG Repo-CleanerDownload BFG Repo-CleanerRun BFG Repo-Cleaner package directory\nlocation package, run following command\njava -jar /bfg-1.13.0.jar --strip-blobs-bigger-100M <\npackage>\nNote: command remove file 100Mb \nlarger. Adjust argument based size files cleaning \n. lower offending file size.Run BFG Repo-Cleaner package directoryIn location package, run following commandNote: command remove file 100Mb \nlarger. Adjust argument based size files cleaning \n. lower offending file size.Run clean \ncd \ngit reflog expire --expire=now --&& git gc --prune=now --aggressiveRun clean upPush Changes\ngit push -f originPush ChangesRequest updates git.bioconductor.org repository location.\nBioconductor git server allow -f force push \ngit.bioconductor.org location. Please email bioc-devel@r-project.org\nexplaining package cleaned large data files needs \nreset.Request updates git.bioconductor.org repository location.Bioconductor git server allow -f force push \ngit.bioconductor.org location. Please email bioc-devel@r-project.org\nexplaining package cleaned large data files needs \nreset.","code":"java -jar /bfg-1.13.0.jar --strip-blobs-bigger-than 100M cd \ngit reflog expire --expire=now --all && git gc --prune=now --aggressivegit push -f origin"},{"path":"git-version-control.html","id":"faq","chapter":"21 Git Version Control","heading":"21.9 Frequently Asked Question (FAQs)","text":"can’t access package.\nneed log BiocCredentials application. \nlogged , must first activate account.\ntwo steps,\nSSH key registered, must add one.\nalready SSH key registered, check packages \naccess ‘Profile’ interface.\ncan alternatively check access package\nusing command line\n ssh -T git@git.bioconductor.org\naccess package, git pull push,\nplease check FAQ #13, #14, #15.can’t access package.need log BiocCredentials application. \nlogged , must first activate account.two steps,SSH key registered, must add one.SSH key registered, must add one.already SSH key registered, check packages \naccess ‘Profile’ interface.already SSH key registered, check packages \naccess ‘Profile’ interface.can alternatively check access package\nusing command lineIf access package, git pull push,\nplease check FAQ #13, #14, #15.’m developer Bioconductor, package ExamplePackage \nnew server https://git.bioconductor.org. next?\nTake look Maintain GitHub Bioconductor repositories.\ngive information needed.\nNOTE: situation packages previously\nmaintained SVN never accessed GIT. \nnewly accepted packages Github.’m developer Bioconductor, package ExamplePackage \nnew server https://git.bioconductor.org. next?Take look Maintain GitHub Bioconductor repositories.\ngive information needed.NOTE: situation packages previously\nmaintained SVN never accessed GIT. \nnewly accepted packages Github.GitHub repository already set Bioconductor\npackage www.github.com// , \nlink repository GitHub https://git.bioconductor.org ?\nTake look New package workflow. Step 2 gives \ninformation add remote link GitHub \nBioconductor repositories.GitHub repository already set Bioconductor\npackage www.github.com// , \nlink repository GitHub https://git.bioconductor.org ?Take look New package workflow. Step 2 gives \ninformation add remote link GitHub \nBioconductor repositories.’m unable push merge updates GitHub\nrepository Bioconductor package \ngit@git.bioconductor.org, go ?\nunable push merge either GitHub\naccount Bioconductor repository, means \ncorrect access rights. developer Bioconductor,\nneed submit SSH public key \nBiocCredentials app.\nalso make sure check public key set \ncorrectly GitHub. Follow\nAdding new SSH key GitHub account.’m unable push merge updates GitHub\nrepository Bioconductor package \ngit@git.bioconductor.org, go ?unable push merge either GitHub\naccount Bioconductor repository, means \ncorrect access rights. developer Bioconductor,\nneed submit SSH public key \nBiocCredentials app.also make sure check public key set \ncorrectly GitHub. Follow\nAdding new SSH key GitHub account.’m sure fetch updates git.bioconductor.org\nregards package, ?\nTake look Sync existing repositories. give \ninformation needed.’m sure fetch updates git.bioconductor.org\nregards package, ?Take look Sync existing repositories. give \ninformation needed.’m just package user, need ?\npackage user, need developer\nrelated documentation. Although, good primer want\ncontributor Bioconductor.\ncan also open Pull requests issues \nBioconductor packages use, GitHub\nrepository.’m just package user, need ?package user, need developer\nrelated documentation. Although, good primer want\ncontributor Bioconductor.can also open Pull requests issues \nBioconductor packages use, GitHub\nrepository.’m new git GitHub, learn?\nmany resources can learn git GitHub.\ngit--github-learning-resources\ngit-scm\nGuides\n’m new git GitHub, learn?many resources can learn git GitHub.git--github-learning-resourcesgit-scmGuidesI’m Bioconductor package maintainer, don’t access \nBioconductor server packages maintained. \ngain access?\nPlease submit SSH public key using BiocCredentials\napp. key added server get\nread+ write access package.\ndevelopers Bioconductor packages required ,\ndon’t already access. Please identify packages\nneed read/write access email.’m Bioconductor package maintainer, don’t access \nBioconductor server packages maintained. \ngain access?Please submit SSH public key using BiocCredentials\napp. key added server get\nread+ write access package.developers Bioconductor packages required ,\ndon’t already access. Please identify packages\nneed read/write access email.relationship origin upstream remote?\ngit lingo origin just default name remote\nrepository originally cloned. might equally\ncalled another name. recommend origin \nset developers GitHub repository.\nSimilarly, upstream name remote hosted\nBioconductor server.\nimportant changes/updates \norigin equal upstream, words, want\ntwo remotes sync.\nFollow Sync existing repositories details \nachieve .\nImage explaining GitHub Bioconductor relationship \ndeveloper\nrelationship origin upstream remote?git lingo origin just default name remote\nrepository originally cloned. might equally\ncalled another name. recommend origin \nset developers GitHub repository.Similarly, upstream name remote hosted\nBioconductor server.important changes/updates \norigin equal upstream, words, want\ntwo remotes sync.Follow Sync existing repositories details \nachieve .Image explaining GitHub Bioconductor relationship \ndeveloperCan one upstream remote, yes, recommended?\ncan many remotes please. can \none remote name upstream. recommend \nremote origin set GitHub, upstream set \nBioconductor git server avoid confusion.Can one upstream remote, yes, recommended?can many remotes please. can \none remote name upstream. recommend \nremote origin set GitHub, upstream set \nBioconductor git server avoid confusion.Common names used scenario’s\ndeveloper: GitHub username, e.g., mine \nnturaga.\nBiocGenerics: used example demonstrate\ngit commands.\nExamplePackage: used place holder package\nname.\nSVN trunk git devel branch now development\nbranches.Common names used scenario’sdeveloper: GitHub username, e.g., mine \nnturaga.BiocGenerics: used example demonstrate\ngit commands.ExamplePackage: used place holder package\nname.SVN trunk git devel branch now development\nbranches.’m Bioconductor developer Bioconductor server. \n/want GitHub account. ?\nget Github account want\none. really good idea, maintain package\npublicly interact community via social coding\nfeatures available Github.\nhighlight Maintain Bioconductor-repositoryI’m Bioconductor developer Bioconductor server. \n/want GitHub account. ?get Github account want\none. really good idea, maintain package\npublicly interact community via social coding\nfeatures available Github.highlight Maintain Bioconductor-repositoryI push package. get error,\n $ git push origin devel\n fatal: remote error: FATAL: W packages/myPackage nobody DENIED fallthru\n (mis-spelled reponame)\n(might renamed origin remote upstream;\nsubstitute upstream origin. Check remote,\n $ git remote -v\n origin https://git.bioconductor.org/packages/myPackage.git (fetch)\n origin https://git.bioconductor.org/packages/myPackage.git (push)\ndeveloper using SSH protocol, \norigin remote HTTPS. Use\n git remote add origin git@git.bioconductor.org:packages/myPackage\nchange remote SSH protocol. Note : \nhost name SSH protocol, rather / HTTPS\nprotocol. Confirm remote updated correctly \ngit remote -v.\nremote correct still see message, \nSSH key invalid. See next FAQ.push package. get error,(might renamed origin remote upstream;\nsubstitute upstream origin. Check remote,developer using SSH protocol, \norigin remote HTTPS. Useto change remote SSH protocol. Note : \nhost name SSH protocol, rather / HTTPS\nprotocol. Confirm remote updated correctly \ngit remote -v.remote correct still see message, \nSSH key invalid. See next FAQ.sending question Bioc-devel mailing list \ngit, please check output following commands \ncorrectness can help better.\ndeveloper check make sure, using SSH \naccess protocol. Check output git remote -v \nconsistency. Include email bioc-devel, \nunsure. remote look like,\n origin git@git.bioconductor.org:packages/myPackage.git (fetch)\n origin git@git.bioconductor.org:packages/myPackage.git (push)\n\n origin git@github.com:/myPackage.git (fetch)\n origin git@github.com:/myPackage.git (push)\n upstream git@git.bioconductor.org:packages/myPackage.git (fetch)\n upstream git@git.bioconductor.org:packages/myPackage.git (push)\nCheck access bioc-git server\n(git@git.bioconductor.org), using ssh -T git@git.bioconductor.org. show list \npackages READ(R) WRITE(W) permissions. developer\nR W next package. based \nSSH public key using, default ssh authentication\nid_rsa.\n R admin/..*\n R packages/..*\n R admin/manifest\n R packages/ABAData\n R packages/ABAEnrichment\n R packages/ABSSeq\n R W packages/ABarray\n R packages/ACME\n R packages/ADaCGH2\n R packages/AGDEX\nsending question Bioc-devel mailing list \ngit, please check output following commands \ncorrectness can help better.developer check make sure, using SSH \naccess protocol. Check output git remote -v \nconsistency. Include email bioc-devel, \nunsure. remote look like,\n origin git@git.bioconductor.org:packages/myPackage.git (fetch)\n origin git@git.bioconductor.org:packages/myPackage.git (push)\n\n origin git@github.com:/myPackage.git (fetch)\n origin git@github.com:/myPackage.git (push)\n upstream git@git.bioconductor.org:packages/myPackage.git (fetch)\n upstream git@git.bioconductor.org:packages/myPackage.git (push)developer check make sure, using SSH \naccess protocol. Check output git remote -v \nconsistency. Include email bioc-devel, \nunsure. remote look like,orCheck access bioc-git server\n(git@git.bioconductor.org), using ssh -T git@git.bioconductor.org. show list \npackages READ(R) WRITE(W) permissions. developer\nR W next package. based \nSSH public key using, default ssh authentication\nid_rsa.\n R admin/..*\n R packages/..*\n R admin/manifest\n R packages/ABAData\n R packages/ABAEnrichment\n R packages/ABSSeq\n R W packages/ABarray\n R packages/ACME\n R packages/ADaCGH2\n R packages/AGDEXCheck access bioc-git server\n(git@git.bioconductor.org), using ssh -T git@git.bioconductor.org. show list \npackages READ(R) WRITE(W) permissions. developer\nR W next package. based \nSSH public key using, default ssh authentication\nid_rsa.SSH key recognized different name?\nnamed SSH public key differently id_rsa \nsuggested ssh-keygen, may find useful set \n~/.ssh/config file machine. Simply make \n~/.ssh/config file exist, add,\n host git.bioconductor.org\n HostName git.bioconductor.org\n IdentityFile ~/.ssh/id_rsa_bioconductor\n User git\nexample, private key called id_rsa_bioconductor\ninstead id_rsa.\nmay find useful check BiocCredentials app see\nSSH key registered.SSH key recognized different name?named SSH public key differently id_rsa \nsuggested ssh-keygen, may find useful set \n~/.ssh/config file machine. Simply make \n~/.ssh/config file exist, add,example, private key called id_rsa_bioconductor\ninstead id_rsa.may find useful check BiocCredentials app see\nSSH key registered.SSH key asking password don’t know ? \nretrieve ?\npossibilities ,\nset password. bioc-devel mailing list help\n. submit new key \nBiocCredentials app.\npermissions SSH key wrong. Verify \npermissions SSH IdentityFile 400. SSH reject, \nclearly explicit manner, SSH keys readable. \njust look like credential rejection. solution, \ncase, (SSH key bioconductor called id_rsa):\n chmod 400 ~/.ssh/id_rsa\nwrong remote set , please check git remote -v\nmake sure SSH access protocol used. bioc-git\nserver remote, \ngit@git.bioconductor.org:packages/myPackage.\nSSH key asking password don’t know ? \nretrieve ?possibilities ,set password. bioc-devel mailing list help\n. submit new key \nBiocCredentials app.set password. bioc-devel mailing list help\n. submit new key \nBiocCredentials app.permissions SSH key wrong. Verify \npermissions SSH IdentityFile 400. SSH reject, \nclearly explicit manner, SSH keys readable. \njust look like credential rejection. solution, \ncase, (SSH key bioconductor called id_rsa):\n chmod 400 ~/.ssh/id_rsaThe permissions SSH key wrong. Verify \npermissions SSH IdentityFile 400. SSH reject, \nclearly explicit manner, SSH keys readable. \njust look like credential rejection. solution, \ncase, (SSH key bioconductor called id_rsa):wrong remote set , please check git remote -v\nmake sure SSH access protocol used. bioc-git\nserver remote, \ngit@git.bioconductor.org:packages/myPackage.wrong remote set , please check git remote -v\nmake sure SSH access protocol used. bioc-git\nserver remote, \ngit@git.bioconductor.org:packages/myPackage.Can create push new branches repository git.bioconductor.org?\n. Maintainers access devel current RELEASE_X_Y.\nNew branches created pushed bioconductor server. \nrecommend maintainers additional branches Github repository\nmaintaining one.Can create push new branches repository git.bioconductor.org?. Maintainers access devel current RELEASE_X_Y.\nNew branches created pushed bioconductor server. \nrecommend maintainers additional branches Github repository\nmaintaining one.can fix duplicate commits issue find required\ndocumentation?\ndetailed documentation resolve duplicate commits\ncan found link.can fix duplicate commits issue find required\ndocumentation?detailed documentation resolve duplicate commits\ncan found link.","code":" ssh -T git@git.bioconductor.org $ git push origin devel\n fatal: remote error: FATAL: W any packages/myPackage nobody DENIED by fallthru\n (or you mis-spelled the reponame) $ git remote -v\n origin https://git.bioconductor.org/packages/myPackage.git (fetch)\n origin https://git.bioconductor.org/packages/myPackage.git (push) git remote add origin git@git.bioconductor.org:packages/myPackage origin git@git.bioconductor.org:packages/myPackage.git (fetch)\n origin git@git.bioconductor.org:packages/myPackage.git (push) origin git@github.com:/myPackage.git (fetch)\n origin git@github.com:/myPackage.git (push)\n upstream git@git.bioconductor.org:packages/myPackage.git (fetch)\n upstream git@git.bioconductor.org:packages/myPackage.git (push) R admin/..*\n R packages/..*\n R admin/manifest\n R packages/ABAData\n R packages/ABAEnrichment\n R packages/ABSSeq\n R W packages/ABarray\n R packages/ACME\n R packages/ADaCGH2\n R packages/AGDEX host git.bioconductor.org\n HostName git.bioconductor.org\n IdentityFile ~/.ssh/id_rsa_bioconductor\n User git chmod 400 ~/.ssh/id_rsa"},{"path":"git-version-control.html","id":"more-questions","chapter":"21 Git Version Control","heading":"21.9.0.1 More questions?","text":"additional questions answered already,\nplease send email bioc-devel@bioconductor.org.","code":""},{"path":"git-version-control.html","id":"helpful-resources","chapter":"21 Git Version Control","heading":"21.9.1 Helpful resources:","text":"Adding new SSH key GitHub accountCreate pull request GitHubCreate issue GitHubGit GitHub learning resourcesgit-scm manualGitHub GuidesNew package workflowMaintain GitHub Bioconductor repositoriesMaintain Bioconductor-repositorySync existing repositoriesAdding SSH key GitHub accountsubmit SSH public keyresolve duplicate commitsPull requestsOpen github issues","code":""},{"path":"versionnum.html","id":"versionnum","chapter":"22 Version Numbering","heading":"22 Version Numbering","text":"Bioconductor packages version number x.y.z format.Examples good version numbers:","code":"1.2.3\n0.99.5\n2.3.0\n3.12.44"},{"path":"versionnum.html","id":"even-odd-schedule","chapter":"22 Version Numbering","heading":"22.1 Even Odd Schedule","text":"Bioconductor ‘devel’ branch new features introduced,\nrelease branches created twice per year. Given package \nversion number x.y.z,y odd number devel.y even number release.regular development new featuresAuthors increment z version package ‘devel’\nbranch 1 GIT commit, e.g., 1.1.0 1.1.1, 1.1.2,\n…, 1.1.10, 1.1.11Any bug fixes ported release branch similarly\nincremented, 1.0.1, 1.0.2, …Changes made GIT without corresponding version bump \npropagate repository visible BiocManager::install().time release, Bioconductor team arranges :Create release branch package version: x . (y+1) . (z-z)Increment devel branch package version : x . (y+2) . (z-z)special case, package version x.99.z bumped \n(x+1) . 0 . (z-z) release, (x+1) . 1 . 0 devel.\nThus authors wishing signify major change package set y\n99 devel package.","code":""},{"path":"versionnum.html","id":"new-packages","chapter":"22 Version Numbering","heading":"22.2 New packages","text":"New packages submitted Bioconductor set Version: 0.99.0 \nDESCRIPTION file. Specifying y=99 triggers bump x next release\ncase results version 1.0.0.See additional details Package Submission page.See also instructions Using Bioc Devel.","code":""},{"path":"versionnum.html","id":"example-cases","chapter":"22 Version Numbering","heading":"22.3 Example Cases","text":"Normal Case. Suppose package devel branch version\nnumber 1.1.25. new release branch now contains copy \npackage version 1.2.0. devel branch Bioconductor\ncontains package whose version number bumped \n1.3.0Normal Case. Suppose package devel branch version\nnumber 1.1.25. new release branch now contains copy \npackage version 1.2.0. devel branch Bioconductor\ncontains package whose version number bumped \n1.3.0Special Case. “0.99.2” version package copied \nBioconductor team release branch version number\n1.0.0. package version bumped 1.1.0 devel\nbranch.Special Case. “0.99.2” version package copied \nBioconductor team release branch version number\n1.0.0. package version bumped 1.1.0 devel\nbranch.Examples version bumping scheme:","code":""},{"path":"versionnum.html","id":"summary","chapter":"22 Version Numbering","heading":"22.4 Summary","text":"summary version components bumped \nkey limitations. Bumps “release time” done Bioconductor\nteam package maintainer.x\n- modified Bioconductor team\n- bumped x+1 release time y=99\ny\n- must even release odd devel\n- must <=99\n- bumped release time packages next\neven number release next odd devel\nz\n- incremented sequentially regular package development\n- limitation size z\n- bumped release time 0 packages.","code":""},{"path":"troubleshooting-build-report.html","id":"troubleshooting-build-report","chapter":"23 Troubleshooting Build Report","heading":"23 Troubleshooting Build Report","text":"","code":""},{"path":"troubleshooting-build-report.html","id":"propagate","chapter":"23 Troubleshooting Build Report","heading":"23.1 How and when does the BBS pull? When will my changes propagate?","text":"Please remember daily builder pulls, installs, builds, checks package\nper day. process starts around 2:30 PM (14:30) EST everyday\n(.e., UTC−05:00).\nChanges pushed Bioconductor 2:30 reflected following\nday’s build report posted around 11:30 EST. build report \ntime stamp top page generated. Changes \n2:30 PM EST reflect day tomorrow, therefore\npossibly taking 36-48 hours. build reports \ndevel release show\npackage version commit id reflected build.\nlanding pages packages (e.g.,\nBiobase)\nupdated package installs/build/checks without ERROR; \npropagate broken packages. account different version \nlanding page pushed Bioconductor. Please also remember \npackage ALWAYS needs valid version bump propagate users.schedule software, data experiment, annotation, books, workflows can \nfound check results page. \norder changes included report, changes committed \nBioconductor git.bioconductor.org location morning listed day\nvalid version bump.","code":""},{"path":"troubleshooting-build-report.html","id":"how-do-i-reproduce-the-build-system-error","chapter":"23 Troubleshooting Build Report","heading":"23.2 How do I reproduce the build system ERROR?","text":"order reproduce ERROR’s accurately locally, remember using \ncorrect version R Bioconductor. version R used build\nreport can found top release \ndevel build reports. using \ncorrect version R make sure packages --date \nBiocManager::valid() BiocManager::install(). additional\nenvironment variables daily builder uses R CMD check.Devel Renviron.biocRelease Renviron.biocThe Single Package build extra\ndocumentation\nset local system use optional environment\nvariables. Please note look file listed page, \nmany additional variables; Bioconductor much stringent check \nincoming packages daily builder (now). welcome use\nfile wish comprehensive check listed\nenvironment variables included minimally.Another option debug test utilize Bioconductor docker\nimage. documentation using docker images can found\n. docker image contain \nenvironment variable setting found daily builder.","code":""},{"path":"troubleshooting-build-report.html","id":"common-build-report-errors","chapter":"23 Troubleshooting Build Report","heading":"23.3 Common Build Report Errors","text":"Often common Error’s arise R develops matures Bioconductor\npackages modified advance. document provides guidance Error’s\npotential solutions.Bioconductor 3.17 R 4.3Bioconductor 3.11 R 4.0","code":""},{"path":"troubleshooting-build-report.html","id":"bioc-317","chapter":"23 Troubleshooting Build Report","heading":"23.4 Bioconductor 3.17 with R 4.3","text":"Length = coercion logical(1)","code":""},{"path":"troubleshooting-build-report.html","id":"lenCoerc","chapter":"23 Troubleshooting Build Report","heading":"23.4.1 Length = coercion to logical(1)","text":"R 4.3, warning vector used statement increased \nERROR. :now :Solution:\ncases misjudgment length argument rather \nintentional use checking value assigned. code reviewed\nsee argument assigned correctly. cases simple\nsolution might use ( ) ( ) surrounding vector.","code":" x = c(TRUE,TRUE, FALSE)\n > if (x) 1\n [1] 1\n Warning message:\n In if (x) 1 :\n the condition has length > 1 and only the first element will be used > x = c(TRUE, TRUE, FALSE)\n > if (x) 1\n Error in if (x) 1 : the condition has length > 1"},{"path":"troubleshooting-build-report.html","id":"bioc-311","chapter":"23 Troubleshooting Build Report","heading":"23.5 Bioconductor 3.11 with R 4.0","text":"R switched 3.x 4.0 generally means significant changes.S3 method registrationRemoved Settings R CMD configConditional length > 1Scalar / Vector LogicClass == vs /inherits\nMatrix now Array\nMatrix now Arraydata.frame stringsAsFactorsstats::smoothEndsgrid package changesplot generic movedPartial Argument MatchingInvalid UTF-8Dependency IssuesDeprecated Functions","code":""},{"path":"troubleshooting-build-report.html","id":"s3method","chapter":"23 Troubleshooting Build Report","heading":"23.5.1 S3 method registration","text":"Many packages currently failing undeclared S3 methods \nNAMESPACE. background information found R developers blog\npost: S3 Method\nLookupThis ERROR takes many different forms build report. \ncommon forms includeCannot coerce class data.frameCannot coerce type ‘S4’ vector type ‘double’applicable method applied object \nclass ‘X’ list, components ‘x’ ‘y’Error colMeans(x, na.rm = TRUE) : ‘x’ must numericError RG\\[1:2, \\] : incorrect number dimensionsformal argument matched multiple actual argumentsobject mode ‘function’ found‘x’ ‘y’ lengths differSolution: Register S3 method NAMESPACEA simple example effects many packages S3 plotting method.\nfollowing line added package NAMESPACE.","code":"S3method(, )S3method(plot, TCC) # example from TCC package"},{"path":"troubleshooting-build-report.html","id":"rcmdconfig","chapter":"23 Troubleshooting Build Report","heading":"23.5.2 Removed Setting in R CMD config","text":"source ERROR utilizing settings package configure script \nremoved replaced.\nsection R NEWS “R CMD config longer knows unused\nsettings F77 FCPIFCPLAGS, CXX98 similar.”\nExecuting configuration script installing package fails, \noutput contains lot messages along lines following:configure: WARNING: flags FFLAGS=“” workchecking whether ERROR: information variable ‘F77’configure: WARNING: value FFLAGS work.Solution: Replace instances “${R} CMD config F77” “${R} CMD config FC”","code":""},{"path":"troubleshooting-build-report.html","id":"condLen","chapter":"23 Troubleshooting Build Report","heading":"23.5.3 Conditional Length > 1","text":"R 4.0 conditional length greater 1 produce WARNING. \nBioconductor Daily Builder Single Package Builder increased \nERROR.Traditionally / statements accept vectors using first\nelement conditional value ignoring remaining values. now\nproduces WARNING seem dummy example documented \nConditions Length Greater OneSolution:\nBioconductor increased severity cases misjudgment \nlength argument rather intentional. code reviewed\nsee argument assigned correctly. cases might \nappropriate use ( ) ( ) surrounding vector.See also mailing list\npost","code":"> if (c(TRUE, FALSE)) {}\nNULL\nWarning message:\nIn if (c(TRUE, FALSE)) { :\n the condition has length > 1 and only the first element will be used"},{"path":"troubleshooting-build-report.html","id":"scalarvec","chapter":"23 Troubleshooting Build Report","heading":"23.5.4 Scalar / Vector Logic","text":"change R yet notified forth coming\nescalated ERROR daily builders preparation. type\nERROR occurs misuse && ||. double && ||\nimply scalar comparison rather vector comparison singular &\n| expect. See dummy example :Solution:\ncases misjudgment misunderstanding use scalar\ncomparison vector comparison. Changing double && / || singular\n& / | generally sufficient vector comparison intended vector argument use \nappropriate ( ) ( ) surrounding vector result \nappropriate scalar comparison. Note: comparison conditional\nplease see section ; ( ) ( ) likely better alternative.See also mailing list post","code":"> c(TRUE, TRUE) && TRUE\nError in c(TRUE, TRUE) && TRUE :\n 'length(x) = 2 > 1' in coercion to 'logical(1)'"},{"path":"troubleshooting-build-report.html","id":"classEq","chapter":"23 Troubleshooting Build Report","heading":"23.5.5 Class == vs is/inherits","text":"isn’t change R / Bioconductor yet, strong discussion\naffects consequences code structure. better discussion\nexplanation can found think class(.) == *, think !sum class( x ) == \"foo\" avoided. can misleading classes extend classes. \nbetter option use ( x , \"foo\") inherits(x, \"foo\").also advised Bioconductor best practicesStarting R 4.0, matrix considered extension array.change along previous section regarding conditional length results\nmany errors users something along lines (class(m) == \"matrix\"); excellent example following \nappropriate change ((m, \"matrix\")) (inherits(m, \"matrix\")) \n(.matrix(m)).Another common ERROR now occurring change something similar\nfollowing:","code":"> m = matrix()\n> class(m)\n[1] \"matrix\" \"array\"\n\n> class(m) == \"matrix\"\n[1] TRUE FALSE\n> if ( class(m) == \"matrix\"){}\nError in if (class(m) == \"matrix\") { : the condition has length > 1Error in vapply(experiments(object), class, character(1)) :\n values must be length 1,\n but FUN(X[[4]]) result is length 2"},{"path":"troubleshooting-build-report.html","id":"stringsAsFactors","chapter":"23 Troubleshooting Build Report","heading":"23.5.6 data.frame stringsAsFactors","text":"R 4.0, default data.frame argument stringsAsFactors changed \nTRUE FALSE. changes causing breakage tests \nchecks particular factor levels constructing factor levels.\nERROR’s take many different forms. simple solution change add\nstringAsFactors=TRUE data.frame call, however maintainers may want\nre-evaluate code potential restructuring ease use.","code":""},{"path":"troubleshooting-build-report.html","id":"statsSmoothEnds","chapter":"23 Troubleshooting Build Report","heading":"23.5.7 stats::smoothEnds","text":"recent change stats::smoothEnds(), now returns integer vector \ninput integer vector. Previously return number vector.Example R 3.6.3Example 4.0.0This potential cause ERROR’s class type checked.","code":"> class(smoothEnds(c(401:403)))\n[1] \"integer\"\n> class(smoothEnds(c(401:403, 555L)))\n[1] \"numeric\"> class(smoothEnds(c(401:403)))\n[1] \"integer\"\n> class(smoothEnds(c(401:403, 555L)))\n[1] \"integer\""},{"path":"troubleshooting-build-report.html","id":"grid","chapter":"23 Troubleshooting Build Report","heading":"23.5.8 Grid package changes","text":"lot specifics changed notified \nemail. Important sections email follows:","code":" I am about to commit some internal changes to 'grid' units\n (for, in some cases, 100x speed-up of unit operations).\n A number of packages have already been fixed to work with these\n changes, but, according to my testing, the following CRAN\n packages will still fail R CMD check.\n Some of those are cascades ('armada', 'countToFPKM', and 'wilson'\n from 'ComplexHeatmap' - see below - and 'fingertipscharts' from 'lemon'\n and 'xpose' is actually a 'ggforce' problem), but all of the other\n package authors have been notified and several are already working on\n fixes.\n The most serious of those is 'ComplexHeatmap' because it causes multiple\n follow-on failures, the CRAN ones above and others on BioConductor:\n Again, the main package authors have been notified and the\n 'ComplexHeatmap' author is working on an update."},{"path":"troubleshooting-build-report.html","id":"plot","chapter":"23 Troubleshooting Build Report","heading":"23.5.9 plot generic moved","text":"plot generic moved graphics base. ERROR’s seen \nchange non specific can take many forms. ERROR’s see\nareorThe explanation given:","code":"Error in getGeneric(f, TRUE, envir, package) :\n no generic function found for 'plot'Error in as.double(y) :\n cannot coerce type 'S4' to vector of type 'double'\n “The namespace controls the search strategy for variables used by\n functions in the package. If not found locally, R searches the package\n namespace first, then the imports, then the base namespace and then the\n normal search path.\" as per\n https://cran.r-project.org/doc/manuals/r-devel/R-exts.html#Package-namespaces):\n\n CRAN and Bioconductor had a few packages that \"worked\" because the right\n plot() was found in the normal search path, but now fail because it's\n calling the one in base instead."},{"path":"troubleshooting-build-report.html","id":"partMatch","chapter":"23 Troubleshooting Build Report","heading":"23.5.10 Partial Argument Matching","text":"now strict checking argument matching regards partial\nargument matching. Best described following exampleNotice generic uses breaks setMethod uses break; \nexample partial argument match longer valid.Partial argument matching envoking functions also avoided \npart best practices. example","code":"setGeneric(“mycoolfunction”, function(object, breaks)\n standardGeneric(“mycoolfunction”)\nsetMethod(“mycoolfunction”,\n signature=c(object=”GRanges”, break=”GRanges”),\n )mycoolfunction <- function( x, myargum, secondarg ) { code }\n\nmycoolfunction(x=2, myar=1:2, second=3) # BAD Coding!\n\nmycoolfunction(x=2, myargum=1:2, secondarg=3) # Good Practice!"},{"path":"troubleshooting-build-report.html","id":"invalidUTF","chapter":"23 Troubleshooting Build Report","heading":"23.5.11 Package inputenc Error: Invalid UTF-8","text":"ERROR started appear tokay2 (windows) Spring 2020. sure\nexact source ERROR (change MiKTek, Change R, ?) \nsolution simple:Please place \\usepackage[utf8]{inputenc} beginning Sweave\nvignette right \\documentclass line.","code":""},{"path":"troubleshooting-build-report.html","id":"dep311","chapter":"23 Troubleshooting Build Report","heading":"23.5.12 Dependency Issues","text":"Dependency Issues can fall sub-categories:","code":""},{"path":"troubleshooting-build-report.html","id":"cran-binaries-not-available-for-r-4.0","chapter":"23 Troubleshooting Build Report","heading":"23.5.12.1 CRAN binaries not available for R 4.0","text":"fall cycle Bioconductor uses R-devel preparation new release \nR spring. always slightly disruptive cycle regards \npackage dependencies CRAN. CRAN next 6 months leading new release R\nmake binaries Windows MacOS available. become available \nBioconductor builders automatically add binaries. binaries \ncreated yet, unavailable result package available error. Bioconductor go extra efforts find work around install\npackages; available, added.\nSolution: Please patient!","code":""},{"path":"troubleshooting-build-report.html","id":"package-have-been-removed-from-cran","chapter":"23 Troubleshooting Build Report","heading":"23.5.12.2 Package have been removed from CRAN","text":"CRAN packages occasionally removed. Unfortunately, Bioconductor \nallow package dependencies actively maintained packages CRAN Bioconductor.\npackage alter package utilize code rely \ndependency. may course try petition CRAN reinstatement reach\npackage maintainer fix submit CRAN. Good Luck!","code":""},{"path":"troubleshooting-build-report.html","id":"package-has-been-removed-from-bioconductor","chapter":"23 Troubleshooting Build Report","heading":"23.5.12.3 Package has been removed from Bioconductor","text":"try aware orphaned packages packages remain broken \nextended periods time. Package deprecation removal occurs packages\nalter utilize code packages potential\noffer take maintenance broken packages require original\nmaintainers permission. Bioconductor Package deprecation announced throughout\nrelease cycle mailing list support site try allow dependent\npackages time adjust code removal. release \nnotable maintainer requested deprecation 3.10 (therefore removed 3.11) \nSNPchip GenomeGraphs. full list deprecated packages can found\nList Deprecated Packages 3.10.\nalso documented removed packages Removed Package Page","code":""},{"path":"troubleshooting-build-report.html","id":"system-requirement-missing-in-the-bioconductor-build-system","chapter":"23 Troubleshooting Build Report","heading":"23.5.12.4 System Requirement missing in the Bioconductor Build System","text":"package may fail build check Bioconductor Build System (BBS)\npackage dependencies System Requirement \navailable BBS.instance, first Bioconductor package suggested installation \narchive\nCRAN package, pass checks BBS. build report stated \n“archive package found”, however package present\nCRAN months. archive package reports among system requirements\nlibarchive library, BBS library installed.happen miss system dependency BBS, please open issue similar\nBBS issue #220, \nmention Bioconductor package either directly indirectly\nsystem requirement, possible provide information missing\npackage need installed. follow pull requests related\nissue, see solution installation \nlibarchive-dev package, BBS Bioconductor docker images.","code":""},{"path":"troubleshooting-build-report.html","id":"depFun311","chapter":"23 Troubleshooting Build Report","heading":"23.5.13 Deprecated Functions","text":"Functions can deprecated, defunct, eventually removed. Bioconductor tries\nenforce progression allow maintainers adjust code. deprecated\ndefunct functions () suggest alternative. following \nnoted Bioconductor 3.11","code":""},{"path":"troubleshooting-build-report.html","id":"rangeddata","chapter":"23 Troubleshooting Build Report","heading":"23.5.13.1 RangedData","text":"","code":"Error : RangedData objects are defunct. Please migrate your code to use GRanges\n or GRangesList objects instead. See IMPORTANT NOTE in ?RangedData"},{"path":"troubleshooting-build-report.html","id":"normalize","chapter":"23 Troubleshooting Build Report","heading":"23.5.13.2 Normalize","text":"","code":"Error:\n'normalize' is defunct.\nUse ''normalize,SingleCellExperiment-method' is defunct.\nUse 'logNormCounts' instead' instead."},{"path":"troubleshooting-build-report.html","id":"calculateqcmetrics","chapter":"23 Troubleshooting Build Report","heading":"23.5.13.3 calculateQCMetrics","text":"","code":"Error:\n'calculateQCMetrics' is defunct.\nUse 'perCellQCMetrics' instead."},{"path":"debugging-cc-code.html","id":"debugging-cc-code","chapter":"24 Debugging C/C++ code","heading":"24 Debugging C/C++ code","text":"following applies non-Windows operating systems. \nfaint heart, requires C-level familiarity.learn better visually, see video Bioconductor\nalum using gdb debug R packages native code.benefit diagnose--crash Case\nstudy examples steps logic written\n; one need rewind video review steps.","code":""},{"path":"debugging-cc-code.html","id":"set-up","chapter":"24 Debugging C/C++ code","heading":"24.1 Set-up","text":"first, essential, step write short script reliably \nquickly reproduces error. Call script buggy.R.debugging package code C/C++ level, one usually starts \ninstalling package without compiler optimizations, e.g., \nfollowingsection 6.3.3. setting instancein .R/Makevars. See relevant Package Guidelines\nsection examples information.","code":"RShowDoc(\"R-admin\")CFLAGS=-ggdb -O0"},{"path":"debugging-cc-code.html","id":"detecting-memory-errors-valgrind","chapter":"24 Debugging C/C++ code","heading":"24.2 Detecting memory errors (Valgrind)","text":"Valgrind mature suite tools \nlow-level program analysis. Valgrind’s memory error checker\n(Memcheck) \npremier tool diagnosing C/C++ memory errors.Valgrind can used spot memory access problems, \ncommon source segfaults C/C++ code. bug isolated \neasily produced buggy.R, start R :runs quite slowly, flag invalid memory read write\nlocations. former typically contribute bad data, latter \nmemory corruption spectacular failures. output require C\nfamiliarity interpret. helpful run buggy code \npackage installed without compiler optimizations. See\nsection 4.3 RShowDoc(\"R-exts\") relevant Package Guidelines\nsection.","code":"R -d valgrind -f buggy.R"},{"path":"debugging-cc-code.html","id":"interactive-debugging-gdb-or-lldb","chapter":"24 Debugging C/C++ code","heading":"24.3 Interactive debugging (gdb or lldb)","text":"never used command-line debugger, many fine\nquick-start guides web; daunting seems.Linux preferred debugger gdb, lldb default Mavericks\nplatform. interfaces similar, accustomed \ngdb, see gdb lldb command map.Start R C-level debugger gdb.’ll end gdb promptand typical operation (r)un (c)ontinue executionto run buggy.R. ’ll end back C segfault, \npress cntrl-C (^C, ), ’ve inserted \n(b)reakpoint C-level function suspect buggy, e.g.,end back debugger, can print C variables \nC representation R variables (provided R isn’t confused \npoint)can also view (b)ack(t)race call stack, navigate (u)p \n(d)call stack, etc. Seeand mutual friend Google additional information.","code":"R -d gdb -f buggy.R(gdb)(gdb) r> ^C\n(gdb) b some_buggy_fun\n(gdb) c(gdb) p c_var\n(gdb) call Rf_PrintValue(some_R_variable)(gdb) help"},{"path":"debugging-cc-code.html","id":"diagnose-a-crash","chapter":"24 Debugging C/C++ code","heading":"24.3.1 Finding clues for causes of a program crash","text":"Perhaps useful function debuggers provide \nbreadcrumb trail (“backtrace”) routines led crash\nbuggy program. knowledge can narrow inquiry \ncode affects parts program state relevant time \ncrash.worth reiterating essential optimizations turned\ncompiler instructed include debugging symbols one\nhopes fruitful debugging session. See relevant Package\nGuidelines section.Though debugger output example may differ slightly compared\noutput computing environments, underlying techniques\napply diagnosing program crashes platform. See Case\nstudy real-world example uses Valgrind \ngdb conjunction.use contrived example demonstrate identify\npotential places code cause crash. able \nuse example files exactly appear. extraneous output\nomitted brevity.particular example uses lldb code compiled clang \nMavericks. example lead program crash Linux\nGCC clang.C++ file buggy.cpp:Compile R CMD SHLIB buggy.cpp -o buggy..source()ing file (buggy.R) within R session (entering\ncommands R session) lead program crash:Unfortunately R’s diagnostics illuminating:Now turn debugger. Start R lldb debugger (\nequivalent platform):point R crashes, lldb produces output, back\nlldb prompt. lldb output looks like (showing us \nframe (#0) call stack crash occurred):looks like debugger telling us memory access\nerror fetching tree node. (Trees common underlying data\nstructure standard library map). output voluminous\nlooks confusing, gist important right now.Still lldb session, enter bt command (\n“backtrace”) lldb prompt see stack frames (\nfunction calls) preceded crash. Frames listed \nascending order, starting frame crash\nhappened. (Note frame #0 frame #0 given .)\nmeans diagnosing crash, usually makes sense start\nlower-numbered frames proceed upwards.frame #5 mentions do_dotcall, native function (\nR library) corresponds .Call(\"buggy_function\") line \nbuggy.R call C entry point. can reasonably conclude\nuseful information bug probably frames #0-4.possible chain thought leads right conclusion:frames #0-2 look like dealing tree/map internals;\nignore moment.frames #0-2 look like dealing tree/map internals;\nignore moment.frame #3 indicates probably talking map\nconst_iterator variable declared line #14 buggy.cpp\n(std::map::const_iterator = m.begin();).frame #3 indicates probably talking map\nconst_iterator variable declared line #14 buggy.cpp\n(std::map::const_iterator = m.begin();).frame #4 key: tells us line (#17) buggy.cpp file\n(++;) execution went C++ code wrote \nmap iterator internals produced error.frame #4 key: tells us line (#17) buggy.cpp file\n(++;) execution went C++ code wrote \nmap iterator internals produced error.Eureka! carefully reading code buggy.cpp realize\ninserts size map m 2. means \nincrementing iterator line #16 (++;), value \nspecial\npast--end\nvalue. Incrementing iterator beyond past--end (third\n++; line #17) undefined\nbehavior!Eureka! carefully reading code buggy.cpp realize\ninserts size map m 2. means \nincrementing iterator line #16 (++;), value \nspecial\npast--end\nvalue. Incrementing iterator beyond past--end (third\n++; line #17) undefined\nbehavior!revise buggy.cpp increment beyond past--end\nremoving third ++; program runs without\ncomplaint. Problem solved!can see, debugger able immediately tell us \nprogram crashed, just program crashed. used \ninformation crash happened home parts \ncode affected program state relevant time \ncrash. Obviously example contrived; real-world scenario\nextra help afforded insight relevant program state \ninvaluable.","code":"#include \n#include \n#ifdef __cplusplus\n#define R_NO_REMAP\n#endif\n#include \n\nextern \"C\" SEXP buggy_function();\n\nSEXP buggy_function() {\n std::map m;\n m.insert(std::make_pair(5, 7));\n m.insert(std::make_pair(9, 42));\n std::map::const_iterator it = m.begin();\n ++it;\n ++it;\n ++it;\n\n return R_NilValue;\n}dyn.load(\"buggy.so\")\n.Call(\"buggy_function\")> source(\"buggy.R\")\n\n *** caught segfault ***\naddress 0x2, cause 'memory not mapped'\n\nTraceback:\n 1: .Call(\"buggy_function\")\n 2: eval(expr, envir, enclos)\n 3: eval(ei, envir)\n 4: withVisible(eval(ei, envir))\n 5: source(\"buggy.R\")R -d lldb\n(lldb) run\n## R startup messages elided\n## now in R session\n> source(\"buggy.R\")Process 21657 stopped\n* thread #1: tid = 0xbcb4ab, 0x00000001028fcbb0 buggy.so`buggy_function [inlined] std::__1::__tree_node_base* std::__1::__tree_min*>(std::__1::__tree_node_base*) at __tree:134, queue = 'com.apple.main-thread', stop reason = EXC_BAD_ACCESS (code=1, address=0x2)\n frame #0: 0x00000001028fcbb0 buggy.so`buggy_function [inlined] std::__1::__tree_node_base* std::__1::__tree_min*>(std::__1::__tree_node_base*) at __tree:134\n 131 _NodePtr\n 132 __tree_min(_NodePtr __x) _NOEXCEPT\n 133 {\n-> 134 while (__x->__left_ != nullptr)\n 135 __x = __x->__left_;\n 136 return __x;\n 137 }(lldb) bt\n* thread #1: tid = 0xbcb4ab, 0x00000001028fcbb0 buggy.so`buggy_function [inlined] std::__1::__tree_node_base* std::__1::__tree_min*>(std::__1::__tree_node_base*) at __tree:134, queue = 'com.apple.main-thread', stop reason = EXC_BAD_ACCESS (code=1, address=0x2)\n * frame #0: 0x00000001028fcbb0 buggy.so`buggy_function [inlined] std::__1::__tree_node_base* std::__1::__tree_min*>(std::__1::__tree_node_base*) at __tree:134\n frame #1: 0x00000001028fcbb0 buggy.so`buggy_function [inlined] std::__1::__tree_node_base* std::__1::__tree_next*>(std::__1::__tree_node_base*) + 20 at __tree:158\n frame #2: 0x00000001028fcb9c buggy.so`buggy_function [inlined] std::__1::__tree_const_iterator, std::__1::__tree_node, void*>*, long>::operator++() at __tree:747\n frame #3: 0x00000001028fcb9c buggy.so`buggy_function [inlined] std::__1::__map_const_iterator, std::__1::__tree_node, void*>*, long> >::operator++() at map:750\n frame #4: 0x00000001028fcb9c buggy.so`buggy_function + 188 at buggy.cpp:17\n frame #5: 0x0000000100073a13 libR.dylib`do_dotcall(call=, op=, args=, env=) + 323 at dotcode.c:578"},{"path":"debugging-cc-code.html","id":"case-study","chapter":"24 Debugging C/C++ code","heading":"24.4 Case study","text":"case study, colleague reported complicated program\n, one particular computer, produce segmentation fault \njust stop responding. series actions wouldn’t cause\nproblems computers. sounds like classic memory\nproblem, segfault difficulty reproduction.first advice develop simple script reproduced \nproblem: original report many moving parts. big insight\nbug produced running part code \nuses RCurl, followed call garbage collector, gc(). \nrole garbage collector suggests memory corruption \nsort, particular perhaps RCurl allocating (C\nlevel) R object properly PROTECT’ing garbage\ncollection. suspect RCurl rather R libcurl (possible\nplayers) least tested code. \nwrong, course… many iterations, colleague arrived \nbuggy24.R:pretty simple, doesn’t require access special\nresources (like server originally queried). \nscript doesn’t cause segfault run systems, running\nvalgrind (installed RCurl without optimizations) shows…Look around C source code RCurl’s curl.c, suggested \nbacktrace, just get oriented. doto run script gdb. Run test scriptNo error. Don’t give , set break pointand run againThat ‘file’ means gdb doesn’t know find \nRCurl package src/ directory, tell (l)ist context, \n(p)rint value C variable isProtected, seems \nsource valgrind warningisProtected value (!), furthermore value \nFALSE results PROTECT’ing object el across C calls (\nR_PreserveObject ). pretty interesting, \n’re aware garbage collection triggers segfault. valgrind \ntelling us value isProtected isn’t actually result\nassignment, result accessing array \nbounds. Let’s head call stack see value \ncoming fromWe’re entering function getCurlPointerForData value\nLOGICAL(isProtected)[ % n ]. , isProtected now R\nobject, C variable. Looking surrounding code, % n doesn’t look right – ’s probably meant recycle isProtected\ncase shorter logical variable provided \nvector elements requiring protection, value n \nnecessarily length isProtected. Let’s look \n’ve got, using C-level R function Rf_PrintValue print R\nvalues (SEXP’s) R fashionisProtected logical vector length 1.…’re trying access element 1 . C\nrepresentation R vectors zero-based, valid value \nindex 0 – ’re bounds! well bug, \n’s time try fixing (naively,\nLOGICAL(isProtected)[ % LENGTH(isProtected) ]) confirm \ndiagnosis, report packageDescription(\"RCurl\")$Maintainer\nmight better sense overall structure intention\ncode.","code":"\nlibrary(RCurl)\n\nfoo <- function() {\n url <- \"https://google.com\"\n curl <- getCurlHandle()\n opts <- list(followlocation=NULL, ssl.verifypeer=TRUE)\n d <- debugGatherer()\n getURL(url,customrequest=\"GET\",curl=curl,debugfunction=d$update,.opts=opts)\n}\n\nexecute <- function() {\n foo()\n gc()\n}\n\nexecute()> R -d valgrind -f buggy24.R\n...\n==10859== Conditional jump or move depends on uninitialised value(s)\n==10859== at 0x11BF00F6: getCurlPointerForData (curl.c:798)\n==10859== by 0x11BF0E80: R_curl_easy_setopt (curl.c:164)\n==10859== by 0x11BF17AD: R_curl_easy_perform (curl.c:89)\n==10859== by 0x4ED5499: do_dotcall (dotcode.c:588)\n==10859== by 0x4F1CAA4: Rf_eval (eval.c:593)\n==10859== by 0x4F2BD5C: do_set (eval.c:1828)\n==10859== by 0x4F1C8B7: Rf_eval (eval.c:567)\n==10859== by 0x4F2B957: do_begin (eval.c:1514)\n==10859== by 0x4F1C8B7: Rf_eval (eval.c:567)\n==10859== by 0x4F297E9: Rf_applyClosure (eval.c:960)\n==10859== by 0x4F1CBA5: Rf_eval (eval.c:611)\n==10859== by 0x4F2BD5C: do_set (eval.c:1828)R -d gdb -f buggy24.R(gdb) r(gdb) b curl.c:798(gdb) r\nBreakpoint 1, getCurlPointerForData (el=0x79e038,\n option=CURLOPT_WRITEFUNCTION, isProtected=FALSE, curl=0x1d9bdc0)\n at curl.c:798\n798 curl.c: No such file or directory.\n(gdb)(gdb) dir ~/tmp/RCurl/src\n(gdb) l\n793 }\n794 }\n795 }\n796 break;\n797 case CLOSXP:\n798 (gdb) l\n793 }\n794 }\n795 }\n796 break;\n797 case CLOSXP:\n798 if(!isProtected) {\n799 R_PreserveObject(el);\n800 }\n801 ptr = (void *) el;\n802 break;\n(gdb) p isProtected\n$5 = FALSE(gdb) up\n#1 0x00007ffff426e273 in R_curl_easy_setopt (handle=0x15d9600,\n values=0x1445788, opts=0xf3d418, isProtected=0xb7d308, encoding=0x776db0)\n at curl.c:164\n164 val = getCurlPointerForData(el, opt, LOGICAL(isProtected)[ i % n ], obj);\n(gdb) l\n159 /* Loop over all the options we are setting. */\n160 for(i = 0; i < n; i++) {\n161 opt = INTEGER(opts)[i];\n162 el = VECTOR_ELT(values, i);\n163 /* Turn the R value into something we can use in libcurl. */\n164 val = getCurlPointerForData(el, opt, LOGICAL(isProtected)[ i % n ], obj);\n165\n166 if(opt == CURLOPT_WRITEFUNCTION && TYPEOF(el) == CLOSXP) {\n167 data->fun = val; useData++;\n168 status = curl_easy_setopt(obj, CURLOPT_WRITEFUNCTION, &R_curl_write_data);\n(gdb)(gdb) p isProtected\n$1 = (SEXP) 0xaad8a0\n(gdb) call Rf_PrintValue(isProtected )\n[1] FALSE(gdb) p i\n$7 = 1\n(gdb) p n\n$8 = 6\n(gdb) p i % n\n$9 = 1"},{"path":"deprecation.html","id":"deprecation","chapter":"25 Deprecation Guidelines","heading":"25 Deprecation Guidelines","text":"normal course software development, functions, classes, methods, \ndata objects may need removed. guidelines ensuring\nprocess minimally disruptive users.","code":""},{"path":"deprecation.html","id":"what-to-deprecate","chapter":"25 Deprecation Guidelines","heading":"25.1 What to Deprecate?","text":"function, class, method, data, even package longer used \nneeded.","code":""},{"path":"deprecation.html","id":"when-to-follow-these-guidelines","chapter":"25 Deprecation Guidelines","heading":"25.2 When to Follow These Guidelines?","text":"Note decide using function introduced\nwithin development cycle, may simply remove function\nwithout following standard function deprecation guidelines. expected\ndevel branch unstable subject API changes without notice\n(though may decide communicate changes users via \nBioconductor support site).However, function published least one release version\nBioconductor, guidelines must followed. process removing\nfeature function, class, method, exported package object\ntakes approximately three release cycles (18 months).","code":">|--- Bioconductor development cycle ---------------|>\n>|--- o feature introduced --- o feature removed ---|>>| Bioconductor RELEASE_X_Y | Bioconductor development cycle |>\n>|-- o feature introduced --|----- o feature removed --------|>"},{"path":"deprecation.html","id":"deprecate-function","chapter":"25 Deprecation Guidelines","heading":"25.3 How To Deprecate A Function","text":"","code":""},{"path":"deprecation.html","id":"step-1-deprecate-the-function","chapter":"25 Deprecation Guidelines","heading":"25.3.1 Step 1: Deprecate the function","text":"first decide deprecate function, mark \ndeprecated devel branch. calling .Deprecated()\ninside function. , must provide replacement function\nused place old function. Example:causes warning emitted whenever user calls\nmyOldFunc(). See ?.Deprecated information.Indicate man page old function \ndeprecated, suggest replacement function. sure old\nfunction called man page examples vignette code chunks; R\nCMD check report .","code":"myOldFunc <- function()\n{\n .Deprecated(\"myNewFunc\")\n ## use new function, or remainder of myOldFunc\n}\\name{MyPkg-deprecated}\n\\alias{MyPkg-deprecated}\n\\title{Deprecated functions in package \\sQuote{MyPkg}}\n\n\\description{\n These functions are provided for compatibility with older versions\n of \\sQuote{MyPkg} only, and will be defunct at the next release.\n}\n\n\\details{\n\n The following functions are deprecated and will be made defunct; use\n the replacement indicated below:\n \\itemize{\n\n \\item{myOldFunc: \\code{\\link{newFunc}}}\n\n }\n}"},{"path":"deprecation.html","id":"step-2-mark-the-function-as-defunct","chapter":"25 Deprecation Guidelines","heading":"25.3.2 Step 2: Mark the function as defunct","text":"next release cycle, function deprecated, \nmust made defunct devel branch. means call \nold function return informative error run \nadditional code. Example:See ?Defunct information.Remove documentation defunct function, add man\npage following:","code":"myOldFunc <- function()\n{\n .Defunct(\"myNewFunc\")\n}\\name{MyPkg-defunct}\n\\alias{myOldFunc}\n\\title{Defunct functions in package \\sQuote{pkg}}\n\\description{These functions are defunct and no longer available.}\n\n\\details{\n Defunct functions are: \\code{myOldFunc}\n}"},{"path":"deprecation.html","id":"step-3-remove-the-function","chapter":"25 Deprecation Guidelines","heading":"25.3.3 Step 3: Remove the function","text":"next release cycle, function marked defunct,\nremove entirely package R code NAMESPACE devel\nbranch. Also remove man page content documents function.Leave man page previous step place thatstill shows list defunct functions appropriate replacements.","code":"help(\"MyPkg-defunct\")"},{"path":"deprecation.html","id":"deprecate-dataset","chapter":"25 Deprecation Guidelines","heading":"25.4 How To Deprecate An S3 Dataset","text":"","code":""},{"path":"deprecation.html","id":"step-1---create-an-s3-deprecation-class","chapter":"25 Deprecation Guidelines","heading":"25.4.1 Step 1 - Create an S3 deprecation class","text":"initial step deprecating dataset signal users \ndataset longer used. Alert user warning message added \nprint method. , first add deprecation class dataset\nobject. Note class name arbitrary descriptive:serialize class R object can loaded \npackage:usethis:","code":"class(pkgDataset) <- c(\"DeprecatedData\", class(pkgDataset))save(pkgDataset, file = \"data/pkgDataset.rda\")usethis::use_data(pkgDataset, overwrite = TRUE)"},{"path":"deprecation.html","id":"step-2---create-a-print-method","chapter":"25 Deprecation Guidelines","heading":"25.4.2 Step 2 - Create a print method","text":"create print method new class print warning\nmessage:useful guide user replacement dataset functionality\nreplace data warning message. Note method\nexported package’s NAMESPACE file.","code":"print.DeprecatedData <- function(x, ...) {\n warning(\"'pkgDataset' dataset is deprecated; see '?newData'\")\n NextMethod()\n}"},{"path":"deprecation.html","id":"step-3---update-documentation","chapter":"25 Deprecation Guidelines","heading":"25.4.3 Step 3 - Update documentation","text":"dataset object saved, update documentation \nreflect changes provide additional details resources \nusers necessary. recommended include “[Deprecated]” label\ndata documentation title.","code":""},{"path":"deprecation.html","id":"step-4---defunct-the-dataset","chapter":"25 Deprecation Guidelines","heading":"25.4.4 Step 4 - Defunct the dataset","text":"following release cycle, upgrade warning message error\nmessage indicate longer available. data can \nremoved package. Remember update “[Deprecated]”\nlabel documentation title “[Defunct]”.","code":""},{"path":"deprecation.html","id":"how-to-deprecate-an-s4-dataset","chapter":"25 Deprecation Guidelines","heading":"25.5 How to Deprecate An S4 Dataset","text":"","code":""},{"path":"deprecation.html","id":"step-1---create-an-s4-deprecation-class","chapter":"25 Deprecation Guidelines","heading":"25.5.1 Step 1 - Create an S4 deprecation class","text":"S4, process similar S3, need create new class\ninherits original class setClass. class name \narbitrary descriptive:setClass call creates generator function can use\ncreate instance new class old object:serialize object disk can loaded \npackage:using usethis:","code":".DeprecatedData <-\n setClass(\"DeprecatedData\", contains = \"S4Class\")myS4DataObject <- .DeprecatedData(myS4DataObject)save(myS4DataObject, file = \"data/myS4DataObject.rda\")usethis::use_data(myS4DataObject, overwrite = TRUE)"},{"path":"deprecation.html","id":"step-2---create-a-show-method","chapter":"25 Deprecation Guidelines","heading":"25.5.2 Step 2 - Create a show method","text":"Create show method new class produce warning message:Note method exported package’s NAMESPACE \nshow generic imported methods package.Note steps 3 4 S3 datasets.","code":"setMethod(\"show\", \"DeprecatedData\", function(object) {\n warning(\"This dataset is deprecated; see '?newData'\")\n callNextMethod()\n})"},{"path":"deprecation.html","id":"deprecate-package","chapter":"25 Deprecation Guidelines","heading":"25.6 How to Deprecate a Package","text":"Please see section Package End Life Policy","code":""},{"path":"package-end-of-life-policy.html","id":"package-end-of-life-policy","chapter":"26 Package End of Life Policy","heading":"26 Package End of Life Policy","text":"Bioconductor project strives provide software repository \nstable relevant users across community. year 100-150 new\nsoftware packages added repository; Spring 2021 2000\npackages hosted. Bioconductor Build System (BBS) installs, builds, \nchecks software package every 24 hours. Regular execution example,\nvignette, unit test code ensures package operating expected \nrequired dependencies available. build system\nprovides detailed report package across three platforms: Linux,\nWindows, Mac.effort maintain high quality repository adopted \none-year end life (EOL) process packages longer pass\nbuild check active maintainer. Packages \nassessed EOL deprecation prior Bioconductor release; \nEOL policies apply software, annotation, workflow, experiment data\npackages.","code":""},{"path":"package-end-of-life-policy.html","id":"criteria-for-package-deprecation-by-core-team","chapter":"26 Package End of Life Policy","heading":"26.1 Criteria for package deprecation by Core Team","text":"R CMD build check errors one platforms\npackage must build check without error platforms\n(exceptions cross-platform builds available limited\ncircumstances) Bioconductor release. efforts \nmade keep package repository maintainer \nactively attempting fix.\npackage broken extended period time maintainer \ngiven final 2 week notice. package fixed end\n2 weeks, End Life started.R CMD build check errors one platformsThe package must build check without error platforms\n(exceptions cross-platform builds available limited\ncircumstances) Bioconductor release. efforts \nmade keep package repository maintainer \nactively attempting fix.package broken extended period time maintainer \ngiven final 2 week notice. package fixed end\n2 weeks, End Life started.Inactive maintainer\nmaintainer listed DESCRIPTION file must responsive \nquestions support site, package-related email users \nBioconductor team members, package-related errors build\nsystem, requests bug fixes. email DESCRIPTION must also\nremain valid, active email.Inactive maintainerThe maintainer listed DESCRIPTION file must responsive \nquestions support site, package-related email users \nBioconductor team members, package-related errors build\nsystem, requests bug fixes. email DESCRIPTION must also\nremain valid, active email.","code":""},{"path":"package-end-of-life-policy.html","id":"user-requested-deprecation","chapter":"26 Package End of Life Policy","heading":"26.2 User Requested Deprecation","text":"Alternatively, package maintainer may request package deprecation. \nmaintainer may number reasons deprecating package. \ncommon reasons include:longer wish maintain packageThey longer wish maintain packageThe package functionality superseded packagesThe package functionality superseded packagesThe package material become --date makes sense retire \npackage.package material become --date makes sense retire \npackage.Significant changes underlying technology e.g., web API, made\npackage unmaintainable.Significant changes underlying technology e.g., web API, made\npackage unmaintainable.ask maintainers wishing deprecate package send email\nnotification bioc-devel mailing list. core team \nensure necessary steps notifications can occur.","code":""},{"path":"package-end-of-life-policy.html","id":"end-of-life-process","chapter":"26 Package End of Life Policy","heading":"26.3 End of Life process","text":"Step : DeprecationPackages deprecated marked deprecation warning \npackage name strikethrough build report. warning \nemitted package loaded, reported package ‘landing\npage’. message alerts users package currently fails minimal\nbuild check criteria, package likely removed \nBioconductor next release.time 6 month period required criteria met (e.g., \npackage returns active maintenance, perhaps ‘adoption’ third\nparty) warning removed.Step II: DefunctWhen package gone one development cycle ‘deprecated’ without\nremedial action, package marked ‘Defunct’. package removed\nnightly build system, longer available \n‘BiocManager::install()’, current ‘landing page’.package remains available git archive, previous\nversions Bioconductor.Defunct packages re-enter Bioconductor repository except \nreview ‘new package’.Example:package identified deprecation Bioconductor release 3.2 /\ndevel 3.3 make following transitions:","code":"- deprecate in devel 3.3\n** Bioc Release **\n- deprecate in release 3.3 (i.e., no change in release status)\n- defunct in devel 3.4\n** Bioc Release **\n- defunct in release 3.4\n- gone in devel 3.5\n** Bioc Release **\n- gone in release 3.5"},{"path":"package-end-of-life-policy.html","id":"implementation-detail","chapter":"26 Package End of Life Policy","heading":"26.4 Implementation detail","text":"Notify bioc-devel mailing list maintainers packages\nDepending, Importing, Suggesting package package\ndeprecated. appropriate, indicate new maintainer\nwelcome take .Notify bioc-devel mailing list maintainers packages\nDepending, Importing, Suggesting package package\ndeprecated. appropriate, indicate new maintainer\nwelcome take .Add following code chunk ‘devel’ version package\nfile R/zzz.R, adjusting Bioconductor version \nversion current devel version.\n.onAttach <- function(libname, pkgname) {\n msg <- sprintf(\n \"Package '%s' deprecated removed Bioconductor\n version %s\", pkgname, \"3.4\")\n .Deprecated(msg=paste(strwrap(msg, exdent=2), collapse=\"\\n\"))\n}Add following code chunk ‘devel’ version package\nfile R/zzz.R, adjusting Bioconductor version \nversion current devel version.Add following annotation package DESCRIPTION file.\nPackageStatus: DeprecatedAdd following annotation package DESCRIPTION file.PackageStatus: DeprecatedThe package remains deprecated ‘devel’ branch 6\nmonths, time Bioconductor core\nteam members remove package ‘devel’ package manifest.package remains deprecated ‘devel’ branch 6\nmonths, time Bioconductor core\nteam members remove package ‘devel’ package manifest.","code":".onAttach <- function(libname, pkgname) {\n msg <- sprintf(\n \"Package '%s' is deprecated and will be removed from Bioconductor\n version %s\", pkgname, \"3.4\")\n .Deprecated(msg=paste(strwrap(msg, exdent=2), collapse=\"\\n\"))\n}"},{"path":"package-end-of-life-policy.html","id":"reversing-end-of-life-status","chapter":"26 Package End of Life Policy","heading":"26.5 Reversing End of Life Status","text":"deprecated package can un-deprecated removed End Life\nprocess fixed next Bioconductor release. \npackage un-deprecated, please contact maintainer@bioconductor.org. package\nalready defunct stage; package mostly likely requested \ngo new package submission process .","code":""},{"path":"package-end-of-life-policy.html","id":"orphaned-packages","chapter":"26 Package End of Life Policy","heading":"26.6 ‘Orphaned’ packages","text":"‘orphaned’ package Bioconductor package inactive \nnon-responsive maintainer. described , Bioconductor makes multiple\nefforts reach package maintainers fix broken packages. \nresponse maintainer emails sent core team, \npackage considered ‘orphaned’. Occasionally, members Bioconductor\ncommunity reach take maintenance ‘orphaned’ package. \ninterested replacement maintainer asked email original maintainer \nmaintainer@bioconductor.org, formally request permission take . Unless\nexplicit request package retired, Bioconductor \ngrant access interested replacement maintainer accordance open\nsource software licenses Bioconductor packages require \npackage naming policy maintainers agree upon submission.","code":""},{"path":"branch-rename-faqs.html","id":"branch-rename-faqs","chapter":"27 Branch Rename FAQs","heading":"27 Branch Rename FAQs","text":"Bioconductor project chosen ‘devel’ default branch \nGitHub git repositories. prepare transition, compiled \nlist Frequently Asked Questions (FAQs) instructions \nrename default branch local clones GitHub.","code":""},{"path":"branch-rename-faqs.html","id":"what-is-changing","chapter":"27 Branch Rename FAQs","heading":"27.1 What is changing?","text":"Bioconductor core team rename default branch ‘devel’ \nBioconductor git repository git.bioconductor.org. \nrepository clones including hosting platforms GitHub, GitLabs,\netc. directly affected core team’s change; however, \nhighly recommend maintainers developers update local cloud\nrepository clones match default branch name.","code":""},{"path":"branch-rename-faqs.html","id":"who-is-affected-by-this-change","chapter":"27 Branch Rename FAQs","heading":"27.2 Who is affected by this change?","text":"Bioconductor developers maintainers affected change.\nBioconductor users affected.","code":""},{"path":"branch-rename-faqs.html","id":"what-repositories-are-affected-by-this-change","chapter":"27 Branch Rename FAQs","heading":"27.3 What repositories are affected by this change?","text":"Note may exist several clones single repository, e.g., \ndifferent servers workstations. repository resides \nBioconductor server hosted git.bioconductor.org affected. \ndefault branch packages Bioconductor git server\nset devel. Maintainers collaborators responsible \nupdating local cloud repository clones.recommend synchronizing default branch changes GitHub-hosted\nrepository simplify workflows.typical setup scenarios, see tidyverse blog\npost.","code":""},{"path":"branch-rename-faqs.html","id":"what-do-i-need-to-change","chapter":"27 Branch Rename FAQs","heading":"27.4 What do I need to change?","text":"recommend Bioconductor developers rename default branches \nlocal repositories ‘devel’. Optionally (highly encouraged), GitHub\nlocal copies affected repositories, including \ncollaborators, branches renamed.Bioconductor users need anything.Note. minority maintainers without GitHub repository \nrename set ‘HEAD’ follows:maintainers GitHub repositories see sections \nset ‘devel’ default branch \nGitHub? set\n‘devel’ default local\n’branch?, respectively.","code":"git branch -m master devel\ngit fetch origin\ngit branch -u origin/devel devel\ngit remote set-head origin -a"},{"path":"branch-rename-faqs.html","id":"what-if-i-am-an-rstudio-user","chapter":"27 Branch Rename FAQs","heading":"27.5 What if I am an RStudio user?","text":"Maintainers use RStudio familiar running git commands\nvia Terminal tab RStudio. commands shown documentation\ncan entered Terminal tab, e.g., git fetch --obtain \nupdates available remotes.","code":""},{"path":"branch-rename-faqs.html","id":"what-if-i-create-a-fresh-clone-of-my-repository","chapter":"27 Branch Rename FAQs","heading":"27.6 What if I create a fresh clone of my repository?","text":"possible create fresh clone repository may lose\nworking changes old local repository. done \ncomfortable git like start afresh. also\nneed set git remotes \n.","code":""},{"path":"branch-rename-faqs.html","id":"what-should-my-git-remotes-look-like","chapter":"27 Branch Rename FAQs","heading":"27.7 What should my Git remotes look like?","text":"reminder, maintainers use GitHub following recommended\nsetup. command git remote -v display origin remote points\nGitHub location upstream remote points Bioconductor\ngit repository. example, set BiocGenerics:Note. maintainers, use SSH protocol remotes.","code":"git remote -v\n# origin git@github.com:Bioconductor/BiocGenerics (fetch)\n# origin git@github.com:Bioconductor/BiocGenerics (push)\n# upstream git@git.bioconductor.org:packages/BiocGenerics (fetch)\n# upstream git@git.bioconductor.org:packages/BiocGenerics (push)"},{"path":"branch-rename-faqs.html","id":"how-do-i-sync-my-git-remotes","chapter":"27 Branch Rename FAQs","heading":"27.8 How do I sync my Git remotes?","text":"making updates local branches, make sure remotes origin\nupstream sync :Note. commands run old local repository \napply freshly cloned repositories.","code":"git checkout master\ngit pull origin master\ngit pull upstream devel:master"},{"path":"branch-rename-faqs.html","id":"how-do-i-set-devel-as-the-default-branch-on-github","chapter":"27 Branch Rename FAQs","heading":"27.9 How do I set ‘devel’ as the default branch on GitHub?","text":"maintainers manage GitHub repositories like use streamlined\ncommands, recommend synchronizing default branch changes GitHub\nrepositories. end, GitHub provided convenient way rename \ndefault branch repository. First, go \nhttps://github.com/{username}/{repo}/branches \nusername repo correspond GitHub username repository,\nrespectively., click ‘edit’ pencil 🖊 rename branch (seen\nbottom right corner) rename branch ‘devel’:’s ! default branch GitHub now set devel.Follow instructions set ‘devel’ default local\nbranch? sync local\nrepository clones.","code":""},{"path":"branch-rename-faqs.html","id":"what-if-i-already-have-a-devel-branch-on-github","chapter":"27 Branch Rename FAQs","heading":"27.10 What if I already have a ‘devel’ branch on GitHub?","text":"Simply select “switch default branch” button (looks like exchange\narrows 🔄) top right “Default\nbranch” box navigating https://github.com/{username}/{repo}/branches\nusername repo correspond GitHub username repository,\nrespectively.","code":""},{"path":"branch-rename-faqs.html","id":"how-do-i-set-devel-as-the-default-local-branch","chapter":"27 Branch Rename FAQs","heading":"27.11 How do I set ‘devel’ as the default local branch?","text":"order keep commands simple avoid confusion, recommend making \ndefault branch changes GitHub repository. allows minimal\ncommands asto simply work without specifying additional parameters, (e.g., main:devel)\npushing GitHub Bioconductor.maintainers wish make changes GitHub well, recommend\nperforming rename operation \nGitHub first, \nperforming adjustment (rename) local branch(es).Note. step necessary cloned fresh copy \nBioconductor git server though re-specify origin \nupstream remotes (described )\nfresh copy.branch renamed GitHub, use GitHub-provided commands update\nlocal copy repository:Note. Change ‘master’ ‘main’ repository ‘main’ default\nbranch:","code":"git push origin\ngit push upstreamgit branch -m master devel\ngit fetch origin\ngit branch -u origin/devel devel\ngit remote set-head origin -agit branch -m main devel\ngit fetch origin\ngit branch -u origin/devel devel\ngit remote set-head origin -a"},{"path":"branch-rename-faqs.html","id":"how-do-i-push-to-bioconductor-after-renaming","chapter":"27 Branch Rename FAQs","heading":"27.12 How do I push to Bioconductor after renaming?","text":"push upstream Bioconductor, developer simply push \ndevel branch:","code":"## branch should already exist\ngit checkout devel\n#### \ngit push upstream devel"},{"path":"branch-rename-faqs.html","id":"clean-up-how-do-i-get-rid-of-stale-remote-tracking-branches","chapter":"27 Branch Rename FAQs","heading":"27.13 Clean up: How do I get rid of stale remote-tracking branches?","text":"rename, remain stale references origin remote.\nSee local remote branches git branch -:Run following get rid stale reference “master” origin\nremote:Note. Remove --dry-run option making sure correct\nremote reference listed.","code":"git branch -a\n# * devel\n# remotes/origin/HEAD -> origin/devel\n# [...]\n# remotes/origin/mastergit remote prune origin --dry-run"},{"path":"branch-rename-faqs.html","id":"what-if-i-have-a-gitlab-repository","chapter":"27 Branch Rename FAQs","heading":"27.14 What if I have a GitLab repository?","text":"possible also change default branch GitLab. See \nchange default branch instructions.\ncomplete, can update local repository similarly \ninstructions.","code":""},{"path":"reviewer-resources-overview.html","id":"reviewer-resources-overview","chapter":"Overview","heading":"Overview","text":"following sections contain resources package reviewers \ninterested becoming package reviewers. find reviewer expectations,\nuseful tools, volunteer community reviewer.also encourage communication conversation package review \ncommunity addition assigned reviewers: Packages Review. \npackage reviews publicly accessible, therefore feedback interactions \nsubmitted packages must abide Bioconductor Code Conduct.","code":""},{"path":"review-expectation.html","id":"review-expectation","chapter":"28 Review Expectations","heading":"28 Review Expectations","text":"Anyone Bioconductor community package Bioconductor can\nvolunteer become community reviewer assess incoming packages submitted\nNew Submission Tracker. following\noverviews expected community reviewers.QualificationsTime CommitmentAssignmentsExpectations deadlinesAccept Decline PackagesRequesting reassignment temporary leave assignmentOn-boardingRecognitionVolunteer","code":""},{"path":"review-expectation.html","id":"review-qualifications","chapter":"28 Review Expectations","heading":"Qualifications","text":"Actively maintaining Bioconductor package","code":""},{"path":"review-expectation.html","id":"review-time-commitment","chapter":"28 Review Expectations","heading":"Time commitment","text":"Package reviews can vary depending quality organization \nsubmitted package. average package review single package \n30 min - 1.5 hour.also plan quarterly “-hands” meeting currently active\nreviewers. meeting acquaint reviewers new\nrequirements, classes, checks activated CRAN BiocCheck, etc. also\nplace raise questions comments larger group perhaps point\nfrequently used comments (perhaps implemented automated\ncheck). Everyone ends slightly different review styles \nbeneficial discuss everyone finds priority. Every effort \nmade attend meetings expect reviewer attend least\nyear.","code":""},{"path":"review-expectation.html","id":"review-assignments","chapter":"28 Review Expectations","heading":"Assignments","text":"Packages assigned evenly randomly, community review\nengagement distributed currently anticipate package assigned \nevery week every 2 weeks. weeks leading Bioconductor\nrelease.‘Additional Package’/‘Circular dependency’ packages submitted occasionally.\nSubmitters allowed submit related packages issue. \noccurs, assigned reviewer responsible reviews \naccept issue packages accepted state.","code":""},{"path":"review-expectation.html","id":"review-expectations-and-deadlines","chapter":"28 Review Expectations","heading":"Expectations and deadlines","text":"Package[s] expected reviewed within 3 weeks assignment \nproduce clean build report build machine. plan make hard\nlimit 3 weeks. delay submitter, issue closed\ninactivity; reopened submitter can commit timely\nupdates engagement review process. delay reviewer,\nreassigned someone else. keep track many\nreassignments occur frequent reassignments (3-4 unexplained) \nremove reviewer person must reapply \nreactivated. Active reviewers expected review least 1 package per\nBioconductor release cycle. Otherwise removed active\nreviewer.","code":""},{"path":"review-expectation.html","id":"acceptdecline","chapter":"28 Review Expectations","heading":"Accept and Decline Packages","text":"general try work submitters get package \nstate acceptable inclusion Bioconductor regardless \nlong takes. willing take critiques open minded \nBioconductor requirements; work . reviewer truly feels \npackage qualify Bioconductor (applicability, coding\nstyle, etc) encounters difficult submitter (unwilling make changes,\naggressive, etc) , please reach package review administrators. \nadministrators make final determination official rejection \ntake review becomes uncomfortable.","code":""},{"path":"review-expectation.html","id":"review-reassignment-and-temporary-leave","chapter":"28 Review Expectations","heading":"Requesting reassignment and temporary leave of assignment","text":"temporary leave assigning packages needs occur (vacation,\nparticularly busy period time, etc), reviewer reach \npackage review committee administrator. administrator temporarily stop\nassignments can discuss currently assigned packages need re-assignment.reviewers slack channel package reviewers ask questions necessary\nask swap/switch/volunteer review packages. Requests can also made \ndirectly contacting package review administrator.Reviewers request reassignment simply lack interest \nlack expertise particular area. review focus ease--use\npackage, documentation, well written code, interoperability. \nreviewer knows particular ‘expert’ field relating submitted\npackage can request someone offer additional comments (including \nofficially part package review list) without explicitly asking \nreassignment.Frequent requests reassignment consider longer leave absence\nagreement package review administrator. frequent requests \nmade reassignement reviewer notified risk \nremoved active review process. reviewer removed, must\nreapply become active reviewer.","code":""},{"path":"review-expectation.html","id":"review-onboarding","chapter":"28 Review Expectations","heading":"On-boarding","text":"New volunteers undergo -boarding process becoming fully active\nreviewers. -boarding process involves least one paired review\ncurrently active reviewing member. Coordination paired review\ncommunicated mentor mentee. recommended practice\nseparate review currently submitted package \ncompare results. currently active member decide another\npaired review necessary review sufficient continue \nsolo reviews.","code":""},{"path":"review-expectation.html","id":"review-recognition","chapter":"28 Review Expectations","heading":"Recognition","text":"Feel free advertise CV resumes Bioconductor reviewer.\nReviewers also listed Community Reviewers Webpage. Reviewers\nmay optionally opt-listed webpage contacting package\nreview administrator. Ideally, plan badges notable achievements\nmilestones, sticker progress.","code":""},{"path":"review-expectation.html","id":"review-volunteer","chapter":"28 Review Expectations","heading":"Volunteer","text":"Refer chapter Volunteer Review details.","code":""},{"path":"reviewtools.html","id":"reviewtools","chapter":"29 Reviewer Resources and Tools","heading":"29 Reviewer Resources and Tools","text":"Reviewers may find following links references useful.","code":""},{"path":"reviewtools.html","id":"review-checklist","chapter":"29 Reviewer Resources and Tools","heading":"Package Review checklist","text":"Reviewers can download template review checklist .checklist can pasted relevant issue New Submission\nTracker, updated review progresses.","code":""},{"path":"reviewtools.html","id":"review-example","chapter":"29 Reviewer Resources and Tools","heading":"Example Review","text":"\nReview 1787: MAGAR\n\nReview 2090: HubPub\n\nReview 1229: BiocSet\n\nReview 1659: AnVILBilling\n\nReview 1671: AnVILPublish\n\nReview 311: AnnotationFilter\n\nReview 498: restfulSEData\n\nReview 1270: biscuiteerData/biscuiteer\n","code":""},{"path":"review-volunteer-chapter.html","id":"review-volunteer-chapter","chapter":"30 Volunteer to Review","heading":"30 Volunteer to Review","text":"Anyone Bioconductor community can volunteer become Bioconductor\ncommunity reviewer review incoming packages submitted New\nSubmission Tracker. Please review Reviewer\nExpectations Bioconductor Code Conduct filling \nvolunteer form.","code":""},{"path":"use-devel.html","id":"use-devel","chapter":"A Using the ‘Devel’ Version of Bioconductor","heading":"A Using the ‘Devel’ Version of Bioconductor","text":"","code":""},{"path":"use-devel.html","id":"which-version-of-r","chapter":"A Using the ‘Devel’ Version of Bioconductor","heading":"A.1 Which version of R?","text":"Package authors develop version R \navailable users Bioconductor devel branch becomes \nBioconductor release branch.R ‘.y’ release x.y.z every year (typically mid-April), \nBioconductor .y release (current devel becomes release)\nevery 6 months (mid-April mid-October).means , mid-October mid-April, Bioconductor\ndevelopers developing R-devel. mid-April \nmid-October, developers use R-release (actually, R snapshot\nR-x-y-branch) Bioconductor development.See BiocManager vignette instructions using multiple versions\nBioconductor.","code":""},{"path":"use-devel.html","id":"mid-april","chapter":"A Using the ‘Devel’ Version of Bioconductor","heading":"A.2 Using ‘bioc-devel’ during mid-April to mid-October","text":"order use ‘bioc-devel’ version Bioconductor \nmid-April mid-October release cycle, use release version R\ninvoke function install(version=\"devel\") (\nBiocManager package):, packages installed ‘bioc-devel’\nrepository.","code":"if (!requireNamespace(\"BiocManager\", quietly=TRUE))\n install.packages(\"BiocManager\")\nBiocManager::install(version = \"devel\")\nBiocManager::valid() # checks for out of date packages"},{"path":"use-devel.html","id":"mid-october","chapter":"A Using the ‘Devel’ Version of Bioconductor","heading":"A.3 Using ‘bioc-devel’ during mid-October to mid-April","text":"order use ‘bioc-devel’ version Bioconductor \nmid-October mid-April release cycle, must install devel\nversion R.SourcemacOSWindowsThen, make sure version BiocManager current \npackages --date.","code":"if (!requireNamespace(\"BiocManager\", quietly=TRUE))\n install.packages(\"BiocManager\")\nBiocManager::install(version=\"devel\")\nBiocManager::valid()"},{"path":"long-tests.html","id":"long-tests","chapter":"B Long Tests","heading":"B Long Tests","text":"","code":""},{"path":"long-tests.html","id":"what-are-they","chapter":"B Long Tests","heading":"B.1 What are they","text":"Code tests subdirectory Bioconductor software\npackages run R CMD check daily basis part \nBioconductor nightly builds.\nmaximum amount time R CMD check allowed spend\npackage 40 min.Package developers wish implement tests long\nrun context nightly builds can set “long tests” \npackage add package Bioconductor Long Tests builds.","code":""},{"path":"long-tests.html","id":"setup","chapter":"B Long Tests","heading":"B.2 Setup","text":"4 steps:Put code “long tests” longtests subdirectory \npackage. Like code tests directory, code\ntypically (necessarily) run unit tests.Put code “long tests” longtests subdirectory \npackage. Like code tests directory, code\ntypically (necessarily) run unit tests.Add package Long Tests builds adding .BBSoptions\nfile top-level directory following line :\nRunLongTests: TRUEAdd package Long Tests builds adding .BBSoptions\nfile top-level directory following line :code longtests subdirectory run week\n(every Saturday) part Long Tests builds allowed\nrun maximum 6 hours TIMEOUT raised.code longtests subdirectory run week\n(every Saturday) part Long Tests builds allowed\nrun maximum 6 hours TIMEOUT raised.Check \nlatest Long Tests report BioC devel.\nnext time report updated (normally every Saturday), \npackage included .Check \nlatest Long Tests report BioC devel.\nnext time report updated (normally every Saturday), \npackage included .Note also run Long Tests builds current release\nbranch week (every Saturday). latest report builds\n.","code":"RunLongTests: TRUE"},{"path":"long-tests.html","id":"short-tests-vs-long-tests","chapter":"B Long Tests","heading":"B.3 “Short tests” vs “long tests”","text":"Long Tests setup forces developers split testing code\npackage “short tests” “long tests”. former go \ntests subdirectory must able run less 40 min (\nlimit actually full R CMD check command runs \npossibly time-consuming things addition code tests).\nlatter go longtests subdirectory must able run\nless 6 hours.Note , unlike “short tests” failures, “long tests” failures don’t\nprevent package propagating version bump. words,\neven package included Long Tests builds, propagation\nstill determined results nightly builds.","code":""},{"path":"long-tests.html","id":"need-help","chapter":"B Long Tests","heading":"B.4 Need help?","text":"Ask bioc-devel mailing list questions \nneed help Long Tests builds.","code":""},{"path":"querying-web-resources.html","id":"querying-web-resources","chapter":"C Querying Web Resources","heading":"C Querying Web Resources","text":"Packages rely access web resources need written\ncarefully. Web resources can change location, can temporarily\nunavailable, can slow access retrieve. Functions\nquery web resources, anticipate handle situations\ngracefully – failing quickly clearly resource \navailable reasonable time frame. avoidable problems seen \nBioconductor package code include infinite loops, use \navailable R connections, unclear error messages.","code":""},{"path":"querying-web-resources.html","id":"guiding-principles-1","chapter":"C Querying Web Resources","heading":"C.1 Guiding Principles","text":"Remember Bioconductor packages built nightly across multiple\noperating systems, users benefit easy--run vignettes\nexamples.Download files reasonable size. Use system.time() estimate \ndownload time. Remember package require less 10 minutes \nrun R CMD check ---build-vignettes upper limit 15 minutes.Download files reasonable size. Use system.time() estimate \ndownload time. Remember package require less 10 minutes \nrun R CMD check ---build-vignettes upper limit 15 minutes.Set limit number times function tries URL. Avoid\n() statements guaranteed termination. \nbecome infinite loops eventually result build-system TIMEOUTs.Set limit number times function tries URL. Avoid\n() statements guaranteed termination. \nbecome infinite loops eventually result build-system TIMEOUTs.Supply informative error messages.Supply informative error messages.","code":""},{"path":"querying-web-resources.html","id":"template-for-resource-queries","chapter":"C Querying Web Resources","heading":"C.2 Template for Resource Queries","text":"function can serve template appropriate resource\nretrieval. tries retrieve resource one several times \nfailing, takes arguments:URL, resource queried, typically character(1) \nurl().FUN, function used query resource. Examples might\ninclude readLines(), download.file(), httr::GET(),\nRCurl::getURL()....: additional arguments used FUN.N.TRIES: number times URL attempted; \nexceptional circumstances might differ default value.return value retrieved resource. resource retrieval\nfails, function indicates failure, including condition\n(error) message last attempt. Warnings propagate user \nnormal way.Base R functions using url() connections respect\ngetOption(\"timeout\"); see ?url details.FUN might implemented retrieve resource test \nstatus, e.g.,","code":"getURL <- function(URL, FUN, ..., N.TRIES=1L) {\n N.TRIES <- as.integer(N.TRIES)\n stopifnot(length(N.TRIES) == 1L, !is.na(N.TRIES))\n\n while (N.TRIES > 0L) {\n result <- tryCatch(FUN(URL, ...), error=identity)\n if (!inherits(result, \"error\"))\n break\n N.TRIES <- N.TRIES - 1L\n }\n\n if (N.TRIES == 0L) {\n stop(\"'getURL()' failed:\",\n \"\\n URL: \", URL,\n \"\\n error: \", conditionMessage(result))\n }\n\n result\n}FUN <- function(URL, ...) {\n response <- httr::GET(URL, timeout(getOption(\"timeout\")), ...)\n stop_for_status(response)\n response\n}"},{"path":"c-fortran.html","id":"c-fortran","chapter":"D C and Fortran code","heading":"D C and Fortran code","text":"package contains C Fortran code, adhere standards \nmethods described System foreign language interfaces\nsection Writing R Extensions manual.emphasize particular points following sections.","code":""},{"path":"c-fortran.html","id":"internal-functions","chapter":"D C and Fortran code","heading":"D.0.1 Internal functions","text":"Use internal functions, e.g., R_alloc random number generators (RNGs), system-supplied ones.","code":""},{"path":"c-fortran.html","id":"c-function-registration","chapter":"D C and Fortran code","heading":"D.0.2 C function registration","text":"Use C function registration (See Registering native routines section \nWriting R Extensions manual).","code":""},{"path":"c-fortran.html","id":"checks-for-user-interruption","chapter":"D C and Fortran code","heading":"D.0.3 Checks for user interruption","text":"Use R_CheckUserInterrupt() C level loops chance may terminate certain parameter settings run time exceeds 10 seconds typical parameter settings, method intended interactive use.","code":""},{"path":"c-fortran.html","id":"makevars-1","chapter":"D C and Fortran code","heading":"D.0.4 Makevars","text":"Make judicious use Makevars Makefile files within package.\noften required (See Configure cleanup section Writing R Extensions manual).","code":""},{"path":"c-fortran.html","id":"warnings-and-optimizations","chapter":"D C and Fortran code","heading":"D.0.5 Warnings and optimizations","text":"package development, enable warnings disable optimizations.\nplan use debugger, tell compiler \ninclude debugging symbols.easiest way enforce create user-level Makevars file user’s home directory sub-directory called ‘.R’). See examples flags common toolchains.\nConsult section Makevars files Writing R Extensions manual.Example gcc/g++:Example clang/clang++:","code":"CFLAGS=-Wall -Wextra -pedantic -O0 -ggdb\nCXXFLAGS=-Wall -Wextra -pedantic -O0 -ggdb\nFFLAGS=-Wall -Wextra -pedantic -O0 -ggdbCFLAGS=-Weverything -O0 -g\nCXXFLAGS=-Weverything -O0 -g\nFFLAGS=-Wall -Wextra -pedantic -O0 -g"},{"path":"cmavericks-best-practices.html","id":"cmavericks-best-practices","chapter":"E C++/Mavericks Best Practices","heading":"E C++/Mavericks Best Practices","text":"guide mostly addresses adapt C/C++ code Bioconductor\npackages build Mac OS X 10.9 (Mavericks). package \nuse C C++ code, can assume document relevant \n.","code":""},{"path":"cmavericks-best-practices.html","id":"table-of-contents-1","chapter":"E C++/Mavericks Best Practices","heading":"E.1 Table of Contents","text":"document written read beginning end, except \nlast section.Orientation: approach developing \nMavericks.C++11: important info C++11 clang’s standard\nlibrary implementation.Issues specific Mavericks\nenvironment: special considerations \ntools available Mavericks.C++ Best Practices: generally applicable best\npractices C++ Bioconductor packages.Issues code external\nsources: tips using code \nwritten package contributor.Lessons learned specific issues: \nrepository knowledge specific problems.might skip lessons-learned section \ncheck issue already explored.","code":""},{"path":"cmavericks-best-practices.html","id":"orientation","chapter":"E C++/Mavericks Best Practices","heading":"E.2 Orientation","text":"Note: simplicity, guide uses ‘GCC’ (GNU Compiler Collection)\n‘clang’ refer respective collection tools (including\nC++ compilers), rather simply ‘GCC C compiler’ ‘clang C\ncompiler’. ‘Mavericks environment’ refers combination clang\nXcode versions available default Mavericks.release Mavericks\nbuild R, CRAN Bioconductor adopted Apple’s preferred\ntoolchain building packages Mavericks\nplatform. Bioconductor packages built Mavericks platform\nusing OS X default combination clang Xcode.introduction Mavericks environment revealed number \nissues building packages, due C/C++ code\nrelies heavily GCC way things. problems\nrevealed transition Mavericks caused C++ coding\npractices universally recognized problematic, \naddressed adhering established best practices.common sources problems, posed Mavericks\nenvironment contrasts GCC:Undefined behavior. GCC undefined\nbehavior might fail silently without affecting program execution,\nwhereas code Mavericks environment leads \nsegfault (“segmentation fault”).Undefined behavior. GCC undefined\nbehavior might fail silently without affecting program execution,\nwhereas code Mavericks environment leads \nsegfault (“segmentation fault”).Issues related naming, particularly \ncircumventing protections offered C++ namespaces. GCC header\norganization seems forgiving loose naming, whereas \nMavericks environment exacting.Issues related naming, particularly \ncircumventing protections offered C++ namespaces. GCC header\norganization seems forgiving loose naming, whereas \nMavericks environment exacting.C++11 default language specification, clang’s\nlibc++. libc++ implementation \nC++11 standard library written scratch. time \nwriting libc++ implementation available Mac OS X.C++11 default language specification, clang’s\nlibc++. libc++ implementation \nC++11 standard library written scratch. time \nwriting libc++ implementation available Mac OS X.Code written directly package\ncontributor(s). Many Bioconductor\npackages transition well Mavericks environment\ninclude third-party (e.g., Boost) generated (e.g., SWIG)\ncode. Many external code sources make assumptions valid\nMavericks environment. compounded difficulty \ndiagnosing problems code written package author limits\nBioconductor team’s ability help package.Code written directly package\ncontributor(s). Many Bioconductor\npackages transition well Mavericks environment\ninclude third-party (e.g., Boost) generated (e.g., SWIG)\ncode. Many external code sources make assumptions valid\nMavericks environment. compounded difficulty \ndiagnosing problems code written package author limits\nBioconductor team’s ability help package.","code":""},{"path":"cmavericks-best-practices.html","id":"what-is-different-about-developing-for-the-mavericks-environment","chapter":"E C++/Mavericks Best Practices","heading":"E.2.1 What is different about developing for the Mavericks environment?","text":"biggest change introduction clang’s\nlibc++ implementation C++11 standard\nlibrary library headers associated Xcode. clang \ngaining market share several reasons, helped fact \nclang intended compiler C-based languages. Advocates\nclang hold clang:offers better diagnostic information errors warningshas quicker compilation timessometimes yields smaller binariesin cases yields faster execution speeds (disputed)guidance compiler flags use developing, see \nrelevant section Package Guidelines page.","code":""},{"path":"cmavericks-best-practices.html","id":"differences-in-unspecified-behavior-memory-addressing-policies","chapter":"E C++/Mavericks Best Practices","heading":"E.2.1.1 Differences in unspecified behavior, memory addressing policies","text":"errors encountered transition seem attributable\nreliance non-portable unspecified behaviors. See section \nguide unspecified behavior \ninformation.example, many aspects C/C++ memory addressing \nimplementation-dependent, means expected behavior \nprescribed C/C++ standard (“unspecified”) therefore \ncompiler writers decide.foremost difference regarding memory clang seems \nrestrictive --bounds memory addressing.","code":""},{"path":"cmavericks-best-practices.html","id":"find-bugs","chapter":"E C++/Mavericks Best Practices","heading":"E.2.1.2 How to find bugs","text":"GCC preferred debugger gdb, many prefer\nlldb debugging Mavericks environment.number bugs packages related memory addressing\nlayout errors, relying debugger alone might sufficient\ntrack memory errors. Valgrind \npremier tool detecting memory errors.See Bioconductor guide debugging C/C++\ncode examples using \ndebugger Valgrind.","code":""},{"path":"cmavericks-best-practices.html","id":"what-if-i-cannot-access-a-mavericks-machine","chapter":"E C++/Mavericks Best Practices","heading":"E.2.1.3 What if I cannot access a Mavericks machine?","text":"substitute using Mavericks machine troubleshoot\npackages fail Mavericks. Many errors seen \nreproducible combination clang, Xcode, OS X 10.9.several options short procuring Mavericks machine:exploratory measure, install recent version GCC\ncompile package -std=c++11 -std=gnu++11 compiler\narguments; version\n4.8.1, GCC implements\nmajor features 2011 ISO C++ standard. Diagnostics \nerrors warnings also greatly improved recent GCC\nversions. Using C++11 implementation might reveal warnings\nerrors point issues encountered Mavericks.exploratory measure, install recent version GCC\ncompile package -std=c++11 -std=gnu++11 compiler\narguments; version\n4.8.1, GCC implements\nmajor features 2011 ISO C++ standard. Diagnostics \nerrors warnings also greatly improved recent GCC\nversions. Using C++11 implementation might reveal warnings\nerrors point issues encountered Mavericks.Install clang; limited value many errors \nunique Mavericks environment.Install clang; limited value many errors \nunique Mavericks environment.Use Valgrind memory addressing problems; many errors\nMavericks platform related memory addressing problems,\nmany errors equally discoverable using Valgrind Linux.Use Valgrind memory addressing problems; many errors\nMavericks platform related memory addressing problems,\nmany errors equally discoverable using Valgrind Linux.unable diagnose problem using combination \nbuild system output Valgrind, feel free contact \nbioc-devel mailing list.unable diagnose problem using combination \nbuild system output Valgrind, feel free contact \nbioc-devel mailing list.","code":""},{"path":"cmavericks-best-practices.html","id":"CXX11","chapter":"E C++/Mavericks Best Practices","heading":"E.3 C++11","text":"Although default version clang Mavericks includes support\nC++11 features, Bioconductor support C++11 dependent \nplatform oldest toolchain. current Snow\nLeopard (Mac OS X 10.6.8) toolchain support C++11\nfeatures, Bioconductor packages generally use C++11\nfeatures. Eventually, Mavericks widely adopted, support\nSnow Leopard dropped.C++11 completely backward-compatible older standards.possible tell clang use older versions standard\nlibrary (default libc++), \nrelying OS version-specific compilation settings workable\nlong-term solution. approach greatly increases maintenance\nburden package authors limits Bioconductor team’s ability\noffer support.insidious catastrophic consequence using non-default\nstandard libraries issue binary incompatibility. Packages\nlinked one standard library liable crash\n(mysteriously) interfacing packages linked \ndifferent standard library. also true programs OS\nlevel: program compiled linked libstdc++ \nMavericks platform , default, assumed incompatible \nprograms compiled linked libc++.Code adapted avoid constructs backward- \nforward-incompatible. See forward-incompatibility\nproblems section examples.","code":""},{"path":"cmavericks-best-practices.html","id":"issues-with-Mavericks-env","chapter":"E C++/Mavericks Best Practices","heading":"E.4 Issues specific to Mavericks environment","text":"","code":""},{"path":"cmavericks-best-practices.html","id":"c-linkage","chapter":"E C++/Mavericks Best Practices","heading":"E.4.1 C Linkage","text":"C++ uses extern \"C\" give declarations C linkage, hence make\ndeclarations accessible C code. R headers \n#included C++ include C++ system headers \nC linkage. According relevant Writing R Extensions Manual\nsection,\nR header files included within extern \"C\"\nblocks.typical symptom bad linkage package load time (\ncompilation link time) error says particular symbol \nfound.C++ mangles names, symbol name R says find \noften unrecognizable. Use c++filt program installed \nsystem online name demangler produce human-readable\nversion symbol name. Note mangled names \nenvironment-specific demangler meant GCC symbol names \nLinux demangle clang symbol names Mac.Solution: R headers #included outside extern \"C\" blocks.Example correct #include R headers:","code":"#include \nextern \"C\" {\n void foo(); // function 'foo' and other code in this block has C linkage\n ...\n}\nextern \"C\" void bar(); // function 'bar' has C linkage"},{"path":"cmavericks-best-practices.html","id":"openmp","chapter":"E C++/Mavericks Best Practices","heading":"E.4.2 OpenMP","text":"writing Mavericks environment support OpenMP,\nunknown tools released Apple ever .Code rely availability OpenMP. Independent \nconcerns OpenMP support, code written start \ndegrade nicely single-threaded environment.See Writing R Extensions Manual\nsection\ninformation OpenMP code R packages, detecting\nsupport.Solution: use preprocessor -else directives code degrades\ngracefully OpenMP support available:See ShortRead package example good practices around support OpenMP.","code":"#ifdef SUPPORT_OPENMP\n // multithreaded OpenMP version of code\n#else\n // single-threaded version of code\n#endif"},{"path":"cmavericks-best-practices.html","id":"best-practices","chapter":"E C++/Mavericks Best Practices","heading":"E.5 C++ Best Practices","text":"C++ practices applicable C++ projects, \nidentified Bioconductor community particularly helpful\navoiding issues Mavericks environment.","code":""},{"path":"cmavericks-best-practices.html","id":"use-rcpp","chapter":"E C++/Mavericks Best Practices","heading":"E.5.1 Use Rcpp","text":"Rcpp CRAN package allows seamless integration C++ R, \ncross-platform. package affords many benefits \nR C interface make C++ appealing language, \neliminating many pitfalls programming R interface.package well documented, extensive repository \nworking examples many tasks: Rcpp\nGallery.","code":""},{"path":"cmavericks-best-practices.html","id":"name-resolution-errors","chapter":"E C++/Mavericks Best Practices","heading":"E.5.2 Avoid name resolution errors","text":"name resolution error occurs compiler encounters \nidentifier (e.g., variable function name) ambiguous (\n, “collision” two identifiers), name\nlookup rules lead compiler resolve name incorrectly. clang \nexacting identifiers.typical symptom name resolution error compiler complains\ntype number arguments function got different \nexpects, compiler points C++ header file \nstandard library.two primary issues name resolution writing R\npackages:","code":""},{"path":"cmavericks-best-practices.html","id":"re-mapping-of-identifiers-from-r-headers","chapter":"E C++/Mavericks Best Practices","heading":"E.5.2.1 Re-mapping of identifiers from R headers","text":"convenience, R aliases common identifiers R\nheaders. E.g., Rf_length(SEXP) becomes length(SEXP). \nmay convenient C, organization headers \nMavericks environment seems lead collisions \nGCC. See relevant section Writing R Extensions\nManualSolution: prevent re-mapping R identifiers C++ code \ndefining R_NO_REMAP symbol. can done package level\n-DR_NO_REMAP preprocessor flag, file--file basis \n#define R_NO_REMAP. Use fully-qualified versions R identifiers,\nusually prepending Rf_.Example excerpt header file prevents re-mapping:Note Rf_length just one example many R identifiers \nmight conflict names C++ standard library headers.","code":"file CxxCode.h\n------------------\n\n#ifndef CXX_CODE_H\n#define CXX_CODE_H\n#ifdef __cplusplus\n#define R_NO_REMAP\n#endif\n\n...\n\nvoid foo(SEXP s) {\n if(Rf_length(s) > 1) // fully qualified: 'Rf_length'\n ...\n}\n\n#endif"},{"path":"cmavericks-best-practices.html","id":"namespace-hygiene","chapter":"E C++/Mavericks Best Practices","heading":"E.5.2.2 Namespace hygiene","text":"Namespaces introduced C++ limit incidence name\ncollisions. Many authors new C++, however, use\nusing-directives\n(particularly ‘using namespace std’ directive) unnecessarily,\nthereby reintroducing problems namespaces meant solve.pointed cppreference Notes\nsection\nuse using namespace std directive introduces entire\nstd namespace name resolution. high likelihood \namong headers standard library identifier\nconflicts identifiers package.Solution: avoid ‘using namespace std’ directive completely \npossible, especially header files. Prefer\nusing-declarations\nusing-directives simply use fully-qualified versions \nstandard library identifiers. New C++ authors overestimate much\nincluding scope resolution operator (namely ‘std::’) affects\nreadability.Example introducing std namespace identifiers:Many new C++ authors use using-directive introduce \nidentifiers need. Avoid possible:One alternative using-declarations (e.g., ‘using std::map;’,\nallow hand-picking identifiers introduce (opposed \nentire std namespace); just want std::map \nstd::make_pair. Even list identifiers want quite\nlong just need single using-declaration one:Using-declarations can also block-scoped. preferred \nusing-declarations global scope, prevents unnecessary\nintroduction names global scope, tenet good namespace\nhygiene:perfectly good alternative simply precede standard library\nidentifiers ‘std::’, C++ programmers accustomed\nreading:","code":"#include \n#include \n// Suppose we want to access the std::map and std::make_pair identifiersusing namespace std; // introduces entire std namespace for resolutionusing std::map; // 'map' and 'make_pair' introduced at declaration scope\nusing std::make_pair;void foo() {\n using std::map;\n using std::make_pair;\n map m;\n m.insert(make_pair(5, 7));\n ...\n}void foo() {\n std::map m;\n m.insert(std::make_pair(5, 7));\n}"},{"path":"cmavericks-best-practices.html","id":"undefined-behavior","chapter":"E C++/Mavericks Best Practices","heading":"E.5.3 Avoid undefined behavior and non-portable unspecified behavior","text":"two major categories behavior prescribed \nC C++ standards:undefined behavior specified arbitrary; code \nproduces behavior might cause program crash, \nmight execute without complaint (“silently”). effect can also\ndiffer one program execution next. Well-known examples\ninclude division zero, indexing outside array bounds, \ndereferencing null pointer.undefined behavior specified arbitrary; code \nproduces behavior might cause program crash, \nmight execute without complaint (“silently”). effect can also\ndiffer one program execution next. Well-known examples\ninclude division zero, indexing outside array bounds, \ndereferencing null pointer.unspecified behavior consistent documented, decided \nimplementation. behaviors either \nmentioned respective standard, mentioned \nsay implementation-dependent. Well-known examples\ninclude size int type size pointers.unspecified behavior consistent documented, decided \nimplementation. behaviors either \nmentioned respective standard, mentioned \nsay implementation-dependent. Well-known examples\ninclude size int type size pointers.typical symptom problematic undefined unspecified behaviors \nsegfault appears Mavericks environment. reason\nproblem discovered might GCC silently\nallows code execute instead crashing program.Solution: code defensively avoid problematic constructs use\ndebuggers find code leads errors.","code":""},{"path":"cmavericks-best-practices.html","id":"issues-external-code-sources","chapter":"E C++/Mavericks Best Practices","heading":"E.6 Issues with code from external sources","text":"packages need use code written directly \ncontributor(s). common scenario include source code\nlibrary written third party. packages also use code\nproduced code generation tools, e.g.,\nSWIG. First, see relevant [Package Guidelines\nsection][third-party-libraries] \nguidance code external sources.See lessons learned section guide \nsuggestions specific code sources.","code":""},{"path":"cmavericks-best-practices.html","id":"generated-code","chapter":"E C++/Mavericks Best Practices","heading":"E.6.1 Generated Code","text":"packages use code generated third-party tools, .e.,\ncode written machines. SWIG common example.problem code written machines code meant \nread machines. top code file produced SWIG, \nexample, states code meant read edited \nhand.many code generation tools make assumptions invalid\nMavericks environment, code needs human attention fix\nerrors; inscrutable nature machine-written code\ndifficult isolate errors.Solution: re-generate problem code possible, otherwise fix \nhand. Fixing hand strongly discouraged.","code":""},{"path":"cmavericks-best-practices.html","id":"third-party-libraries","chapter":"E C++/Mavericks Best Practices","heading":"E.6.2 Third-party libraries","text":"packages include third-party libraries written \ncompiler-independent way, build ---box \nMavericks environment.Solutions approximate order preference:Check existing CRAN \nBioconductor package provides functionality, meeting\nperformance needs use case. Eliminating third-party\ncode package greatly reduces maintenance burden.Check existing CRAN \nBioconductor package provides functionality, meeting\nperformance needs use case. Eliminating third-party\ncode package greatly reduces maintenance burden.Check library updated. libraries \nactive user community undergo updates add support \ncompilers/environments.Check library updated. libraries \nactive user community undergo updates add support \ncompilers/environments.Check maintainers aware library work \nMavericks environment, find support \nforthcoming. usually easy directly contact authors \nlibraries maintained individual small group.Check maintainers aware library work \nMavericks environment, find support \nforthcoming. usually easy directly contact authors \nlibraries maintained individual small group.Use actively maintained alternate library provides\nequivalent functionality. Sometimes library longer\nmaintained, library abandoned \nalternative project provides functionality.Use actively maintained alternate library provides\nequivalent functionality. Sometimes library longer\nmaintained, library abandoned \nalternative project provides functionality.Update library code included package \nhand. Strongly discouraged. Maintainer assumes responsibility\nkeeping code --date mainline source project. \nundertaken, record descriptions changes needed \ncodebase updated changes can easily reproduced.Update library code included package \nhand. Strongly discouraged. Maintainer assumes responsibility\nkeeping code --date mainline source project. \nundertaken, record descriptions changes needed \ncodebase updated changes can easily reproduced.","code":""},{"path":"cmavericks-best-practices.html","id":"lessons-learned","chapter":"E C++/Mavericks Best Practices","heading":"E.7 Lessons learned from specific issues","text":"section serves loosely organized repository knowledge\ngained specific problems solutions. expected\ncomprehensive. Items added knowledge base\ngrows. Bioconductor eager suggestions; please write \nbioc-devel mailing list !idea start diagnosing broken package\nmight worthwhile skim section.relevant, issue marked discoverable compile\ntime runtime.applicable, link live code demo provided.","code":""},{"path":"cmavericks-best-practices.html","id":"forward-incompatible","chapter":"E C++/Mavericks Best Practices","heading":"E.7.1 Forward-incompatibility problems with C++11","text":"C++11 completely backward-compatible. particular, API\nparts standard library changed slightly, \nperhaps subtle ways. issues require minimal tweaking fix.","code":""},{"path":"cmavericks-best-practices.html","id":"container-iterator-const-ness","chapter":"E C++/Mavericks Best Practices","heading":"E.7.1.1 Container iterator const-ness","text":"Type: compile timeA number operations standard library containers now require\niterators const. Two ready examples \ninsert\nerase\nmethods take iterator parameters.","code":""},{"path":"cmavericks-best-practices.html","id":"iterating-standard-library-containers","chapter":"E C++/Mavericks Best Practices","heading":"E.7.2 Iterating standard library containers","text":"Type: runtimeGenerally, using special\npast--end\niterator value equality checks (.e., == !=)\nresults undefined behavior. Particularly, Mavericks\nenvironment:Dereferencing iterator past--end value results \nsegfaultIncrementing iterator beyond past--end value results\nsegfault","code":""},{"path":"cmavericks-best-practices.html","id":"external-code-sources","chapter":"E C++/Mavericks Best Practices","heading":"E.7.3 External code sources","text":"Common examples external code sources \nSWIG, Boost, \nnumerous file format libraries. Code external sources \nsometimes written non-compiler-independent way. Check \ndocumentation see Mavericks environment supported.","code":""},{"path":"cmavericks-best-practices.html","id":"boost","chapter":"E C++/Mavericks Best Practices","heading":"E.7.3.1 Boost","text":"Boost source free, peer-reviewed C++\nlibraries enhance language. Many parts Boost \n“header-”, means need separately compiled\nheaders merely need appear search path order \nclient code use .Many Boost libraries platform-independent, . Boost\nlibraries either process adding Mavericks environment\nsupport, library authors announced Mavericks environment\nsupport added.Solutions approximate order preference:Use BH\npackage CRAN, possible. BH package provides several Boost\nheader-libraries. Using BH package means maintenance\ncost using Boost package virtually nothing.Use BH\npackage CRAN, possible. BH package provides several Boost\nheader-libraries. Using BH package means maintenance\ncost using Boost package virtually nothing.Update Boost libraries include package. Boost\nlibraries sometimes contain bugs, later updated add\nsupport platforms. Bioconductor package\nmaintainer’s responsibility keep code package\nupdated.Update Boost libraries include package. Boost\nlibraries sometimes contain bugs, later updated add\nsupport platforms. Bioconductor package\nmaintainer’s responsibility keep code package\nupdated.Contact authors specific Boost library. \nfind announcement regarding support Mavericks\nenvironment, might worth contacting library authors \ninquire.Contact authors specific Boost library. \nfind announcement regarding support Mavericks\nenvironment, might worth contacting library authors \ninquire.","code":""},{"path":"cmavericks-best-practices.html","id":"swig","chapter":"E C++/Mavericks Best Practices","heading":"E.7.3.2 SWIG","text":"SWIG generates code interface code written C/C++ \nlanguages. time writing, SWIG support clang\nlimited, SWIG particularly problems clang’s libc++\nversion (C++11) standard library. problems \nlimited issues can addressed tweaking function\nsignatures. problems deeply embedded way SWIG\nproduces code.time writing, thread SWIG-devel mailing\nlist\nseems -depth discussion working SWIG \nMavericks.Solutions approximate order preference:Eliminate SWIG code, possible. probably \nreducing maintenance burden.Eliminate SWIG code, possible. probably \nreducing maintenance burden.Re-generate SWIG code newest version SWIG. time\nwriting SWIG recently updated include partial\nsupport C++11, might alleviate problems clang’s\nlibc++. See SWIG document \nC++11 support. \npossible new version produce problematic\ncode. Note code must valid supported compilers.Re-generate SWIG code newest version SWIG. time\nwriting SWIG recently updated include partial\nsupport C++11, might alleviate problems clang’s\nlibc++. See SWIG document \nC++11 support. \npossible new version produce problematic\ncode. Note code must valid supported compilers.Troubleshoot fix errors hand. Strongly discouraged. \nundertaken, record descriptions changes needed \ncode regenerated changes can easily reproduced.\nRead SWIG documentation find\nguidance troubleshooting. (example, SWIG -E switch\noutputs results preprocessor run.) Perhaps start \nremoving SWIG functionality gradually adding features. Find\ninformation web fix errors \npackage.Troubleshoot fix errors hand. Strongly discouraged. \nundertaken, record descriptions changes needed \ncode regenerated changes can easily reproduced.Read SWIG documentation find\nguidance troubleshooting. (example, SWIG -E switch\noutputs results preprocessor run.) Perhaps start \nremoving SWIG functionality gradually adding features. Find\ninformation web fix errors \npackage.","code":""},{"path":"cmavericks-best-practices.html","id":"f2c","chapter":"E C++/Mavericks Best Practices","heading":"E.7.3.3 f2c","text":"f2c tool converts Fortran77\ncode C/C++ code. maintenance burden required make f2c code\ncross-platform substantial. Since fortran compiler (emulator)\nrequired install R, f2c usually unnecessary. Several\npackages use native fortran code without problem.Solution: possible, remove need f2c. \nrecourse finesse makefiles point supported\nplatform less targeted makefile. Please write \nbioc-devel mailing list trouble.","code":""},{"path":"man-links.html","id":"man-links","chapter":"F Debug: Links in Rd files","heading":"F Debug: Links in Rd files","text":"","code":""},{"path":"man-links.html","id":"context","chapter":"F Debug: Links in Rd files","heading":"F.1 Context","text":"chapter describes issue resolved 31-May-2022.objective include link man page one package\nman page SummarizedExperiment class SummarizedExperiment package.Using roxygen2, link written \nfollows R file:issue rcmdcheck::rcmdcheck() reported following WARNING:","code":"#' ... \\linkS4class{SummarizedExperiment} ...W checking Rd cross-references (<...>ms)\n Missing link or links in documentation object '<...>.Rd':\n ‘SummarizedExperiment-class’\n \n See section 'Cross-references' in the 'Writing R Extensions' manual."},{"path":"man-links.html","id":"what-worked","chapter":"F Debug: Links in Rd files","heading":"F.2 What worked","text":"First, SummarizedExperiment package added Depends: section\nDESCRIPTION file.point, rcmdcheck::rcmdcheck() dropped previous WARNING instead\ndisplayed following NOTE., following line added R script.Next, devtools::document() run, adding following line \nNAMESPACE file.point rcmdcheck::rcmdcheck() return issue.","code":"Depends:\n SummarizedExperimentN checking dependencies in R code (7.9s)\n Package in Depends field not imported from: ‘SummarizedExperiment’\n These packages need to be imported from (in the NAMESPACE file)\n for when this namespace is loaded but not attached.#' @import SummarizedExperimentimport(SummarizedExperiment)"},{"path":"man-links.html","id":"what-did-not-work","chapter":"F Debug: Links in Rd files","heading":"F.3 What did not work","text":"Adding SummarizedExperiment package Imports: section \nDESCRIPTION file, adding @import statement documentation, \nrunning devtools::document().\npoint, rcmdcheck::rcmdcheck() continued display initial WARNING.","code":""},{"path":"man-links.html","id":"additional-resources-1","chapter":"F Debug: Links in Rd files","heading":"F.4 Additional resources","text":"Rd formatting","code":""},{"path":"booknews.html","id":"booknews","chapter":"G NEWS","heading":"G NEWS","text":"","code":""},{"path":"booknews.html","id":"version-1.0.1-2021-08-19","chapter":"G NEWS","heading":"G.1 Version 1.0.1 (2021-08-19)","text":"Add dedicated section package name.","code":""},{"path":"booknews.html","id":"version-1.0.0-2021-06-02","chapter":"G NEWS","heading":"G.2 Version 1.0.0 (2021-06-02)","text":"Initial definition package development guidelines based \nBioconductor package guidelines listed main Bioconductor.org website.","code":""}] diff --git a/sysdep.html b/sysdep.html index 5970970..f2815aa 100644 --- a/sysdep.html +++ b/sysdep.html @@ -106,8 +106,11 @@

An INSTALL file does not have to be included with the package. An INSTALL file is utilized for specifying external system requirements needed. It should be used in combination with the SystemRequirements field of the Description -file. This file should contain installation instructions -for the required system dependency.

+file. This file should provide instructions for installing +the external software on the 3 major OS that we support: Linux, Windows, and +Mac. This will not only help your users get the external software on their +machines, but it will also help us install it on the build machines if it’s not +already there.

Specifying this requirement does not guarantee that Bioconductor will agree to install the external system requirement. It is encouraged to discuss any additional system requirements on the before