treatssyntaxhighlighter

knitr:AGeneral-PurposeToolforDynamicReportGenerationinRYihuiXieJanuary6,2013Theoriginalparadigmofliterateprogrammingwasbroughtforwardmainlyforsoftwaredevelopment,orspecically,tomixsourcecode(forcomputer)anddocumentation(forhuman)together.
EarlysystemsincludeWEBandNoweb;Sweave(Leisch,2002)wasderivedfromthelatter,butitislessfocusedondocumentingsoftware,insteaditismainlyusedforreproducibledataanalysisandgeneratingstatisticalreports.
Theknitrpackage(Xie,2012c)isfollowingthestepsofSweave.
Forthismanual,IassumereadershavesomebackgroundknowledgeofSweavetounderstandthetechnicaldetails;forareferenceofavailableoptions,hooksanddemos,seethepackagehomepagehttp://yihui.
name/knitr/.
1HelloWorldAnaturalquestioniswhytoreinventthewheel.
TheshortansweristhatextendingSweavebyhackingSweaveDrivers.
Rintheutilspackageisadifcultjobtome.
Manyfeaturesinknitrcomenaturallyasuserswouldhaveexpected.
Figure1isasimpledemoofsomefeaturesofknitr.
IwouldhavechosentohidetheRcodeifthiswerearealreport,buthereIshowthecodejustforthesakeofdemonstration.
Ifwetypeqplot()inR,wegetaplot,andthesamethinghappensinknitr.
Ifwefitxx[1]-0.
630160.
12716-1.
100260.
07677-0.
10064>var(x)[1]0.
2776Theexamplebelowshowstheeffectoftidy=TRUE/FALSE:##optiontidy=FALSEfor(kin1:10){j=cos(sin(k)*k2)+3;print(j-5)}##optiontidy=TRUEfor(kin1:10){j>=@DifferentdocumentscanreadthesameRscript,sotheRcodecanbereusableacrossdifferentinputdocuments.
3.
5EvaluationofChunkOptionsBydefaultknitrusesanewsyntaxtoparsechunkoptions:ittreatsthemasfunctionargumentsinsteadofatextstringtobesplittoobtainoptionvalues.
Thisgivestheusermuchmorepowerthantheoldsyntax;wecanpassarbitraryRobjectstochunkoptionsbesidessimpleoneslikeTRUE/FALSE,numbersandcharacterstrings.
Thepagehttp://yihui.
name/knitr/demo/sweave/hasgiventwoexamplestoshowtheadvantagesofthenewsyntax.
Hereweshowyetanotherusefulapplication.
Beforeknitr0.
3,therewasafeaturenamed"conditionalevaluation"6.
Theideais,insteadofsettingchunkoptionsevalandechotobeTRUEorFALSE(constants),theirvaluescanbecontrolledbyglobalvariablesinthecurrentRsession.
Thisenablesknitrtoconditionallyevaluatecodechunksaccordingtovariables.
Forexample,hereweassignTRUEtoavariabledothis:dothis<-TRUEInthenextchunk,wesetchunkoptionseval=dothisandecho=!
dothis,botharevalidRexpressionssincethevariabledothisexists.
Aswecansee,thesourcecodeishidden,butitwasindeedevaluated:##[1]"youcannotseemysourcebecause!
dothisisFALSE"Thenweseteval=dothisandecho=dothisforanotherchunk:dothis##[1]TRUEIfwechangethevalueofdothistoFALSE,neitheroftheabovechunkswillbeevaluatedanymore.
Thereforewecancontrolmanychunkswithasinglevariable,andpresentresultsselectively.
Thisoldfeaturerequiresknitrtotreatevalandechospecially,andwecaneasilyseethatitisnolongernecessarywiththenewsyntax:eval=dothiswilltellRtondthevariabledothisautomaticallyjustlikewecallafunctionfoobar(eval=dothis).
Whatismore,alloptionswillbeevaluatedasRexpressionsunlesstheyarealreadyconstantswhichdonotneedtobeevaluated,sothisoldfeaturehasbeengeneralizedtoallotheroptionsnaturally.
3.
6CustomizationTheknitrpackageisreadyforcustomization.
Boththepatternsandhookscanbecustomized;seethepackagewebsitefordetails.
HereIshowanexampleonhowtosaverglplots(AdlerandMurdoch,2012)usingacustomizedhookfunction.
Firstwedeneahooknamedrglusingthefunctionhookrgl()inknitr:6requestfromhttps://plus.
google.
com/u/0/116405544829727492615/posts/43WrRUffjzK9knit_hooks$set(rgl=hook_rgl)head(hook_rgl)#thehookfunctionisdefinedasthis####1function(before,options,envir)##2{##3library(rgl)##4if(before||rgl.
cur()==0)##5return()##6name=fig_path()Thenweonlyhavetosetthechunkoptionrgl=TRUE:library(rgl)demo("bivar",package="rgl",echo=FALSE)par3d(zoom=0.
7)Duetotheexibilityofoutputhooks,knitrsupportsseveraldifferentoutputformats.
Theimplemen-tationisfairlyeasy,e.
g.
,forLATEXweputRoutputinverbatimenvironments,andinHTML,itisonlyamatterofputtingoutputindivlayers.
Thesearesimplycharacterstringoperations.
Manydemosinhttp://yihui.
name/knitr/demosshowthisideaclearly.
Thismanualdidnotcoverallthefeaturesofknitr,andusersareencouragedtothumbthroughthewebsitetoknowmorepossiblefeatures.
4EditorsYoucanuseanytexteditorstowritethesourcedocuments,butsomehavebuilt-insupportforknitr.
BothRStudio(http://www.
rstudio.
org)andLYX(http://www.
lyx.
org)havefullsupportforknitr,andyoucancompilethedocumenttoPDFwithjustoneclick.
Seehttp://yihui.
name/knitr/demo/rstudio/andhttp://yihui.
name/knitr/demo/lyx/respectively.
ItisalsopossibletosupportothereditorslikeEclipse,TexmakerandWinEdt;seethedemolistinthewebsiteforcongurationinstructions.
AboutThisDocumentThismanualwaswritteninLYXandcompiledwithknitr(version0.
9.
5).
TheLYXsourceandtheRnwdocumentexportedfromLYXcanbefoundunderthesedirectories:system.
file("examples","knitr-manual.
lyx",package="knitr")#lyxsourcesystem.
file("examples","knitr-manual.
Rnw",package="knitr")#Rnwsource10Youcanusethefunctionknit()toknittheRnwdocument(remembertoputthetwo.
biblesunderthesamedirectory),andyouneedtomakesurealltheRpackagesusedinthisdocumentareinstalled:install.
packages(c("animation","rgl","tikzDevice","ggplot2"))Feedbackandcommentsonthismanualandthepackagearealwayswelcome.
Bugreportsandfeaturerequestscanbesenttohttps://github.
com/yihui/knitr/issues,andquestionscanbedeliveredtothemailinglisthttps://groups.
google.
com/group/knitr.
ReferencesAdlerD,MurdochD(2012).
rgl:3Dvisualizationdevicesystem(OpenGL).
Rpackageversion0.
92.
894,URLhttp://CRAN.
R-project.
org/package=rgl.
BrackenC,SharpsteenC(2012).
pgfSweave:QualityspeedygraphicscompilationandcachingwithSweave.
Rpackageversion1.
3.
0,URLhttp://CRAN.
R-project.
org/package=pgfSweave.
FrancoisR(2012).
highlight:Syntaxhighlighter.
Rpackageversion0.
3.
2,URLhttp://CRAN.
R-project.
org/package=highlight.
LeischF(2002).
"Sweave:DynamicGenerationofStatisticalReportsUsingLiterateDataAnalysis.
"InCOMPSTAT2002ProceedingsinComputationalStatistics,69,pp.
575–580.
PhysicaVerlag,Heidelberg.
PengRD(2012).
cacheSweave:ToolsforcachingSweavecomputations.
Rpackageversion0.
6-1,URLhttp://CRAN.
R-project.
org/package=cacheSweave.
SharpsteenC,BrackenC(2012).
tikzDevice:ADeviceforRGraphicsOutputinPGF/TikZFormat.
Rpackageversion0.
6.
2,URLhttp://CRAN.
R-project.
org/package=tikzDevice.
WickhamH(2012).
evaluate:Parsingandevaluationtoolsthatprovidemoredetailsthanthedefault.
Rpackageversion0.
4.
3.
XieY(2012a).
animation:Agalleryofanimationsinstatisticsandutilitiestocreateanimations.
Rpackageversion2.
1.
1,URLhttps://github.
com/yihui/animation.
XieY(2012b).
formatR:FormatRCodeAutomatically.
Rpackageversion0.
7,URLhttp://yihui.
name/formatR.
XieY(2012c).
knitr:Ageneral-purposepackagefordynamicreportgenerationinR.
Rpackageversion0.
9,URLhttp://yihui.
name/knitr/.
11