R Packages : Organize, Test, Document, and Share Your Code

Turn your R code into packages that others can easily download and use. This practical book shows you how to bundle reusable R functions, sample data, and documentation together by applying author Hadley Wickham’s package development philosophy. In the process, you’ll work with devtools, roxygen, and testthat, a set of R packages that automate common development tasks. Devtools encapsulates best practices that Hadley has learned from years of working with this programming language. Ideal for developers, data scientists, and programmers with various backgrounds, this book starts you with the basics and shows you how to improve your package writing over time. You’ll learn to focus on what you want your package to do, rather than think about package structure. * Learn about the most useful components of an R package, including vignettes and unit tests * Automate anything you can, taking advantage of the years of development experience embodied in devtools * Get tips on good style, such as organizing functions into files * Streamline your development process with devtools * Learn the best way to submit your package to the Comprehensive R Archive Network (CRAN) * Learn from a well-respected member of the R community who created 30 R packages, including ggplot2, dplyr, and tidyr Table of Contents 5 Preface 11 In This Book 11 Conventions Used in This Book 13 Using Code Examples 14 Safari庐 Books Online 14 How to Contact Us 15 Acknowledgments 15 Part I. Getting Started 17 Chapter 1. Introduction 19 Philosophy 20 Getting Started 21 Conventions 22 Colophon 22 Chapter 2. Package Structure 23 Naming Your Package 23 Requirements for a Name 23 Strategies for Creating a Name 23 Creating a Package 24 RStudio Projects 26 What Is an RStudio Project File? 27 What Is a Package? 29 Source Packages 29 Bundled Packages 30 Binary Packages 31 Installed Packages 32 In-Memory Packages 33 What Is a Library? 34 Part II. Package Components 37 Chapter 3. R Code 39 R Code Workflow 39 Organizing Your Functions 39 Code Style 40 Object Names 41 Spacing 42 Curly Braces 43 Line Length 43 Indentation 43 Assignment 44 Commenting Guidelines 44 Top-Level Code 45 Loading Code 45 The R Landscape 46 When You Do Need Side Effects 47 S4 Classes, Generics, and Methods 49 CRAN Notes 49 Chapter 4. Package Metadata 51 Dependencies: What Does Your Package Need? 52 Versioning 54 Other Dependencies 54 Title and Description: What Does Your Package Do? 55 Author: Who Are You? 56 On CRAN 58 License: Who Can Use Your Package? 58 On CRAN 59 Version 59 Other Components 60 Chapter 5. Object Documentation 61 The Documentation Workflow 62 Alternative Documentation Workflow 64 Roxygen Comments 65 Documenting Functions 67 Documenting Datasets 69 Documenting Packages 69 Documenting Classes, Generics, and Methods 69 S3 69 S4 70 RC 71 Special Characters 72 Do Repeat Yourself 72 Inheriting Parameters from Other Functions 73 Documenting Multiple Functions in the Same File 73 Text Formatting Reference Sheet 74 Character Formatting 75 Links 75 Lists 75 Mathematics 76 Tables 76 Chapter 6. Vignettes: Long-Form Documentation 77 Vignette Workflow 78 Metadata 79 Markdown 80 Sections 81 Lists 81 Inline Formatting 82 Tables 82 Code 82 Knitr 83 Options 84 Development Cycle 85 Advice for Writing Vignettes 86 Organization 86 CRAN Notes 87 Where to Go Next 87 Chapter 7. Testing 89 Test Workflow 90 Test Structure 91 Expectations 92 Writing Tests 94 What to Test 95 Skipping a Test 95 Building Your Own Testing Tools 96 Test Files 98 CRAN Notes 98 Chapter 8. Namespace 99 Motivation 99 Search Path 100 The NAMESPACE 102 Workflow 104 Exports 104 S3 105 S4 106 RC 106 Data 106 Imports 106 R Functions 107 S3 107 S4 108 Compiled Functions 108 Chapter 9. External Data 109 Exported Data 109 Documenting Datasets 111 Internal Data 111 Raw Data 112 Other Data 112 CRAN Notes 112 Chapter 10. Compiled Code 115 C++ 115 Workflow 116 Documentation 117 Exporting C++ Code 118 Importing C++ Code 118 Best Practices 118 C 119 Getting Started with .Call() 120 Getting Started with .C() 121 Workflow 122 Exporting C Code 122 Importing C Code 124 Best Practices 124 Debugging Compiled Code 125 Makefiles 127 Other Languages 127 Licensing 128 Development Workflow 128 CRAN Issues 128 Chapter 11. Installed Files 131 Package Citation 132 Other Languages 133 Chapter 12. Other Components 135 Demos 135 Part III. Best Practices 137 Chapter 13. Git and GitHub 139 RStudio, Git, and GitHub 140 Initial Setup 141 Creating a Local Git Repository 142 Seeing What鈥檚 Changed 144 Recording Changes 146 Best Practices for Commits 148 Ignoring Files 149 Undoing Mistakes 150 Synchronizing with GitHub 152 Benefits of Using GitHub 153 Working with Others 155 Issues 156 Branches 157 Making a Pull Request 158 Submitting a Pull Request to Another Repo 160 Reviewing and Accepting Pull Requests 162 Learning More 163 Chapter 14. Automated Checking 165 Workflow 165 Checks 166 Check Metadata 166 Package Structure 167 Description 169 Namespace 170 R Code 171 Data 173 Documentation 174 Demos 176 Compiled Code 176 Tests 176 Vignettes 177 Checking After Every Commit with Travis 178 Basic Config 178 Other Uses 179 Chapter 15. Releasing a Package 181 Version Number 181 Backward Compatibility 182 The Submission Process 184 Test Environments 186 Check Results 187 Reverse Dependencies 187 CRAN Policies 188 Important Files 189 README.md 189 README.Rmd 189 NEWS.md 190 Release 191 On Failure 192 Binary Builds 193 Prepare for Next Version 193 Publicizing Your Package 194 Congratulations! 194 Index 195 About the Author 201 Turn your R code into packages that others can easily download and use. This practical book shows you how to bundle reusable R functions, sample data, and documentation together by applying author Hadley Wickham’s package development philosophy. In the process, you’ll work with devtools, roxygen, and testthat, a set of R packages that automate common development tasks. Devtools encapsulates best practices that Hadley has learned from years of working with this programming language.Ideal for developers, data scientists, and programmers with various backgrounds, this book starts you with the basics and shows you how to improve your package writing over time. You’ll learn to focus on what you want your package to do, rather than think about package structure.Learn about the most useful components of an R package, including vignettes and unit testsAutomate anything you can, taking advantage of the years of development experience embodied in devtoolsGet tips on good style, such as organizing functions into filesStreamline your development process with devtoolsLearn the best way to submit your package to the Comprehensive R Archive Network (CRAN)Learn from a well-respected member of the R community who created 30 R packages, including ggplot2, dplyr, and tidyr Turn your R code into packages that others can easily download and use. This practical book shows you how to bundle reusable R functions, sample data, and documentation together by applying author Hadley Wickham's package development philosophy. In the process, you'll work with devtools, roxygen, and testthat, a set of R packages that automate common development tasks. Devtools encapsulates best practices that Hadley has learned from years of working with this programming language.Ideal for developers, data scientists, and programmers with various backgrounds, this book starts you with the basics and shows you how to improve your package writing over time. You'll learn to focus on what you want your package to do, rather than think about package structure. Ideal for developers, data scientists, and programmers with various backgrounds, this book starts with the basics and shows you how to improve your package writing over time. You'll learn to focus on what you want your package to do, rather than think about package structure