{"id":154892,"date":"2018-11-28T19:26:01","date_gmt":"2018-11-29T03:26:01","guid":{"rendered":"https:\/\/www.esri.com\/about\/newsroom\/?post_type=arcuser&p=154892"},"modified":"2024-04-15T12:56:33","modified_gmt":"2024-04-15T19:56:33","slug":"coding-standards-for-jupyter-notebook","status":"publish","type":"arcuser","link":"https:\/\/www.esri.com\/about\/newsroom\/arcuser\/coding-standards-for-jupyter-notebook","title":{"rendered":"Coding Standards for Jupyter Notebook"},"author":1031,"featured_media":0,"menu_order":0,"template":"","format":"standard","meta":{"_acf_changed":false,"sync_status":"","episode_type":"","audio_file":"","castos_file_data":"","podmotor_file_id":"","cover_image":"","cover_image_id":"","duration":"","filesize":"","filesize_raw":"","date_recorded":"","explicit":"","block":"","itunes_episode_number":"","itunes_title":"","itunes_season_number":"","itunes_episode_type":"","_links_to":"","_links_to_target":""},"categories":[10712,25002],"tags":[198052],"arcuser_issues":[184702],"class_list":["post-154892","arcuser","type-arcuser","status-publish","format-standard","hentry","category-arcgis-api-for-python","category-developers-corner","tag-jupyter-notebook","arcuser_issues-fall-2018"],"acf":{"short_description":"Follow these guidelines when using Jupyter Notebook to make them communicate your work effectively. ","pdf":{"host_remotely":false,"file":"","file_url":""},"flexible_content":[{"acf_fc_layout":"pdf","file":154922},{"acf_fc_layout":"content","content":"Jupyter Notebook has become incredibly popular among data scientists and general users of Python and R. While the Jupyter framework is liberal and lets you be creative, it would benefit you, your team, and your readers if you define a structure and follow it. Based on my experience as developer evangelist and the author of public-facing notebooks for the last three years, I share in this article the patterns I recommend for writing data science samples using Jupyter Notebook."},{"acf_fc_layout":"image","image":154932,"image_position":"center","orientation":"horizontal","hyperlink":""},{"acf_fc_layout":"content","content":"

Use Headings and Markdown Lavishly<\/h2>\r\nStart your notebook with Heading level 1 and give it a title. Follow with a narrative explaining what the notebook aims to do, where the data is sourced, and what the user can expect.\r\n\r\nBreak down your notebook into smaller parts and use Heading levels 2, 3, 4, and so on for the hierarchy of topics and sub-topics. A notebook should ideally have just one Heading level 1, under which multiple Heading levels of 2, 3, 4, and so on are nested. To enhance your notebook, embed images and use different typography such as bold or italic, or insert code to enliven text."},{"acf_fc_layout":"image","image":154942,"image_position":"center","orientation":"horizontal","hyperlink":""},{"acf_fc_layout":"content","content":"

Use LaTeX for Equations<\/h2>\r\nLaTeX is a document preparation system that uses the TeX macro language. A cheat sheet from the New York University website is linked to the online version of this article. Insert LaTeX equations inline within two dollar signs $\u2026$.\r\n\r\nBreak Longer Segments of Code into Multiple Cells\r\n\r\nTry to keep your code cells as short as possible. Break them up by adding markdown cells in between and add explanatory text. A cell for a single line of code is too short. A cell with more than 15 lines of code is too long.\r\n

Plot Profusely<\/h2>\r\nMatplotlib, a Python 2D plotting library, is great, but check out higher-level plotting libraries such as Seaborn Pandas.DataFrame.plot()<\/em> before you settle for Matplotlib. Use plt.tight_layout()<\/em> to autosize your plots to fit the notebook. Use subplots when you want to show a grid of plots. And finally, ensure that your plots have a legend, title, axes names, and discernible symbols.\r\n

Coding Standards for Your Python Snippets<\/h2>\r\nFor variable and function names, use underscores to separate words\u2014in other words, snake_name_your_variables\u2014instead of separating words with cases or camelCasingYourVariables. The exception is class names, which should use camel casing and start with the capital case.\r\n\r\nDo all imports at the top of the notebook. This way, the reader knows what libraries are used and can ensure that their environment is ready.\r\n\r\nName variables so that they don\u2019t clobber built-ins. For instance, call your map object map1 and map2 instead of map, which will hide built-in map()<\/em> function. Don\u2019t call variables as dict or list, which will hide built-in data structures with the same names.\r\n\r\nFor enhanced performance, use the Spatially Enabled DataFrame (available since version 1.5 of ArcGIS API for Python) in place of SpatialDataFrame objects.\r\n

Use Round Numbers for Display Purposes<\/h2>\r\nQuickly round your DataFrames during display by calling the DataFrame_obj.round()<\/em> method. For instance: usa_house_scaled.describe().round(3)<\/em> will display numeric columns in your DataFrame rounded to three decimal digits.\r\n

Be Explicit about Uncommon Libraries<\/h2>\r\nIt is generally a good practice to import all your dependencies at the beginning of your script. However, in the notebook medium, you might prefer to import them as and when necessary to better explain your work. This is especially true if you import a lot of dependencies at the function level. If you use a library that is not shipped with base anaconda, then the user must run installation steps and relaunch the notebook. Make this explicit at the beginning of the notebook."},{"acf_fc_layout":"image","image":154952,"image_position":"center","orientation":"horizontal","hyperlink":""},{"acf_fc_layout":"content","content":"

Structure of Your Data Science Notebook<\/h2>\r\nBy and large, use headings to structure your notebook as you would a paper for a scientific journal.\r\n

Heading 1: Title<\/h3>\r\nCover the narrative or abstract and include a TOC.\r\n

Heading 2: Get data<\/h3>\r\nImport libraries and search for and get required datasets.\r\n

Heading 2: Exploratory data analysis<\/h3>\r\nUse maps and charts lavishly to show different aspects of the data.\r\n

Heading 2: Feature engineering<\/h3>\r\nUse pandas and other libraries to prepare your data for training. After each significant transformation, show previews of your data by printing the first three or five records of your DataFrame.\r\n

Heading 2: Analysis<\/h3>\r\nPerform analysis and build and train models.\r\n

Heading 3: Evaluation<\/h3>\r\nEvaluate model and note if assumptions are met by using both charts and metrics. Run predictions, evaluate results using both charts and metrics. Use more than one metric for evaluation.\r\n

Heading 2: Act on the analysis<\/h3>\r\nPersist the results, either by writing to disk or publishing them to the web. Elucidate with maps and charts as applicable. If you built a prediction model, publish it as a web tool (REST API). If you built an explanatory notebook, publish it as an article or report.\r\n

Heading 2: Conclusion<\/h3>\r\nSummarize your work by starting from your problem statement, moving to the approach you followed, and describing the results you obtained."}],"references":null},"yoast_head":"\nCoding Standards for Jupyter Notebook | Fall 2018 | ArcUser<\/title>\n<meta name=\"description\" content=\"The Jupyter framework lets you be creative, it is beneficial you, your team if you define a structure and follow it when using it.\" \/>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/www.esri.com\/about\/newsroom\/arcuser\/coding-standards-for-jupyter-notebook\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Coding Standards for Jupyter Notebook\" \/>\n<meta property=\"og:description\" content=\"The Jupyter framework lets you be creative, it is beneficial you, your team if you define a structure and follow it when using it.\" \/>\n<meta property=\"og:url\" content=\"https:\/\/www.esri.com\/about\/newsroom\/arcuser\/coding-standards-for-jupyter-notebook\" \/>\n<meta property=\"og:site_name\" content=\"Esri\" \/>\n<meta property=\"article:publisher\" content=\"https:\/\/www.facebook.com\/esrigis\/\" \/>\n<meta property=\"article:modified_time\" content=\"2024-04-15T19:56:33+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/www.esri.com\/about\/newsroom\/app\/uploads\/2018\/11\/aufall18_standards_card.jpg\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:site\" content=\"@Esri\" \/>\n<meta name=\"twitter:label1\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data1\" content=\"5 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\n\t \"@context\": \"https:\/\/schema.org\",\n\t \"@graph\": [\n\t {\n\t \"@type\": \"WebPage\",\n\t \"@id\": \"https:\/\/www.esri.com\/about\/newsroom\/arcuser\/coding-standards-for-jupyter-notebook\",\n\t \"url\": \"https:\/\/www.esri.com\/about\/newsroom\/arcuser\/coding-standards-for-jupyter-notebook\",\n\t \"name\": \"Coding Standards for Jupyter Notebook | Fall 2018 | ArcUser\",\n\t \"isPartOf\": {\n\t \"@id\": \"https:\/\/www.esri.com\/about\/newsroom\/#website\"\n\t },\n\t \"datePublished\": \"2018-11-29T03:26:01+00:00\",\n\t \"dateModified\": \"2024-04-15T19:56:33+00:00\",\n\t \"description\": \"The Jupyter framework lets you be creative, it is beneficial you, your team if you define a structure and follow it when using it.\",\n\t \"breadcrumb\": {\n\t \"@id\": \"https:\/\/www.esri.com\/about\/newsroom\/arcuser\/coding-standards-for-jupyter-notebook#breadcrumb\"\n\t },\n\t \"inLanguage\": \"en-US\",\n\t \"potentialAction\": [\n\t {\n\t \"@type\": \"ReadAction\",\n\t \"target\": [\n\t \"https:\/\/www.esri.com\/about\/newsroom\/arcuser\/coding-standards-for-jupyter-notebook\"\n\t ]\n\t }\n\t ]\n\t },\n\t {\n\t \"@type\": \"BreadcrumbList\",\n\t \"@id\": \"https:\/\/www.esri.com\/about\/newsroom\/arcuser\/coding-standards-for-jupyter-notebook#breadcrumb\",\n\t \"itemListElement\": [\n\t {\n\t \"@type\": \"ListItem\",\n\t \"position\": 1,\n\t \"name\": \"Home\",\n\t \"item\": \"https:\/\/www.esri.com\/about\/newsroom\"\n\t },\n\t {\n\t \"@type\": \"ListItem\",\n\t \"position\": 2,\n\t \"name\": \"Coding Standards for Jupyter Notebook\"\n\t }\n\t ]\n\t },\n\t {\n\t \"@type\": \"WebSite\",\n\t \"@id\": \"https:\/\/www.esri.com\/about\/newsroom\/#website\",\n\t \"url\": \"https:\/\/www.esri.com\/about\/newsroom\/\",\n\t \"name\": \"Esri\",\n\t \"description\": \"Esri Newsroom\",\n\t \"potentialAction\": [\n\t {\n\t \"@type\": \"SearchAction\",\n\t \"target\": {\n\t \"@type\": \"EntryPoint\",\n\t \"urlTemplate\": \"https:\/\/www.esri.com\/about\/newsroom\/?s={search_term_string}\"\n\t },\n\t \"query-input\": {\n\t \"@type\": \"PropertyValueSpecification\",\n\t \"valueRequired\": true,\n\t \"valueName\": \"search_term_string\"\n\t }\n\t }\n\t ],\n\t \"inLanguage\": \"en-US\"\n\t },\n\t {\n\t \"@type\": \"Person\",\n\t \"@id\": \"https:\/\/www.esri.com\/about\/newsroom\/#\/schema\/person\/82e5143bcdebadf8fd64d84e503ca468\",\n\t \"name\": \"Monica Pratt\",\n\t \"image\": {\n\t \"@type\": \"ImageObject\",\n\t \"inLanguage\": \"en-US\",\n\t \"@id\": \"https:\/\/www.esri.com\/about\/newsroom\/#\/schema\/person\/image\/\",\n\t \"url\": \"https:\/\/www.esri.com\/about\/newsroom\/app\/uploads\/2018\/08\/MonicaMug_agol2.jpg\",\n\t \"contentUrl\": \"https:\/\/www.esri.com\/about\/newsroom\/app\/uploads\/2018\/08\/MonicaMug_agol2.jpg\",\n\t \"caption\": \"Monica Pratt\"\n\t },\n\t \"description\": \"Monica Pratt is the founding and current editor of ArcUser magazine, the executive editor of ArcNews magazine, the editor of Esri Globe and head of the Publications team at Esri. She has been writing on technology topics, specializing in GIS, for more than 30 years. Before joining Esri in 1997, she worked for newspapers and in the financial industry.\",\n\t \"sameAs\": [\n\t \"https:\/\/x.com\/ArcUser\"\n\t ],\n\t \"url\": \"\"\n\t }\n\t ]\n\t}<\/script>\n<!-- \/ Yoast SEO Premium plugin. -->","yoast_head_json":{"title":"Coding Standards for Jupyter Notebook | Fall 2018 | ArcUser","description":"The Jupyter framework lets you be creative, it is beneficial you, your team if you define a structure and follow it when using it.","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/www.esri.com\/about\/newsroom\/arcuser\/coding-standards-for-jupyter-notebook","og_locale":"en_US","og_type":"article","og_title":"Coding Standards for Jupyter Notebook","og_description":"The Jupyter framework lets you be creative, it is beneficial you, your team if you define a structure and follow it when using it.","og_url":"https:\/\/www.esri.com\/about\/newsroom\/arcuser\/coding-standards-for-jupyter-notebook","og_site_name":"Esri","article_publisher":"https:\/\/www.facebook.com\/esrigis\/","article_modified_time":"2024-04-15T19:56:33+00:00","og_image":[{"url":"https:\/\/www.esri.com\/about\/newsroom\/app\/uploads\/2018\/11\/aufall18_standards_card.jpg","type":"","width":"","height":""}],"twitter_card":"summary_large_image","twitter_site":"@Esri","twitter_misc":{"Est. reading time":"5 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/www.esri.com\/about\/newsroom\/arcuser\/coding-standards-for-jupyter-notebook","url":"https:\/\/www.esri.com\/about\/newsroom\/arcuser\/coding-standards-for-jupyter-notebook","name":"Coding Standards for Jupyter Notebook | Fall 2018 | ArcUser","isPartOf":{"@id":"https:\/\/www.esri.com\/about\/newsroom\/#website"},"datePublished":"2018-11-29T03:26:01+00:00","dateModified":"2024-04-15T19:56:33+00:00","description":"The Jupyter framework lets you be creative, it is beneficial you, your team if you define a structure and follow it when using it.","breadcrumb":{"@id":"https:\/\/www.esri.com\/about\/newsroom\/arcuser\/coding-standards-for-jupyter-notebook#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/www.esri.com\/about\/newsroom\/arcuser\/coding-standards-for-jupyter-notebook"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/www.esri.com\/about\/newsroom\/arcuser\/coding-standards-for-jupyter-notebook#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/www.esri.com\/about\/newsroom"},{"@type":"ListItem","position":2,"name":"Coding Standards for Jupyter Notebook"}]},{"@type":"WebSite","@id":"https:\/\/www.esri.com\/about\/newsroom\/#website","url":"https:\/\/www.esri.com\/about\/newsroom\/","name":"Esri","description":"Esri Newsroom","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/www.esri.com\/about\/newsroom\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-US"},{"@type":"Person","@id":"https:\/\/www.esri.com\/about\/newsroom\/#\/schema\/person\/82e5143bcdebadf8fd64d84e503ca468","name":"Monica Pratt","image":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/www.esri.com\/about\/newsroom\/#\/schema\/person\/image\/","url":"https:\/\/www.esri.com\/about\/newsroom\/app\/uploads\/2018\/08\/MonicaMug_agol2.jpg","contentUrl":"https:\/\/www.esri.com\/about\/newsroom\/app\/uploads\/2018\/08\/MonicaMug_agol2.jpg","caption":"Monica Pratt"},"description":"Monica Pratt is the founding and current editor of ArcUser magazine, the executive editor of ArcNews magazine, the editor of Esri Globe and head of the Publications team at Esri. She has been writing on technology topics, specializing in GIS, for more than 30 years. Before joining Esri in 1997, she worked for newspapers and in the financial industry.","sameAs":["https:\/\/x.com\/ArcUser"],"url":""}]}},"sort_order":"6","_links":{"self":[{"href":"https:\/\/www.esri.com\/about\/newsroom\/wp-json\/wp\/v2\/arcuser\/154892","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.esri.com\/about\/newsroom\/wp-json\/wp\/v2\/arcuser"}],"about":[{"href":"https:\/\/www.esri.com\/about\/newsroom\/wp-json\/wp\/v2\/types\/arcuser"}],"author":[{"embeddable":true,"href":"https:\/\/www.esri.com\/about\/newsroom\/wp-json\/wp\/v2\/users\/1031"}],"version-history":[{"count":0,"href":"https:\/\/www.esri.com\/about\/newsroom\/wp-json\/wp\/v2\/arcuser\/154892\/revisions"}],"wp:attachment":[{"href":"https:\/\/www.esri.com\/about\/newsroom\/wp-json\/wp\/v2\/media?parent=154892"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.esri.com\/about\/newsroom\/wp-json\/wp\/v2\/categories?post=154892"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.esri.com\/about\/newsroom\/wp-json\/wp\/v2\/tags?post=154892"},{"taxonomy":"arcuser_issues","embeddable":true,"href":"https:\/\/www.esri.com\/about\/newsroom\/wp-json\/wp\/v2\/arcuser_issues?post=154892"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}