PackagecheckpointJanuary282022TitleInstallPackagesfromSnapshotsonth - PDF document

Package`checkpoint'January28,2022TitleInstallPackagesfromSnapshotsontheCheckpointServerforReproducibilityDescriptionThegoalofcheckpointistosolvetheproblemofpackagereproducibilityinR.Specically,checkpointallowsyoutoinstallpackagesastheyexistedonCRANonaspecicsnapshotdateasifyouhadaCRANtimemachine.Toachievereproducibility,thecheckpoint()functioninstallsthepackagesrequiredorcalledbyyourprojectandscriptstoalocallibraryexactlyastheyexistedatthespeciedpointintime.Onlythosepackagesareavailabletoyourproject,therebyavoidinganypackageupdatesthatcamelaterandmayhavealteredyourresults.Inthisway,anyoneusingcheckpointscheckpoint()canensurethereproducibilityofyourscriptsorprojectsatanytime.Tocreatethesnapshotarchives,onceaday(atmidnightUTC)MicrosoftrefreshestheAustriaCRANmirrorontheMicrosoftRArchivedNetworkserver(https://mran.microsoft.com/�).Immediatelyaftercompletionofthersyncmirrorprocess,theprocesstakesasnapshot,thuscreatingthearchive.Snapshotarchivesexiststartingfrom2014-09-17.Version1.0.2LicenseGPL-2URLhttps://github.com/RevolutionAnalytics/checkpointBugReportshttps://github.com/RevolutionAnalytics/checkpoint/issuesImportsutils,tools,jsonlite,yaml,withr,pkgdependsDependsR�(=3.3.0)Suggestspkgcache,knitr,rmarkdown,testthat,dartsVignetteBuilderknitrEncodingUTF-8RoxygenNote7.1.0NeedsCompilationnoAuthorFolashadeDaniel[cre],HongOoi[aut],AndriedeVries[aut],GáborCsárdi[ctb](Assistancewithpkgdepends),Microsoft[aut,cph]1 2checkpoint-packageMaintainerFolashadeDaniel࿚n;&#xiel@;&#

xmicr;&#xosof;&#xt.co;&#xm000;RepositoryCRANDate/Publication2022-01-2819:10:09UTCRtopicsdocumented:checkpoint-package.....................................2checkpoint..........................................3scan_project_les......................................7use_mran_snapshot.....................................9Index11 checkpoint-packageInstallpackagesfromsnapshotsonthecheckpointserverforrepro-ducibility DescriptionThegoalofcheckpointistosolvetheproblemofpackagereproducibilityinR.Specically,check-pointallowsyoutoinstallpackagesastheyexistedonCRANonaspecicsnapshotdateasifyouhadaCRANtimemachine.DetailsToachievereproducibility,thecreate_checkpointfunctioninstallsthepackagesrequiredorcalledbyyourprojectandscriptstoalocallibraryexactlyastheyexistedatthespeciedpointintime.Onlythosepackagesareavailabletotyourproject,therebyavoidinganypackageupdatesthatcamelaterandmayhavealteredyourresults.Inthisway,anyoneusingcheckpointcanensurethereproducibilityofyourscriptsorprojectsatanytime.Tocreatethesnapshotarchives,onceaday(atmidnightUTC)werefreshtheAustriaCRANmirror,onthecheckpointserver(https://mran.microsoft.com/).Immediatelyaftercompletionofthersyncmirrorprocess,wetakeasnapshot,thuscreatingthearchive.Snapshotarchivesexiststartingfrom2014-09-17.checkpointexposesthefollowingfunctions:•create_checkpoint:CreatesacheckpointbyscanningaprojectfolderanddownloadingandinstallinganypackagesrequiredfromMRAN.•use_checkpoint:Usesapreviouslycreatedcheckpoint,bysettingthelibrarysearchpathtothecheckpointpath,andt

heCRANmirrortoMRAN.•delete_checkpoint:Deletesanexistingcheckpoint.•delete_all_checkpoints:Deletesallexistingcheckpoints.•uncheckpoint:Stopsusingacheckpoint,restoringthelibrarysearchpathandCRANmirrortotheiroriginalstate.•scan_project_files:Scansaprojectforanyrequiredpackages.•list_mran_snapshots:ReturnsallvalidsnapshotdatesfoundonMRAN. checkpoint3 checkpointConguresRsessiontousepackagesastheyexistedonCRANattimeofsnapshot. DescriptionTogether,thecheckpointpackageandthecheckpointserveractasaCRANtimemachine.Thecreate_checkpointfunctioninstallsthepackagesreferencedinthespeciedprojecttoalo-callibraryexactlyastheyexistedatthespeciedpointintime.Onlythosepackagesareavailabletoyoursession,therebyavoidinganypackageupdatesthatcamelaterandmayhavealteredyourresults.Inthisway,anyoneusingtheuse_checkpointfunctioncanensurethereproducibilityofyourscriptsorprojectsatanytime.Thecheckpointfunctionservesasasimpleumbrellainterfacetothesefunctions.Itrsttestsifthecheckpointexists,createsitifnecessarywithcreate_checkpoint,andthencallsuse_checkpoint.Usagecheckpoint(snapshot_date,r_version=getRversion(),checkpoint_location="~",...)create_checkpoint(snapshot_date,r_version=getRversion(),checkpoint_location="~",project_dir=".",mran_url=getOption("checkpoint.mranUrl","https://mran.microsoft.com"),scan_now=TRUE,scan_r_only=FALSE,scan_rnw_with_knitr=TRUE,scan_rprofile=TRUE,force=FALSE,log=TRUE,num_workers=getOption("Ncpus",1),config=list(),...)use_checkpoint(snapshot_date,r_version=getRversion(),checkpoint

_location="~",mran_url=getOption("checkpoint.mranUrl","https://mran.microsoft.com"), 4checkpointprepend=FALSE,...)delete_checkpoint(snapshot_date,r_version=getRversion(),checkpoint_location="~",confirm=TRUE)delete_all_checkpoints(checkpoint_location="~",confirm=TRUE)uncheckpoint()Argumentssnapshot_dateDateofsnapshottouseinYYYY-MM-DDformat,e.g."2020-01-01".Specifyadateonorafter"2014-09-17".MRANtakesonesnapshotperday.TolistallvalidsnapshotdatesonMRAN,uselist_mran_snapshots.r_versionOptionalcharacterstring,e.g."3.6.2".Ifspecied,thisiscomparedtothecur-rentR.version,andiftheydiffer,awarningisissued.ThebenetofsupplyingthisargumentisthatcheckpointcanalertyouwhenyourRversionchangeswhileyouareworkingonaproject;thiscanjustaseasilyleadtoreproducibilityissuesaschangesinthird-partycode.Considersupplyinganexplicitvalueforthisargument,althoughcheckpointwillstillfunctionwithoutit.checkpoint_locationFilepathwherethecheckpointlibraryisstored.Defaultis"~",i.e.yourhomedirectory.Usecasesforchangingthisincludecreatingacheckpointlibraryonaportabledrive(e.g.USBdrive),orcreatingper-projectcheckpoints.Theactualcheckpointswillbecreatedundera.checkpointdirectoryatthislocation....Forcheckpoint,furtherargumentstopasstocreate_checkpointanduse_checkpoint.Ignoredforcreate_checkpointanduse_checkpoint.project_dirAprojectpath.ThisisthepathtotherootoftheprojectthatreferencesthepackagestobeinstalledfromtheMRANsnapshotforthedatespeciedforsnapshotDate.Defaultstothecurrentworkingdirectory.mran_urlThebaseMRANURL.Thedefaultistakenfromthesystemo

ptioncheckpoint.mranUrl,orifthisisunset,https://mran.microsoft.com.Currentlycheckpoint1.0doesnotsupportlocalMRANmirrors.scan_nowIfTRUE,scansforpackagesintheprojectfolder(see'Details').IfFALSE,skipsthescanningprocess.SetthistoFALSEifyouonlywanttocreatethecheckpointsubdirectorystructure.scan_r_onlyIfTRUE,limitsthescanningofprojectlestoRscriptsonly(thosewiththeextension".R").scan_rnw_with_knitrIfTRUE,scansSweaveles(thosewithextension".Rnw")withknitr::knitr,otherwisewithutils::Stangle.Ignoredifscan_r_only=TRUE. checkpoint5scan_rprofileifTRUE,includesthe~/.Rprolestartupleinthescan.SeeStartup.forceIfTRUE,suppressestheconrmationpromptifcreate_checkpointisrunwithprojectdirectorysettotheuserhomedirectory.logIfTRUE,writeslogginginformation(mostlytheoutputfromthemethodsofpkgdepends::pkg_installation_proposal)tothecheckpointdirectory.num_workersThenumberofparallelworkerstouseforinstallingpackages.DefaultstothevalueofthesystemoptionNcpus,orifthisisunset,1.configAnamedlistofadditionalcongurationoptionstopasstopkgdepends::new_pkg_installation_proposal.See'Conguration'below.prependIfTRUE,addsthecheckpointdirectorytothebeginningofthelibrarysearchpath.ThedefaultisFALSE,wherethecheckpointdirectoryreplacesallbutthesystementries(thevaluesof.Libraryand.Library.site)inthesearchpath;thisistoreducethechancesofaccidentallycallingnon-checkpointedcode.See.libPaths.confirmFordelete_checkpointanddelete_all_checkpoints,whethertoaskforconrmationrst.Detailscreate_checkpointcreatesalocallibrary(bydefault,located

underyourhomedirectory)intowhichitinstallscopiesofthepackagesrequiredbyyourprojectastheyexistedonCRANonthespeciedsnapshotdate.Todeterminethepackagesusedinyourproject,thefunctionscansallRcode(.R,.Rmd,.Rnw,.Rhtmland.Rpresles)forlibraryandrequirestatements,aswellasthenamespacingoperators::and:::.create_checkpointwillautomaticallyaddthermarkdownpackageasadependencyifitndsanyRmarkdown-basedles(thosewithextension.Rmd,.Rpresor.Rhtml)inyourproject.Thisallowsyoutocontinueworkingwithsuchdocumentsaftercheckpointing.CheckpointonlyinstallspackagesthatcanbefoundonCRAN.Thisincludesthird-partypack-ages,aswellasthosedistributedaspartofRthathavethe"Recommends"priority.Base-prioritypackages(theworkhorseengineofR,includingutils,graphics,methodsandsoforth)arenotcheck-pointed(butseether_versionargumentabove).Thepackageinstallationiscarriedoutviathepkgdependspackage,whichhasmanyfeaturesinclud-ingcacheddownloads,parallelinstalls,andcomprehensivereportingofoutcomes.Italsosolvesmanyproblemsthatpreviousversionsofcheckpointstruggledwith,suchasbeingabletoinstallpackagesthatareinuse,andreliablydetectingtheoutcomeoftheinstallationprocess.use_checkpointmodiesyourRsessiontouseonlythepackagesinstalledbycreate_checkpoint.Specically,itchangesyourlibrarysearchpathvia.libPaths()topointtothecheckpointedli-brary,andthencallsuse_mran_snapshottosettheCRANmirrorforthesession.checkpointisaconveniencefunctionthatcallscreate_checkpointifthecheckpointdirectorydoesnotexist,andthenuse_checkpoint.delete_checkpointdeletesacheckpoint,afteren

suringthatitisnolongerinuse.delete_all_checkpointsdeletesallcheckpointsunderthegivencheckpointlocation.uncheckpointisthereverseofuse_checkpoint.ItrestoresyourlibrarysearchpathandCRANmirroroptiontotheiroriginalvalues,astheywerebeforecheckpointwasloaded.Callthisbeforecallingdelete_checkpointanddelete_all_checkpoints. 6checkpointValueThesefunctionsarerunmostlyfortheirside-effects;howevercreate_checkpointinvisiblyreturnsanobjectofclasspkgdepends::pkg_installation_proposalifscan_now=TRUE,andNULLoth-erwise.checkpointreturnstheresultofcreate_checkpointifthecheckpointhadtobecreated,otherwiseNULL.CongurationThepkgdependspackagewhichpowerscheckpointallowsyoutocustomisetheinstallationprocessviaalistofcongurationoptions.Whencreatingacheckpoint,youcanpasstheseoptionstopkgde-pendsviatheconfigargument.Afulllistofoptionscanbefoundatpkgdepends::pkg_config;notethatcreate_checkpointautomaticallysetsthevaluesofcran-mirror,libraryandr-version.OneimportantusecasefortheconfigargumentiswhenyouareusingWindowsorMacOS,andthesnapshotdatedoesnotincludebinarypackagesforyourversionofR.ThiscanoccurifeitheryourversionofRistooold,orthesnapshotdateistoofarinthepast.Inthiscase,youshouldspecifyconfig=list(platforms="source")togetcheckpointtodownloadthesourcepackagesinstead(andthencompilethemlocally).NotethatifyourpackagesincludeC,C++orFortrancode,youwillneedtohavetherequisitecompilersinstalledonyourmachine.LastaccesseddateThecreate_checkpointanduse_checkpointfunctionsstoreamarkerinthesnapshotfoldereverytimethefunctiongetscalled.Thismarkercont

ainsthesystemdate,thusindicatingthethelasttimethesnapshotwasaccessed.Examples##Notrun:#Createtemporaryprojectandsetworkingdirectoryexample_projectpaste0("~/checkpoint_example_project_",Sys.Date())dir.create(example_project,recursive=TRUE)#Writedummycodefiletoprojectcat("library(MASS)library(foreach)",file="checkpoint_example_code.R")#Createacheckpointbyspecifyingasnapshotdate#recommendedpracticeistospecifytheRversionexplicitlyrvergetRversion()create_checkpoint("2014-09-17",r_version=rver,project_dir=example_project)use_checkpoint("2014-09-17",r_version=rver) scan_project_les7#moretersealternativeischeckpoint(),whichisequivalentto#callingcreate_checkpoint()andthenuse_checkpoint()insequencecheckpoint("2014-09-17",r_version=rver,project_dir=example_project)#CheckthatCRANmirrorissettoMRANsnapshotgetOption("repos")#Checkthat(1st)librarypathissetto~/.checkpoint.libPaths()#Checkwhichpackagesareinstalledincheckpointlibraryinstalled.packages()#restoreinitialstateuncheckpoint()#deletethecheckpointdelete_checkpoint("2014-09-17",r_version=rver)##End(Notrun) scan_project_filesScanRlesforpackagedependencies DescriptionThisfunctionscanstheRlesinyourproject,includingscripts,SweavedocumentsandRmarkdown-basedles,forreferencestopackages.Usagescan_project_files(project_dir=".",scan_r_only=FALSE,scan_rnw_with_knitr=TRUE,scan_rprofile=TRUE)Argumentsproject_dirAprojectpath.ThisisthepathtotherootoftheprojectthatreferencesthepackagestobeinstalledfromtheMRANsnapshotforthedatespeciedforsnapshotDate.Defaultstothecurrentwo

rkingdirectory. 8scan_project_lesscan_r_onlyIfTRUE,limitsthescanningofprojectlestoRscriptsonly(thosewiththeextension.R).scan_rnw_with_knitrIfTRUE,scansSweaveleswithknitr::knitr,otherwisewithutils::Stangle.Ignoredifscan_r_only=TRUE.scan_rprofileifTRUE,includesthe~/.Rprolestartupleinthescan.SeeStartup.Detailsscan_project_filesrecursivelybuildsalistofalltheRlesinyourproject.ThisincludesregularRscripts,aswellasSweaveles(thosewithextension.Rnw)andRmarkdown-basedles(thosewithextension.Rmd,.RpresorRhtml).Itthenparsesthecodeineachleandlooksforcallstolibraryandrequire,aswellasthenamespacingoperators::and:::.ThedetectedpackagesareassumedtobeavailablefromCRAN/MRAN.ValueAlistwith2components:pkgs,avectorofpackagenames,anderrors,avectoroflesthatcouldnotbescanned.Thepackagelistingincludesthird-partypackages,aswellasthosethataredistributedwithRandhave"Recommended"priority.Base-prioritypackages(utils,graphics,methodsandsoforth)arenotincluded.Inaddition,ifanyRmarkdownlesarefound,thepackagelistingwillincludermarkdown.Thisallowsyoutocontinuerenderingtheminacheckpointedsession.ManifestAsanexperimentalfeature,youcanspecifyadditionalpackagestoincludeorexcludeviaanoptionalcheckpoint.ymlmanifestlelocatedinyourprojectdirectory.ThisshouldbeavalidYAMLlewith2components:•refs:Anarrayofpackagereferencestoincludeinthecheckpoint,thatcanbeparsedbypkgdepends::new_pkg_installation_proposal.•exclude:Anarrayofpackagenames(withoutdecorations)toexcludefromthecheckpoint,despiteshowingupinthesc

an.AmanifestleallowsyoutoincludepackagesfromsourcesotherthanCRAN/MRANinthecheck-point.YoucanincludeaBioconductorpackagewithabioc::reference:bioc::BiocGenerics.AGitHubreferencebeginswithgithub::,forexamplegithub::RevolutionAnalytics/checkpoint@v1.0.Alocal::referencecanpointtoapackage.tar.gzle,ortoadirectorycontainingthepackagesourcecode.Youshouldusethisfeaturewithcaution,ascheckpointdoesnotchecktheversionsofthesepack-ages.It'srecommendedthatyouincludeaversionnumber,tagorcommithashinareference,sothatyoualwaysobtainthesameversionofthepackage.Seepkgdepends::pkg_refsforafulldescriptionofthereferencesyntax;notethatinstalled::referencesarenotcurrentlysupportedbycheckpoint.AusecaseforexclusionsisifyourworkowloadspackagesthatarenotonCRANorotherpublicrepositories.Forexample,MicrosoftMachineLearningServer(MMLS)comeswithanumberofproprietarypackagesforbigdataandin-databaseanalytics.Youcanexcludethesepackages use_mran_snapshot9fromcheckpointingbylistingthemintheexcludeentryinthemanifest.Inthiscase,youmustensurethatyourpackagesarestillvisibletothecheckpointedsession,forexamplebyspecifyingprepend=TRUEintheuse_checkpointcall.Ifyoushareyourprojectwithcollaborators,theywillalsoneedtohavethesepackagesseparatelyinstalledontheirmachines.Examplesscan_project_files() use_mran_snapshotUtilitiesforworkingwithMRANsnapshots DescriptionThesefunctionsareforworkingwiththeMRANcheckpointserver.use_mran_snapshotupdatestheCRANmirrorforyourRsessiontopointtoanMRANsnapshot,usingoptions(repos).list_mran_snapshotsreturnsthedatesforwhichanMRA

Nsnapshotexists.Usageuse_mran_snapshot(snapshot_date,mran_url=getOption("checkpoint.mranUrl","https://mran.microsoft.com"),validate=FALSE)list_mran_snapshots(mran_url=getOption("checkpoint.mranUrl","https://mran.microsoft.com"))Argumentssnapshot_dateDateofsnapshottouseinYYYY-MM-DDformat,e.g."2020-01-01".Specifyadateonorafter"2014-09-17".mran_urlThebaseMRANURL.Thedefaultistakenfromthesystemoptioncheckpoint.mranUrl,orifthisisunset,https://mran.microsoft.com.validateForuse_mran_snapshot,whethertocheckifthesnapshotdateisvalid(existsontheserver).ValueForuse_mran_snapshot,thenewvalueofgetOption("repos"),invisibly.Forlist_mran_snapshots,acharactervectorofsnapshotdates. 10use_mran_snapshotExamples##Notrun:list_mran_snapshots()use_mran_snapshot("2020-01-01")#validate=TRUEwilldetectaninvalidsnapshotdateuse_mran_snapshot("1970-01-01",validate=TRUE)##End(Notrun) Indexcheckpointfunctionscheckpoint,3packagecheckpoint-package,2.libPaths,5checkpoint,3checkpoint-package,2create_checkpoint,2create_checkpoint(checkpoint),3delete_all_checkpoints,2delete_all_checkpoints(checkpoint),3delete_checkpoint,2delete_checkpoint(checkpoint),3knitr::knitr,4,8library,5list_mran_snapshots,2,4list_mran_snapshots(use_mran_snapshot),9pkgdepends,5pkgdepends::new_pkg_installation_proposal,5,8pkgdepends::pkg_config,6pkgdepends::pkg_installation_proposal,5pkgdepends::pkg_refs,8R.version,4require,5scan_project_files,2,7Startup,5,8uncheckpoint,2uncheckpoint(checkpoint),3use_checkpoint,2use_checkpoint(checkpoint),3use_mran_snapshot,5,9utils::Stangle