├── .gitignore ├── Gemfile ├── Gemfile.lock ├── Guardfile ├── LICENSE ├── Makefile ├── README.md ├── _build ├── 01 │ ├── 1 │ │ └── intro.md │ ├── 2 │ │ └── why-data-science.md │ ├── 3 │ │ ├── Plotting_the_Classics.md │ │ └── subsection │ │ │ ├── subsections.md │ │ │ └── subsectiontwo.md │ └── what-is-data-science.md ├── 02 │ ├── 1 │ │ └── observation-and-visualization-john-snow-and-the-broad-street-pump.md │ ├── 2 │ │ └── snow-s-grand-experiment.md │ ├── 3 │ │ └── establishing-causality.md │ ├── 4 │ │ └── randomization.md │ ├── 5 │ │ └── endnote.md │ └── causality-and-experiments.md ├── 03 │ ├── 1 │ │ └── Expressions.md │ ├── 2 │ │ └── Names.md │ ├── 3 │ │ └── Calls.md │ ├── 4 │ │ └── Introduction_to_Tables.md │ └── programming-in-python.md ├── 04 │ ├── 1 │ │ └── Numbers.md │ ├── 2 │ │ └── Strings.md │ ├── 3 │ │ └── Comparison.md │ └── Types.md ├── features │ ├── cool.jpg │ ├── features.md │ ├── markdown.md │ └── notebooks.md ├── guide │ ├── 00_intro.md │ ├── 01_overview.md │ ├── 02_setup.md │ ├── 03_configure.md │ ├── 04_build.md │ ├── 05_publish.md │ ├── 06_faq.md │ └── 07_advanced.md └── intro.md ├── _config.yml ├── _data └── toc.yml ├── _includes ├── css_entry.scss ├── dom-update.html ├── fb_tags.html ├── head.html ├── interact-update.html ├── interact.html ├── mathjax.html ├── metadata.json ├── onthispage.html ├── page-nav.html ├── sidebar-toggle.html └── sidebar.html ├── _layouts └── default.html ├── _sass ├── components │ ├── _components.interact-button.scss │ ├── _components.page__nav.scss │ ├── _components.sidebar-toggle.scss │ ├── _components.textbook.scss │ ├── _components.textbook__page.scss │ ├── _components.textbook__sidebar-right.scss │ └── _components.textbook__sidebar.scss ├── elements │ ├── _elements.links.scss │ ├── _elements.syntax-highlighting.scss │ ├── _elements.tables.scss │ ├── _elements.typography.scss │ └── _elements.variables.scss ├── generic │ └── _generic.phone-scrolling.scss ├── hamburgers │ ├── _base.scss │ ├── hamburgers.scss │ └── types │ │ └── _arrowalt.scss ├── inuitcss │ ├── elements │ │ ├── _elements.headings.scss │ │ ├── _elements.images.scss │ │ ├── _elements.page.scss │ │ └── _elements.tables.scss │ ├── generic │ │ ├── _generic.box-sizing.scss │ │ ├── _generic.normalize.scss │ │ ├── _generic.reset.scss │ │ └── _generic.shared.scss │ ├── objects │ │ ├── _objects.block.scss │ │ ├── _objects.box.scss │ │ ├── _objects.crop.scss │ │ ├── _objects.flag.scss │ │ ├── _objects.layout.scss │ │ ├── _objects.list-bare.scss │ │ ├── _objects.list-inline.scss │ │ ├── _objects.media.scss │ │ ├── _objects.pack.scss │ │ ├── _objects.ratio.scss │ │ ├── _objects.table.scss │ │ └── _objects.wrapper.scss │ ├── settings │ │ ├── _example.settings.config.scss │ │ ├── _example.settings.global.scss │ │ └── _settings.core.scss │ ├── tools │ │ ├── _tools.clearfix.scss │ │ ├── _tools.font-size.scss │ │ ├── _tools.hidden.scss │ │ └── _tools.mq.scss │ └── utilities │ │ ├── _utilities.clearfix.scss │ │ ├── _utilities.headings.scss │ │ ├── _utilities.hide.scss │ │ ├── _utilities.print.scss │ │ ├── _utilities.responsive-spacings.scss │ │ ├── _utilities.spacings.scss │ │ └── _utilities.widths.scss ├── main.scss ├── objects │ ├── _objects.copy-button.scss │ └── _objects.tooltip.scss └── settings │ └── settings.global.scss ├── assets ├── copy-button.svg ├── css │ └── styles.scss ├── js │ ├── ga.js │ ├── scripts.js │ └── turbolinks.js └── templates │ └── jekyllmd.tpl ├── content ├── 01 │ ├── 1 │ │ ├── 1 │ │ │ └── computational-tools.md │ │ ├── 2 │ │ │ └── statistical-techniques.md │ │ └── intro.md │ ├── 2 │ │ └── why-data-science.md │ ├── 3 │ │ ├── Plotting_the_Classics.ipynb │ │ └── subsection │ │ │ ├── subsections.md │ │ │ └── subsectiontwo.md │ └── what-is-data-science.md ├── 02 │ ├── 1 │ │ └── observation-and-visualization-john-snow-and-the-broad-street-pump.md │ ├── 2 │ │ └── snow-s-grand-experiment.md │ ├── 3 │ │ └── establishing-causality.md │ ├── 4 │ │ └── randomization.md │ ├── 5 │ │ └── endnote.md │ └── causality-and-experiments.md ├── 03 │ ├── 1 │ │ └── Expressions.ipynb │ ├── 2 │ │ ├── 1 │ │ │ └── Growth.ipynb │ │ └── Names.ipynb │ ├── 3 │ │ └── Calls.ipynb │ ├── 4 │ │ └── Introduction_to_Tables.ipynb │ └── programming-in-python.md ├── 04 │ ├── 1 │ │ └── Numbers.ipynb │ ├── 2 │ │ ├── 1 │ │ │ └── String_Methods.ipynb │ │ └── Strings.ipynb │ ├── 3 │ │ └── Comparison.ipynb │ └── Types.ipynb ├── features │ ├── cool.jpg │ ├── features.md │ ├── markdown.md │ └── notebooks.ipynb ├── guide │ ├── 00_intro.md │ ├── 01_overview.md │ ├── 02_setup.md │ ├── 03_configure.md │ ├── 04_build.md │ ├── 05_publish.md │ ├── 06_faq.md │ └── 07_advanced.md └── intro.md ├── images ├── C-3PO_droid.png ├── logo │ ├── download.svg │ ├── favicon.ico │ ├── jupyter.png │ ├── logo.png │ └── logo.psd ├── monty_hall_goat.png ├── snow_map.jpg └── snow_map2.jpg ├── requirements.txt └── scripts ├── clean.py ├── execute_all_notebooks.py └── generate_book.py /.gitignore: -------------------------------------------------------------------------------- 1 | # Byte-compiled / optimized / DLL files 2 | __pycache__/ 3 | *.py[cod] 4 | *$py.class 5 | 6 | # C extensions 7 | *.so 8 | 9 | # Distribution / packaging 10 | .Python 11 | build/ 12 | develop-eggs/ 13 | dist/ 14 | downloads/ 15 | eggs/ 16 | .eggs/ 17 | lib/ 18 | lib64/ 19 | parts/ 20 | sdist/ 21 | var/ 22 | wheels/ 23 | *.egg-info/ 24 | .installed.cfg 25 | *.egg 26 | MANIFEST 27 | 28 | # PyInstaller 29 | # Usually these files are written by a python script from a template 30 | # before PyInstaller builds the exe, so as to inject date/other infos into it. 31 | *.manifest 32 | *.spec 33 | 34 | # Installer logs 35 | pip-log.txt 36 | pip-delete-this-directory.txt 37 | 38 | # Unit test / coverage reports 39 | htmlcov/ 40 | .tox/ 41 | .coverage 42 | .coverage.* 43 | .cache 44 | nosetests.xml 45 | coverage.xml 46 | *.cover 47 | .hypothesis/ 48 | .pytest_cache/ 49 | 50 | # Translations 51 | *.mo 52 | *.pot 53 | 54 | # Django stuff: 55 | *.log 56 | local_settings.py 57 | db.sqlite3 58 | 59 | # Flask stuff: 60 | instance/ 61 | .webassets-cache 62 | 63 | # Scrapy stuff: 64 | .scrapy 65 | 66 | # Sphinx documentation 67 | docs/_build/ 68 | 69 | # PyBuilder 70 | target/ 71 | 72 | # Jupyter Notebook 73 | .ipynb_checkpoints 74 | 75 | # pyenv 76 | .python-version 77 | 78 | # celery beat schedule file 79 | celerybeat-schedule 80 | 81 | # SageMath parsed files 82 | *.sage.py 83 | 84 | # Environments 85 | .env 86 | .venv 87 | env/ 88 | venv/ 89 | ENV/ 90 | env.bak/ 91 | venv.bak/ 92 | .vscode 93 | .ipynb_checkpoints 94 | 95 | # Spyder project settings 96 | .spyderproject 97 | .spyproject 98 | 99 | # Rope project settings 100 | .ropeproject 101 | 102 | # mkdocs documentation 103 | _site/ 104 | 105 | # mypy 106 | .mypy_cache/ 107 | 108 | .sass-cache 109 | .jekyll-metadata 110 | .DS_Store 111 | -------------------------------------------------------------------------------- /Gemfile: -------------------------------------------------------------------------------- 1 | source 'https://rubygems.org' 2 | 3 | group :jekyll_plugins do 4 | gem 'github-pages' 5 | gem 'jekyll-feed', '~> 0.6' 6 | end 7 | 8 | # Windows does not include zoneinfo files, so bundle the tzinfo-data gem 9 | gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby] 10 | 11 | # Performance-booster for watching directories on Windows 12 | gem 'wdm', '~> 0.1.0' if Gem.win_platform? 13 | 14 | # Development tools 15 | gem 'guard', '~> 2.14.2' 16 | gem 'guard-jekyll-plus', '~> 2.0.2' 17 | gem 'guard-livereload', '~> 2.5.2' 18 | 19 | # Textbook plugins 20 | gem 'jekyll-redirect-from' 21 | -------------------------------------------------------------------------------- /Guardfile: -------------------------------------------------------------------------------- 1 | guard 'jekyll-plus', serve: true do 2 | watch /.*/ 3 | ignore /^_site/ 4 | end 5 | 6 | guard 'livereload' do 7 | watch /.*/ 8 | end 9 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2018 Chris Holdgraf 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | .PHONY: help book clean serve 2 | 3 | help: 4 | @echo "Please use 'make ' where is one of:" 5 | @echo " book to convert the `notebooks/` folder into Jekyll markdown in `chapters/`" 6 | @echo " clean to clean out site build files" 7 | @echo " runall to run all notebooks in-place, capturing outputs with the notebook" 8 | @echo " serve to serve the repository locally with Jekyll" 9 | 10 | book: 11 | python scripts/generate_book.py 12 | 13 | runall: 14 | python scripts/execute_all_notebooks.py 15 | 16 | clean: 17 | python scripts/clean.py 18 | 19 | serve: 20 | bundle exec guard 21 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Jupyter Books 2 | 3 | 4 | 5 | This is a guide and template for hosting your own book using 6 | Jupyter Notebooks and Jekyll. 7 | 8 | Here are some highlights: 9 | 10 | * All course content is written in markdown and Jupyter Notebooks, stored in `notebooks/` 11 | * This site comes packaged with helper scripts to convert these into Jekyll pages (in `scripts/`) 12 | * Pages can have [Binder](https://mybinder.org) or JupyterHub links automatically added for interactivity. 13 | * The website itself is based on Jekyll, and is highly extensible and can be freely-hosted on GitHub. 14 | 15 | This repository comes with some sample textbook files from the Data 8 course 16 | for Data Science at UC Berkeley. You can update these materials and all site 17 | content with your own, and have a Jupyter-based textbook ready to go shortly! 18 | 19 | Here are a few links of interest: 20 | 21 | * **[A demo of the hosted textbook](http://predictablynoisy.com/jupyter-book/ )** 22 | * **[A short guide to deploying your own textbook](https://predictablynoisy.com/jupyter-book/ch/guide/00_intro)** 23 | * **[The markdown version of the guide in this repo](notebooks/guide/)** 24 | 25 | See the [live demo of the template here](https://predictablynoisy.com/jupyter-book). 26 | 27 | ## Explore this book 28 | 29 | This website is an example of a Jupyter Book. You can explore the chapters of the book 30 | by clicking on links in the sidebar to the left. Or, you can move linearly forward and 31 | backwards by clicking the left/right arrow on your computer. 32 | 33 | ## Contribute or improve the book 34 | 35 | Notice some inefficient CSS? A typo in the text? Want to add a cool feature so that others 36 | can enjoy the improvements to Jupyter Books? Don't hesitate to [open an issue or a PR on the 37 | Jupyter Book template repo](https://github.com/choldgraf/jupyter-book). We'd love your 38 | help! 39 | 40 | ## Acknowledgements 41 | 42 | Jupyter Books was originally created by [Sam Lau][sam] and [Chris Holdgraf][chris] 43 | with support of the **UC Berkeley Data Science Education Program and the Berkeley 44 | Institute for Data Science**. 45 | 46 | [sam]: http://www.samlau.me/ 47 | [chris]: https://predictablynoisy.com 48 | -------------------------------------------------------------------------------- /_build/01/1/intro.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Introduction' 3 | prev_page: 4 | url: /01/what-is-data-science 5 | title: 'Data Science' 6 | next_page: 7 | url: /01/2/why-data-science 8 | title: 'Why Data Science?' 9 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 10 | --- 11 | Chapter 1: Introduction 12 | ======================= 13 | 14 | Data are descriptions of the world around us, collected through observation and 15 | stored on computers. Computers enable us to infer properties of the world from 16 | these descriptions. Data science is the discipline of drawing conclusions from 17 | data using computation. There are three core aspects of effective data 18 | analysis: exploration, prediction, and inference. This text develops a 19 | consistent approach to all three, introducing statistical ideas and fundamental 20 | ideas in computer science concurrently. We focus on a minimal set of core 21 | techniques that they apply to a vast range of real-world 22 | applications. A foundation in data science requires not only understanding 23 | statistical and computational techniques, but also recognizing how they apply 24 | to real scenarios. 25 | 26 | For whatever aspect of the world we wish to study—whether it's the Earth's 27 | weather, the world's markets, political polls, or the human mind—data we 28 | collect typically offer an incomplete description of the subject at hand. A 29 | central challenge of data science is to make reliable conclusions using this 30 | partial information. 31 | 32 | In this endeavor, we will combine two essential tools: computation and 33 | randomization. For example, we may want to understand climate change trends 34 | using temperature observations. Computers will allow us to use all available 35 | information to draw conclusions. Rather than focusing only on the average 36 | temperature of a region, we will consider the whole range of temperatures 37 | together to construct a more nuanced analysis. Randomness will allow us to 38 | consider the many different ways in which incomplete information might be 39 | completed. Rather than assuming that temperatures vary in a particular way, we 40 | will learn to use randomness as a way to imagine many possible scenarios that 41 | are all consistent with the data we observe. 42 | 43 | Applying this approach requires learning to program a computer, and so this 44 | text interleaves a complete introduction to programming that assumes no prior 45 | knowledge. Readers with programming experience will find that we cover several 46 | topics in computation that do not appear in a typical introductory computer 47 | science curriculum. Data science also requires careful reasoning about 48 | quantities, but this text does not assume any background in mathematics or 49 | statistics beyond basic algebra. You will find very few equations in this text. 50 | Instead, techniques are described to readers in the same language in which they 51 | are described to the computers that execute them—a programming language. 52 | -------------------------------------------------------------------------------- /_build/01/2/why-data-science.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Why Data Science?' 3 | prev_page: 4 | url: /01/1/intro 5 | title: 'Introduction' 6 | next_page: 7 | url: /01/3/Plotting_the_Classics 8 | title: 'Plotting the Classics' 9 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 10 | --- 11 | Why Data Science? 12 | ================= 13 | 14 | Most important decisions are made with only partial information and uncertain 15 | outcomes. However, the degree of uncertainty for many decisions can be reduced 16 | sharply by public access to large data sets and the computational tools 17 | required to analyze them effectively. Data-driven decision making has already 18 | transformed a tremendous breadth of industries, including finance, advertising, 19 | manufacturing, and real estate. At the same time, a wide range of academic 20 | disciplines are evolving rapidly to incorporate large-scale data analysis into 21 | their theory and practice. 22 | 23 | Studying data science enables individuals to bring these techniques to bear on 24 | their work, their scientific endeavors, and their personal decisions. Critical 25 | thinking has long been a hallmark of a rigorous education, but critiques are 26 | often most effective when supported by data. A critical analysis of any aspect 27 | of the world, may it be business or social science, involves inductive 28 | reasoning; conclusions can rarely been proven outright, only supported by 29 | the available evidence. Data science provides the means to make precise, 30 | reliable, and quantitative arguments about any set of observations. With 31 | unprecedented access to information and computing, critical thinking about 32 | any aspect of the world that can be measured would be incomplete without 33 | effective inferential techniques. 34 | 35 | The world has too many unanswered questions and difficult challenges to leave 36 | this critical reasoning to only a few specialists. All educated members of 37 | society can build the capacity to reason about data. The tools, techniques, 38 | and data sets are all readily available; this text aims to make them 39 | accessible to everyone. 40 | -------------------------------------------------------------------------------- /_build/01/3/subsection/subsections.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Subsection Demo 1' 3 | prev_page: 4 | url: /01/3/Plotting_the_Classics 5 | title: 'Plotting the Classics' 6 | next_page: 7 | url: /01/3/subsection/subsectiontwo 8 | title: 'Subsection Demo 2' 9 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 10 | --- 11 | # Subsections 12 | 13 | You can also add subsections to your markdown files. These will be 14 | displayed along with the sidebar! -------------------------------------------------------------------------------- /_build/01/3/subsection/subsectiontwo.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Subsection Demo 2' 3 | prev_page: 4 | url: /01/3/subsection/subsections 5 | title: 'Subsection Demo 1' 6 | next_page: 7 | url: /02/causality-and-experiments 8 | title: 'Causality and Experiments' 9 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 10 | --- 11 | # A second subsection page 12 | 13 | And here's another subsection page! -------------------------------------------------------------------------------- /_build/01/what-is-data-science.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Data Science' 3 | prev_page: 4 | url: /guide/07_advanced 5 | title: 'Advanced' 6 | next_page: 7 | url: /01/1/intro 8 | title: 'Introduction' 9 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 10 | --- 11 | What is Data Science 12 | ==================== 13 | 14 | Data Science is about drawing useful conclusions from large and diverse data 15 | sets through exploration, prediction, and inference. Exploration involves 16 | identifying patterns in information. Prediction involves using information 17 | we know to make informed guesses about values we wish we knew. Inference 18 | involves quantifying our degree of certainty: will those patterns we found 19 | also appear in new observations? How accurate are our predictions? Our primary 20 | tools for exploration are visualizations and descriptive statistics, for 21 | prediction are machine learning and optimization, and for inference are 22 | statistical tests and models. 23 | 24 | Statistics is a central component of data science because statistics 25 | studies how to make robust conclusions with incomplete information. Computing 26 | is a central component because programming allows us to apply analysis 27 | techniques to the large and diverse data sets that arise in real-world 28 | applications: not just numbers, but text, images, videos, and sensor readings. 29 | Data science is all of these things, but it is more than the sum of its parts 30 | because of the applications. Through understanding a particular domain, data 31 | scientists learn to ask appropriate questions about their data and correctly 32 | interpret the answers provided by our inferential and computational tools. 33 | -------------------------------------------------------------------------------- /_build/02/2/snow-s-grand-experiment.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Snow’s “Grand Experiment”' 3 | prev_page: 4 | url: /02/1/observation-and-visualization-john-snow-and-the-broad-street-pump 5 | title: 'John Snow and the Broad Street Pump' 6 | next_page: 7 | url: /02/3/establishing-causality 8 | title: 'Establishing Causality' 9 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 10 | --- 11 | Snow’s “Grand Experiment” 12 | ------------------------- 13 | 14 | Encouraged by what he had learned in Soho, Snow completed a more thorough 15 | analysis of cholera deaths. For some time, he had been gathering data on cholera 16 | deaths in an area of London that was served by two water companies. The Lambeth 17 | water company drew its water upriver from where sewage was discharged into the 18 | River Thames. Its water was relatively clean. But the Southwark and Vauxhall 19 | (S&V) company drew its water below the sewage discharge, and thus its supply was 20 | contaminated. 21 | 22 | The map below shows the areas served by the two companies. Snow honed in on the region where the two service areas overlap. 23 | ![Snow’s Other Map](../../images/snow_map2.jpg) 24 | 25 | Snow noticed that there was no systematic difference between the people who were 26 | supplied by S&V and those supplied by Lambeth. “Each company supplies both rich 27 | and poor, both large houses and small; there is no difference either in the 28 | condition or occupation of the persons receiving the water of the different 29 | Companies … there is no difference whatever in the houses or the people 30 | receiving the supply of the two Water Companies, or in any of the physical 31 | conditions with which they are surrounded …” 32 | 33 | The only difference was in the water supply, “one group being supplied with 34 | water containing the sewage of London, and amongst it, whatever might have come 35 | from the cholera patients, the other group having water quite free from 36 | impurity.” 37 | 38 | Confident that he would be able to arrive at a clear conclusion, Snow summarized 39 | his data in the table below. 40 | 41 | | Supply Area | Number of houses | cholera deaths | deaths per 10,000 houses | 42 | |----------------|------------------|----------------|--------------------------| 43 | | S&V | 40,046 | 1,263 | 315 | 44 | | Lambeth | 26,107 | 98 | 37 | 45 | | Rest of London | 256,423 | 1,422 | 59 | 46 | 47 | 48 | The numbers pointed accusingly at S&V. The death rate from cholera in the S&V 49 | houses was almost ten times the rate in the houses supplied by Lambeth. 50 | -------------------------------------------------------------------------------- /_build/02/3/establishing-causality.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Establishing Causality' 3 | prev_page: 4 | url: /02/2/snow-s-grand-experiment 5 | title: 'Snow’s “Grand Experiment”' 6 | next_page: 7 | url: /02/4/randomization 8 | title: 'Randomization' 9 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 10 | --- 11 | Establishing Causality 12 | ---------------------- 13 | 14 | In the language developed earlier in the section, you can think of the people in 15 | the S&V houses as the treatment group, and those in the Lambeth houses at the 16 | control group. A crucial element in Snow’s analysis was that the people in the 17 | two groups were comparable to each other, apart from the treatment. 18 | 19 | In order to establish whether it was the water supply that was causing cholera, 20 | Snow had to compare two groups that were similar to each other in all but one 21 | aspect–their water supply. Only then would he be able to ascribe the differences 22 | in their outcomes to the water supply. If the two groups had been different in 23 | some other way as well, it would have been difficult to point the finger at the 24 | water supply as the source of the disease. For example, if the treatment group 25 | consisted of factory workers and the control group did not, then differences 26 | between the outcomes in the two groups could have been due to the water supply, 27 | or to factory work, or both, or to any other characteristic that made the groups 28 | different from each other. The final picture would have been much more fuzzy. 29 | 30 | Snow’s brilliance lay in identifying two groups that would make his comparison 31 | clear. He had set out to establish a causal relation between contaminated water 32 | and cholera infection, and to a great extent he succeeded, even though the 33 | miasmatists ignored and even ridiculed him. Of course, Snow did not understand 34 | the detailed mechanism by which humans contract cholera. That discovery was made 35 | in 1883, when the German scientist Robert Koch isolated the *Vibrio cholerae*, 36 | the bacterium that enters the human small intestine and causes cholera. 37 | 38 | In fact the *Vibrio cholerae* had been identified in 1854 by Filippo Pacini in 39 | Italy, just about when Snow was analyzing his data in London. Because of the 40 | dominance of the miasmatists in Italy, Pacini’s discovery languished unknown. 41 | But by the end of the 1800’s, the miasma brigade was in retreat. Subsequent 42 | history has vindicated Pacini and John Snow. Snow’s methods led to the 43 | development of the field of *epidemiology*, which is the study of the spread of 44 | diseases. 45 | 46 | **Confounding** 47 | 48 | Let us now return to more modern times, armed with an important lesson that we 49 | have learned along the way: 50 | 51 | In an observational study, if the treatment and control groups differ in ways 52 | other than the treatment, it is difficult to make conclusions about causality. 53 | 54 | An underlying difference between the two groups (other than the treatment) is 55 | called a *confounding factor*, because it might confound you (that is, mess you 56 | up) when you try to reach a conclusion. 57 | 58 | **Example: Coffee and lung cancer.** Studies in the 1960’s showed that coffee 59 | drinkers had higher rates of lung cancer than those who did not drink coffee. 60 | Because of this, some people identified coffee as a cause of lung cancer. But 61 | coffee does not cause lung cancer. The analysis contained a confounding factor – 62 | smoking. In those days, coffee drinkers were also likely to have been smokers, 63 | and smoking does cause lung cancer. Coffee drinking was associated with lung 64 | cancer, but it did not cause the disease. 65 | 66 | Confounding factors are common in observational studies. Good studies take great 67 | care to reduce confounding. 68 | -------------------------------------------------------------------------------- /_build/02/4/randomization.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Randomization' 3 | prev_page: 4 | url: /02/3/establishing-causality 5 | title: 'Establishing Causality' 6 | next_page: 7 | url: /02/5/endnote 8 | title: 'Endnote' 9 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 10 | --- 11 | Randomization 12 | -------------- 13 | 14 | An excellent way to avoid confounding is to assign individuals to the treatment 15 | and control groups *at random*, and then administer the treatment to those who 16 | were assigned to the treatment group. Randomization keeps the two groups similar 17 | apart from the treatment. 18 | 19 | If you are able to randomize individuals into the treatment and control groups, 20 | you are running a *randomized controlled experiment*, also known as a 21 | *randomized controlled trial* (RCT). Sometimes, people’s responses in an 22 | experiment are influenced by their knowing which group they are in. So you might 23 | want to run a *blind* experiment in which individuals do not know whether they 24 | are in the treatment group or the control group. To make this work, you will 25 | have to give the control group a *placebo*, which is something that looks 26 | exactly like the treatment but in fact has no effect. 27 | 28 | Randomized controlled experiments have long been a gold standard in the medical 29 | field, for example in establishing whether a new drug works. They are also 30 | becoming more commonly used in other fields such as economics. 31 | 32 | **Example: Welfare subsidies in Mexico.** In Mexican villages in the 1990’s, 33 | children in poor families were often not enrolled in school. One of the reasons 34 | was that the older children could go to work and thus help support the family. 35 | Santiago Levy , a minister in Mexican Ministry of Finance, set out to 36 | investigate whether welfare programs could be used to increase school enrollment 37 | and improve health conditions. He conducted an RCT on a set of villages, 38 | selecting some of them at random to receive a new welfare program called 39 | PROGRESA. The program gave money to poor families if their children went to 40 | school regularly and the family used preventive health care. More money was 41 | given if the children were in secondary school than in primary school, to 42 | compensate for the children’s lost wages, and more money was given for girls 43 | attending school than for boys. The remaining villages did not get this 44 | treatment, and formed the control group. Because of the randomization, there 45 | were no confounding factors and it was possible to establish that PROGRESA 46 | increased school enrollment. For boys, the enrollment increased from 73% in the 47 | control group to 77% in the PROGRESA group. For girls, the increase was even 48 | greater, from 67% in the control group to almost 75% in the PROGRESA group. Due 49 | to the success of this experiment, the Mexican government supported the program 50 | under the new name OPORTUNIDADES, as an investment in a healthy and well 51 | educated population. 52 | 53 | 54 | In some situations it might not be possible to carry out a randomized controlled 55 | experiment, even when the aim is to investigate causality. For example, suppose 56 | you want to study the effects of alcohol consumption during pregnancy, and you 57 | randomly assign some pregnant women to your “alcohol” group. You should not 58 | expect cooperation from them if you present them with a drink. In such 59 | situations you will almost invariably be conducting an observational study, not 60 | an experiment. Be alert for confounding factors. 61 | -------------------------------------------------------------------------------- /_build/02/5/endnote.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Endnote' 3 | prev_page: 4 | url: /02/4/randomization 5 | title: 'Randomization' 6 | next_page: 7 | url: /03/programming-in-python 8 | title: 'Programming in Python' 9 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 10 | --- 11 | Endnote 12 | ------- 13 | 14 | In the terminology of that we have developed, John Snow conducted an 15 | observational study, not a randomized experiment. But he called his study a 16 | “grand experiment” because, as he wrote, “No fewer than three hundred thousand 17 | people … were divided into two groups without their choice, and in most cases, 18 | without their knowledge …” 19 | 20 | Studies such as Snow’s are sometimes called “natural experiments.” However, true 21 | randomization does not simply mean that the treatment and control groups are 22 | selected “without their choice.” 23 | 24 | The method of randomization can be as simple as tossing a coin. It may also be 25 | quite a bit more complex. But every method of randomization consists of a 26 | sequence of carefully defined steps that allow chances to be specified 27 | mathematically. This has two important consequences. 28 | 29 | 1. It allows us to account–mathematically–for the possibility that randomization 30 | produces treatment and control groups that are quite different from each 31 | other. 32 | 33 | 2. It allows us to make precise mathematical statements about differences 34 | between the treatment and control groups. This in turn helps us make 35 | justifiable conclusions about whether the treatment has any effect. 36 | 37 | 38 | In this course, you will learn how to conduct and analyze your own randomized 39 | experiments. That will involve more detail than has been presented in this 40 | section. For now, just focus on the main idea: to try to establish causality, 41 | run a randomized controlled experiment if possible. If you are conducting an 42 | observational study, you might be able to establish association but not 43 | causation. Be extremely careful about confounding factors before making 44 | conclusions about causality based on an observational study. 45 | 46 | **Terminology** 47 | 48 | * observational study 49 | * treatment 50 | * outcome 51 | * association 52 | * causal association 53 | * causality 54 | * comparison 55 | * treatment group 56 | * control group 57 | * epidemiology 58 | * confounding 59 | * randomization 60 | * randomized controlled experiment 61 | * randomized controlled trial (RCT) 62 | * blind 63 | * placebo 64 | 65 | **Fun facts** 66 | 67 | 1. John Snow is sometimes called the father of epidemiology, but he was an 68 | anesthesiologist by profession. One of his patients was Queen Victoria, who 69 | was an early recipient of anesthetics during childbirth. 70 | 71 | 2. Florence Nightingale, the originator of modern nursing practices and famous 72 | for her work in the Crimean War, was a die-hard miasmatist. She had no time 73 | for theories about contagion and germs, and was not one for mincing her 74 | words. “There is no end to the absurdities connected with this doctrine,” she 75 | said. “Suffice it to say that in the ordinary sense of the word, there is no 76 | proof such as would be admitted in any scientific enquiry that there is any 77 | such thing as contagion.” 78 | 79 | 3. A later RCT established that the conditions on which PROGRESA insisted – 80 | children going to school, preventive health care – were not necessary to 81 | achieve increased enrollment. Just the financial boost of the welfare 82 | payments was sufficient. 83 | 84 | 85 | **Good reads** 86 | 87 | [*The Strange Case of the Broad Street Pump: John Snow and the Mystery of 88 | Cholera*](http://www.ucpress.edu/book.php?isbn=9780520250499) by Sandra Hempel, 89 | published by our own University of California Press, reads like a whodunit. It 90 | was one of the main sources for this section's account of John Snow and his 91 | work. A word of warning: some of the contents of the book are stomach-churning. 92 | 93 | [*Poor Economics*](http://www.pooreconomics.com), the best seller by Abhijit V. 94 | Banerjee and Esther Duflo of MIT, is an accessible and lively account of ways to 95 | fight global poverty. It includes numerous examples of RCTs, including the 96 | PROGRESA example in this section. 97 | -------------------------------------------------------------------------------- /_build/02/causality-and-experiments.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Causality and Experiments' 3 | prev_page: 4 | url: /01/3/subsection/subsectiontwo 5 | title: 'Subsection Demo 2' 6 | next_page: 7 | url: /02/1/observation-and-visualization-john-snow-and-the-broad-street-pump 8 | title: 'John Snow and the Broad Street Pump' 9 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 10 | --- 11 | Causality and Experiments 12 | ====================== 13 | 14 | *"These problems are, and will probably ever remain, among the inscrutable 15 | secrets of nature. They belong to a class of questions radically inaccessible to 16 | the human intelligence."* —The Times of London, September 1849, on how cholera 17 | is contracted and spread 18 | 19 | Does the death penalty have a deterrent effect? Is chocolate good for you? What 20 | causes breast cancer? 21 | 22 | All of these questions attempt to assign a cause to an effect. A careful 23 | examination of data can help shed light on questions like these. In this section 24 | you will learn some of the fundamental concepts involved in establishing 25 | causality. 26 | 27 | Observation is a key to good science. An *observational study* is one in which 28 | scientists make conclusions based on data that they have observed but had no 29 | hand in generating. In data science, many such studies involve observations on a 30 | group of individuals, a factor of interest called a *treatment*, and an 31 | *outcome* measured on each individual. 32 | 33 | It is easiest to think of the individuals as people. In a study of whether 34 | chocolate is good for the health, the individuals would indeed be people, the 35 | treatment would be eating chocolate, and the outcome might be a measure of blood 36 | pressure. But individuals in observational studies need not be people. In a 37 | study of whether the death penalty has a deterrent effect, the individuals could 38 | be the 50 states of the union. A state law allowing the death penalty would be 39 | the treatment, and an outcome could be the state’s murder rate. 40 | 41 | The fundamental question is whether the treatment has an effect on the outcome. 42 | Any relation between the treatment and the outcome is called an *association*. 43 | If the treatment causes the outcome to occur, then the association is *causal*. 44 | *Causality* is at the heart of all three questions posed at the start of this 45 | section. For example, one of the questions was whether chocolate directly causes 46 | improvements in health, not just whether there there is a relation between 47 | chocolate and health. 48 | 49 | The establishment of causality often takes place in two stages. First, an 50 | association is observed. Next, a more careful analysis leads to a decision about 51 | causality. 52 | -------------------------------------------------------------------------------- /_build/03/2/Names.md: -------------------------------------------------------------------------------- 1 | --- 2 | interact_link: mnt/c/Users/chold/github/forks/python/teaching/dsep/jupyter-book/content/03/2/Names.ipynb 3 | title: 'Names' 4 | prev_page: 5 | url: /03/1/Expressions 6 | title: 'Expressions' 7 | next_page: 8 | url: /03/3/Calls 9 | title: 'Call Expressions' 10 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 11 | --- 12 | 13 | ## 3.2 Names 14 | Names are given to values in Python using an *assignment* statement. In an assignment, a name is followed by `=`, which is followed by any expression. The value of the expression to the right of `=` is *assigned* to the name. Once a name has a value assigned to it, the value will be substituted for that name in future expressions. 15 | 16 | 17 | 18 | {:.input_area} 19 | ```python 20 | a = 10 21 | b = 20 22 | a + b 23 | ``` 24 | 25 | 26 | 27 | 28 | 29 | {:.output_data_text} 30 | ``` 31 | 30 32 | ``` 33 | 34 | 35 | 36 | A previously assigned name can be used in the expression to the right of `=`. 37 | 38 | 39 | 40 | {:.input_area} 41 | ```python 42 | quarter = 1/4 43 | half = 2 * quarter 44 | half 45 | ``` 46 | 47 | 48 | 49 | 50 | 51 | {:.output_data_text} 52 | ``` 53 | 0.5 54 | ``` 55 | 56 | 57 | 58 | However, only the current value of an expression is assigned to a name. If that value changes later, names that were defined in terms of that value will not change automatically. 59 | 60 | 61 | 62 | {:.input_area} 63 | ```python 64 | quarter = 4 65 | half 66 | ``` 67 | 68 | 69 | 70 | 71 | 72 | {:.output_data_text} 73 | ``` 74 | 0.5 75 | ``` 76 | 77 | 78 | 79 | Names must start with a letter, but can contain both letters and numbers. A name cannot contain a space; instead, it is common to use an underscore character `_` to replace each space. Names are only as useful as you make them; it's up to the programmer to choose names that are easy to interpret. Typically, more meaningful names can be invented than `a` and `b`. For example, to describe the sales tax on a $5 purchase in Berkeley, CA, the following names clarify the meaning of the various quantities involved. 80 | 81 | 82 | 83 | {:.input_area} 84 | ```python 85 | purchase_price = 5 86 | state_tax_rate = 0.075 87 | county_tax_rate = 0.02 88 | city_tax_rate = 0 89 | sales_tax_rate = state_tax_rate + county_tax_rate + city_tax_rate 90 | sales_tax = purchase_price * sales_tax_rate 91 | sales_tax 92 | ``` 93 | 94 | 95 | 96 | 97 | 98 | {:.output_data_text} 99 | ``` 100 | 0.475 101 | ``` 102 | 103 | 104 | -------------------------------------------------------------------------------- /_build/03/programming-in-python.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Programming in Python' 3 | prev_page: 4 | url: /02/5/endnote 5 | title: 'Endnote' 6 | next_page: 7 | url: /03/1/Expressions 8 | title: 'Expressions' 9 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 10 | --- 11 | Programming in Python 12 | ===================== 13 | 14 | Programming can dramatically improve our ability to collect and analyze information 15 | about the world, which in turn can lead to discoveries through the kind of careful 16 | reasoning demonstrated in the previous section. In data science, the purpose of 17 | writing a program is to instruct a computer to carry out the steps of an analysis. 18 | Computers cannot study the world on their own. People must describe precisely what 19 | steps the computer should take in order to collect and analyze data, and those steps 20 | are expressed through programs. 21 | 22 | 23 | -------------------------------------------------------------------------------- /_build/04/2/Strings.md: -------------------------------------------------------------------------------- 1 | --- 2 | interact_link: mnt/c/Users/chold/github/forks/python/teaching/dsep/jupyter-book/content/04/2/Strings.ipynb 3 | title: 'Strings' 4 | prev_page: 5 | url: /04/1/Numbers 6 | title: 'Numbers' 7 | next_page: 8 | url: /04/3/Comparison 9 | title: 'Comparisons' 10 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 11 | --- 12 | 13 | Much of the world's data is text, and a piece of text represented in a computer is called a *string*. A string can represent a word, a sentence, or even the contents of every book in a library. Since text can include numbers (like this: 5) or truth values (True), a string can also describe those things. 14 | 15 | The meaning of an expression depends both upon its structure and the types of values that are being combined. So, for instance, adding two strings together produces another string. This expression is still an addition expression, but it is combining a different type of value. 16 | 17 | 18 | 19 | {:.input_area} 20 | ```python 21 | "data" + "science" 22 | ``` 23 | 24 | 25 | 26 | 27 | 28 | {:.output_data_text} 29 | ``` 30 | 'datascience' 31 | ``` 32 | 33 | 34 | 35 | Addition is completely literal; it combines these two strings together without regard for their contents. It doesn't add a space because these are different words; that's up to the programmer (you) to specify. 36 | 37 | 38 | 39 | {:.input_area} 40 | ```python 41 | "data" + " " + "science" 42 | ``` 43 | 44 | 45 | 46 | 47 | 48 | {:.output_data_text} 49 | ``` 50 | 'data science' 51 | ``` 52 | 53 | 54 | 55 | Single and double quotes can both be used to create strings: `'hi'` and `"hi"` are identical expressions. Double quotes are often preferred because they allow you to include apostrophes inside of strings. 56 | 57 | 58 | 59 | {:.input_area} 60 | ```python 61 | "This won't work with a single-quoted string!" 62 | ``` 63 | 64 | 65 | 66 | 67 | 68 | {:.output_data_text} 69 | ``` 70 | "This won't work with a single-quoted string!" 71 | ``` 72 | 73 | 74 | 75 | Why not? Try it out. 76 | 77 | The `str` function returns a string representation of any value. Using this function, strings can be constructed that have embedded values. 78 | 79 | 80 | 81 | {:.input_area} 82 | ```python 83 | "That's " + str(1 + 1) + ' ' + str(True) 84 | ``` 85 | 86 | 87 | 88 | 89 | 90 | {:.output_data_text} 91 | ``` 92 | "That's 2 True" 93 | ``` 94 | 95 | 96 | -------------------------------------------------------------------------------- /_build/04/3/Comparison.md: -------------------------------------------------------------------------------- 1 | --- 2 | interact_link: mnt/c/Users/chold/github/forks/python/teaching/dsep/jupyter-book/content/04/3/Comparison.ipynb 3 | title: 'Comparisons' 4 | prev_page: 5 | url: /04/2/Strings 6 | title: 'Strings' 7 | next_page: 8 | url: / 9 | title: '' 10 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 11 | --- 12 | 13 | Boolean values most often arise from comparison operators. Python includes a variety of operators that compare values. For example, `3` is larger than `1 + 1`. 14 | 15 | 16 | 17 | {:.input_area} 18 | ```python 19 | 3 > 1 + 1 20 | ``` 21 | 22 | 23 | 24 | 25 | 26 | {:.output_data_text} 27 | ``` 28 | True 29 | ``` 30 | 31 | 32 | 33 | The value `True` indicates that the comparison is valid; Python has confirmed this simple fact about the relationship between `3` and `1+1`. The full set of common comparison operators are listed below. 34 | 35 | | Comparison | Operator | True example | False Example | 36 | |--------------------|----------|--------------|---------------| 37 | | Less than | < | 2 < 3 | 2 < 2 | 38 | | Greater than | > | 3>2 | 3>3 | 39 | | Less than or equal | <= | 2 <= 2 | 3 <= 2 | 40 | | Greater or equal | >= | 3 >= 3 | 2 >= 3 | 41 | | Equal | == | 3 == 3 | 3 == 2 | 42 | | Not equal | != | 3 != 2 | 2 != 2 | 43 | 44 | An expression can contain multiple comparisons, and they all must hold in order for the whole expression to be `True`. For example, we can express that `1+1` is between `1` and `3` using the following expression. 45 | 46 | 47 | 48 | {:.input_area} 49 | ```python 50 | 1 < 1 + 1 < 3 51 | ``` 52 | 53 | 54 | 55 | 56 | 57 | {:.output_data_text} 58 | ``` 59 | True 60 | ``` 61 | 62 | 63 | 64 | The average of two numbers is always between the smaller number and the larger number. We express this relationship for the numbers `x` and `y` below. You can try different values of `x` and `y` to confirm this relationship. 65 | 66 | 67 | 68 | {:.input_area} 69 | ```python 70 | x = 12 71 | y = 5 72 | min(x, y) <= (x+y)/2 <= max(x, y) 73 | ``` 74 | 75 | 76 | 77 | 78 | 79 | {:.output_data_text} 80 | ``` 81 | True 82 | ``` 83 | 84 | 85 | 86 | Strings can also be compared, and their order is alphabetical. A shorter string is less than a longer string that begins with the shorter string. 87 | 88 | 89 | 90 | {:.input_area} 91 | ```python 92 | "Dog" > "Catastrophe" > "Cat" 93 | ``` 94 | 95 | 96 | 97 | 98 | 99 | {:.output_data_text} 100 | ``` 101 | True 102 | ``` 103 | 104 | 105 | -------------------------------------------------------------------------------- /_build/04/Types.md: -------------------------------------------------------------------------------- 1 | --- 2 | interact_link: mnt/c/Users/chold/github/forks/python/teaching/dsep/jupyter-book/content/04/Types.ipynb 3 | title: 'Data Types' 4 | prev_page: 5 | url: /03/4/Introduction_to_Tables 6 | title: 'Introduction to Tables' 7 | next_page: 8 | url: /04/1/Numbers 9 | title: 'Numbers' 10 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 11 | --- 12 | 13 | Every value has a type, and the built-in `type` function returns the type of the result of any expression. 14 | 15 | One type we have encountered already is a built-in function. Python indicates that the type is a `builtin_function_or_method`; the distinction between a *function* and a *method* is not important at this stage. 16 | 17 | 18 | 19 | {:.input_area} 20 | ```python 21 | type(abs) 22 | ``` 23 | 24 | 25 | 26 | 27 | 28 | {:.output_data_text} 29 | ``` 30 | builtin_function_or_method 31 | ``` 32 | 33 | 34 | 35 | This chapter will explore many useful types of data. 36 | -------------------------------------------------------------------------------- /_build/features/cool.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/choldgraf/jupyter-book-DEPRECATED/7d6ab22e279a6c8d2ad1948fb574f87a50efb99f/_build/features/cool.jpg -------------------------------------------------------------------------------- /_build/features/features.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Features' 3 | prev_page: 4 | url: /intro 5 | title: 'Home' 6 | next_page: 7 | url: /features/markdown 8 | title: 'Markdown files' 9 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 10 | --- 11 | # Features 12 | 13 | This is a short demonstration textbook to show the general layout / style of textbooks built 14 | with Jupyter and Jekyll. The markdown files for *this* page (and others in the textbook) is generated from the notebooks 15 | with the `scripts/generate_textbook.py` script, which is called when you run `make textbook`. 16 | 17 | The content for the book is contained in a folder in the site's repository called `notebooks/`. It has a 18 | combination of markdown and Jupyter notebooks. This content is rendered into the textbook that you see here! 19 | 20 | To begin, click on one of the chapter sections in the sidebar to the left. The first section demonstrates some 21 | simple functionality of this repository, while the following chapters contain a subset of content from the 22 | [Foundations in Data Science](https://inferentialthinking.com). 23 | 24 | ## Quickstart 25 | 26 | This chapter shows a couple ways to add content to your course textbook. Click on the section headers 27 | to the left, or on the "next" button below in order to read further. 28 | -------------------------------------------------------------------------------- /_build/features/markdown.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Markdown files' 3 | prev_page: 4 | url: /features/features 5 | title: 'Features' 6 | next_page: 7 | url: /features/notebooks 8 | title: 'Jupyter notebooks' 9 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 10 | --- 11 | # Creating course content 12 | 13 | The two kinds of files that contain course content are: 14 | 15 | * Jupyter Notebooks 16 | * Markdown files 17 | 18 | Each are contained in the `notebooks/` folder and referenced from `SUMMARY.md`. 19 | 20 | If the file is markdown, it will be copied over with front-matter YAML added so 21 | that Jekyll can parse it 22 | 23 | ## Sidebars with Jekyll 24 | 25 | You may notice that there's a sidebar to the right (if your screen is wide enough). 26 | These are automatically generated from the headers that are present in your page. 27 | The sidebar will automatically capture all 2nd and 3rd level section headers. 28 | The best way to designate these headers is with `#` characters at the beginning 29 | of a line. 30 | 31 | ### Here's a third-level header 32 | 33 | This section is here purely to demonstrate the third-level header of the 34 | rendered page! 35 | 36 | ## Embedding media 37 | 38 | ### Adding images 39 | 40 | You can reference external media like images from your markdown file. If you use 41 | relative paths, then they will continue to work when the markdown files are copied over, 42 | so long as they point to a file that's inside of the repository. 43 | 44 | Here's an image relative to the site root 45 | 46 | ![](../images/C-3PO_droid.png) 47 | 48 | ### Adding movies 49 | 50 | You can even embed references to movies on the web! For example, here's a little gif for you! 51 | 52 | ![](https://media.giphy.com/media/yoJC2A59OCZHs1LXvW/giphy.gif) 53 | 54 | This will be included in your website when it is built. -------------------------------------------------------------------------------- /_build/guide/00_intro.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Guide' 3 | prev_page: 4 | url: /features/notebooks 5 | title: 'Jupyter notebooks' 6 | next_page: 7 | url: /guide/01_overview 8 | title: 'Overview' 9 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 10 | --- 11 | # Books with Jupyter and Jekyll 12 | 13 | Jupyter Books lets you build an online book using a collection of Jupyter Notebooks 14 | and Markdown files. 15 | 16 | For an example of a book built with Jupyter Books, see the [textbook for Data 100](https://www.textbook.ds100.org/) at UC Berkeley. 17 | 18 | Here are a few features of Jupyter Books 19 | 20 | * All course content is written in markdown and Jupyter Notebooks, stored in `notebooks/` 21 | * The Jupyter Book repo comes packaged with helper scripts to convert these into Jekyll pages (in `scripts/`) that can be hosted for free on GitHub 22 | * Pages can have [Binder](https://mybinder.org) or JupyterHub links automatically added for interactivity. 23 | * The website itself is based on Jekyll, and is highly extensible and can be freely-hosted on GitHub. 24 | * There are lots of nifty HTML features under-the-hood, such as Turbolinks fast-navigation and 25 | click-to-copy in code cells. 26 | 27 | ## Installation 28 | 29 | Here's a brief rundown of how to create your own Jupyter Book using this site. For a more 30 | complete guide, see [the Jupyter Book guide](guide). 31 | 32 | * Fork the Jupyter Book template repo 33 | * Replace the demo notebooks in `notebooks/` with your own notebooks and markdown files. 34 | * Create a Table of Contents yaml file by editing `_data/toc.yaml`. 35 | * Generate the Jekyll markdown for your notebooks by running `scripts/generate_book.py` 36 | * Push your changes to GitHub (or wherever you host your site)! 37 | 38 | ## Getting started 39 | 40 | To get started, you may be interested in the following links. 41 | Here are a few links of interest: 42 | 43 | * **[The Jupyter Book Guide](https://predictablynoisy.com/jupyter-book-guide/guide/01_overview/)** 44 | will step you through the process of configuring and building your own Jupyter Book. 45 | 46 | * **[The Jupyter Book template](https://github.com/choldgraf/jupyter-book)** is the template 47 | repository you'll use as a start for your Jupyter Book. 48 | 49 | * **[A live demo of a Jupyter Book](textbook)** is also available for you to browse. 50 | 51 | 52 | ## Acknowledgements 53 | 54 | Jupyter Books was originally created by [Sam Lau][sam] and [Chris Holdgraf][chris] 55 | with support of the **UC Berkeley Data Science Education Program and the Berkeley 56 | Institute for Data Science**. 57 | 58 | [sam]: http://www.samlau.me/ 59 | [chris]: https://predictablynoisy.com 60 | -------------------------------------------------------------------------------- /_build/guide/01_overview.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Overview' 3 | prev_page: 4 | url: /guide/00_intro 5 | title: 'Guide' 6 | next_page: 7 | url: /guide/02_setup 8 | title: 'Setup and Install' 9 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 10 | --- 11 | # The Jupyter Books Guide 12 | 13 | This repository / website is a guide for hosting your own book using 14 | Jupyter Notebooks and Jekyll. All course content is written in markdown and 15 | Jupyter Notebooks, and a set of helper scripts converts these notebooks into 16 | Jekyll-based markdown fit for hosting on the web. This short guide will 17 | help you through the process should you want to do this for your own book. 18 | 19 | ## The structure underneath Jupyter Books 20 | 21 | This page gives a general idea for what we mean by a "Jupyter Book". Jupyter Books 22 | are essentially these two things: 23 | 24 | 1. [**A collection of notebooks and markdown files**](https://github.com/choldgraf/jupyter-book/tree/master/content). These are in `content/`. When you run `scripts/generate_book.py`, 25 | they'll be converted to `.md` files (or just copied if they're already `.md` files) and placed in `/_build`. 26 | 2. [**A Table of Contents file**](https://github.com/choldgraf/jupyter-book/tree/master/_data/toc.yml) (`_data/toc.yml`). This is 27 | the Table of Contents, which will be used to create the sidebar for your site. Links in this file are **relative to the `/_contents/` folder.** 28 | See [the TOC for this book](https://github.com/choldgraf/jupyter-book/tree/master/_data/toc.yml) for a couple of examples. 29 | 3. [**A Jekyll configuration file**](https://github.com/choldgraf/jupyter-book/tree/master/config.yml) that defines information about your book, 30 | such as its title or the URL of a JupyterHub you want interact links to point to. This is also how you turn on / off many features 31 | of your Jupyter Book. 32 | 33 | ## To build your own Jupyter Book 34 | 35 | To build your own Jupyter Book, you'll follow a process similar to this (we'll go into each 36 | step in more detail in this guide): 37 | 38 | * Get yourself a copy of the jupyter-book repository. [Here's the repo URL on GitHub](https://github.com/choldgraf/jupyter-book). 39 | * Put your Jupyter Notebooks / markdown files in `/content/` 40 | * Edit the `_data/toc.yml` file for your Table of Contents. This defines the structure 41 | of your book. The location of URLs should be **relative to the `/_contents/` folder.** 42 | * Navigate to the repo root, then run `make book` to convert your Jupyter Notebooks into Jekyll-ready markdown. It will be placed in `/_build`. 43 | * Push these changes to a GitHub repo you control and tell GitHub you want to build a website from your repository. 44 | * That's it! 45 | 46 | See the rest of this guide in the links to the left for detailed 47 | instructions on this process. The next section covers [Setting up your environment](02_setup.html). 48 | 49 | For a more complete description of the relevant files for the template repository, 50 | see the [Advanced topics section](../07_advanced). 51 | 52 | -------------------------------------------------------------------------------- /_build/guide/02_setup.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Setup and Install' 3 | prev_page: 4 | url: /guide/01_overview 5 | title: 'Overview' 6 | next_page: 7 | url: /guide/03_configure 8 | title: 'Configuration' 9 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 10 | --- 11 | This page should get you set up with the software and code needed to build 12 | your textbook! Follow the steps below... 13 | 14 | ## Get your own copy of this repository 15 | 16 | The easiest way to get a copy of the template repository is to use **GitHub's Import Feature**. 17 | This gives you a new copy of the contents of the template, without creating 18 | a "fork". This should make it easier for you to re-use the repository multiple 19 | times. **If you'd like to contribute improvements to the template itself, then please do fork it!** 20 | 21 | To import the template repository to your GitHub account, take the following steps: 22 | 23 | * Go to https://github.com/new/import 24 | * Enter the URL of the `jupyter-book` template repository in the 25 | "old repository's clone URL" field: 26 | 27 | ``` 28 | https://github.com/choldgraf/jupyter-book` 29 | ``` 30 | 31 | * Choose a new name for your repository, and whether you want it to be public. 32 | 33 | For example: 34 | 35 | ``` 36 | my-course-spring-2018 37 | ``` 38 | 39 | * Wait while GitHub creates a version of this repository for your account. You 40 | can watch the progress of this process by looking at this URL: 41 | 42 | ``` 43 | https://github.com///import 44 | ``` 45 | * Clone your repository to your computer and make edits as you wish. You may 46 | want to still add the URL of the original repository as a "remote" in case 47 | you want to pull in new changes to the template / build system. 48 | 49 | That's it! 50 | 51 | ## Set up your repository and dependencies 52 | 53 | The Jupyter Book repository primarily depends on three sets of tools: 54 | 55 | * Python and Jupyter for converting Jupyter Notebooks into Jekyll-ready markdown 56 | * GitHub (specifically, GitHub-pages) for hosting your textbook online with Jekyll 57 | * (optionally) Ruby and Jekyll for building or previewing your site locally before pushing to GitHub 58 | 59 | This section helps you set each of these up 60 | 61 | 62 | 0. **Install the Anaconda distribution of Python**. This is needed to install 63 | the dependencies in `environment.yml`. It's not *strictly* necessary, so 64 | if you know what you're doing feel free to skip this step. 65 | 1. **Install the proper dependencies**. You can do this by installing the 66 | Anaconda environment specified in `environment.yml`: 67 | 68 | conda env create -f environment.yml 69 | 70 | 2. **Activate the environment** before building your site. 71 | 72 | conda activate textbook 73 | 74 | 3. (optionally) **Install Ruby and the Jekyll plugin.** 75 | 76 | If you want to build and preview the site locally, you'll need Ruby and Jekyll. 77 | [See the Jekyll docs](https://jekyllrb.com/docs/installation/) for information on this. 78 | As well as the [GitHub gh-pages documentation](https://help.github.com/articles/using-jekyll-as-a-static-site-generator-with-github-pages/) 79 | for more information on how Jekyll and GitHub interact. 80 | 81 | Make sure you run `bundle install` from the jupyter-book root so that you install its required dependencies! 82 | 83 | ## Deploying a JupyterHub 84 | 85 | If you wish, you may deploy a JupyterHub alongside your textbook. This way, for pages that are built from 86 | Jupyter Notebooks, students can click the "interact" links 87 | at the top of each page and be taken to a live Jupyter Notebook running on your JupyterHub. 88 | 89 | The easiest way to set up a JupyterHub is to follow [The Littlest JupyterHub guide](https://the-littlest-jupyterhub.readthedocs.io/en/latest/index.html). 90 | This is a straightforward deployment of JupyterHub on a single VM, and is suitable for 91 | courses / workshops of less than 50-60 students. 92 | 93 | Once you have your JupyterHub set up, you can use the [nbgitpuller](https://github.com/data-8/nbgitpuller) 94 | package to send links to course material to your students, or use the interact links that Textbooks for Jupyter 95 | automatically inserts into your course material. 96 | -------------------------------------------------------------------------------- /_build/guide/03_configure.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Configuration' 3 | prev_page: 4 | url: /guide/02_setup 5 | title: 'Setup and Install' 6 | next_page: 7 | url: /guide/04_build 8 | title: 'Build your book' 9 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 10 | --- 11 | ## Site configuration 12 | 13 | You can configure several aspects of your site. This is primarily done 14 | by changing [the values in `_config.yml`](https://github.com/choldgraf/jupyter-book/blob/master/_config.yml). Values that are unique to the 15 | textbook can be found under the `# Jupyter Books settings` section. See the 16 | [comments in that file](https://github.com/choldgraf/jupyter-book/blob/master/_config.yml) for information about what each field does. 17 | 18 | You can modify things like where your interact links point (if you've set up your 19 | own JupyterHub or BinderHub) or whether these links should use JupyterLab by default. 20 | 21 | ## Site CSS and Javascript 22 | 23 | You can change the site's CSS rules to get the look and feel you desire, as well as add 24 | any javascript that you wish. To do so, find the relevant folders in the `assets/` folder. 25 | 26 | This site uses SCSS to make it easier to create modular and beautiful CSS rules. If you create 27 | a new CSS file, make sure that you include it in `_sass/main.scss`. 28 | -------------------------------------------------------------------------------- /_build/guide/04_build.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Build your book' 3 | prev_page: 4 | url: /guide/03_configure 5 | title: 'Configuration' 6 | next_page: 7 | url: /guide/05_publish 8 | title: 'Publish your book' 9 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 10 | --- 11 | To build your site, take the following steps.: 12 | 13 | 0. (optionally) clean out the auto-generated folders by running 14 | 15 | make clean 16 | 17 | 1. Ensure that your Table of Contents file (`_data/toc.yml`) is up to date. The links in 18 | that file should be **relative to the `/_contents/` folder and with no extension.** For example, 19 | the file that's located in `mysite/contents/mychapter/mypage.ipynb` should have an entry like this: 20 | 21 | - title: My page title 22 | url: /mychapter/mypage 23 | 24 | See [the template `toc.yml`](https://github.com/choldgraf/jupyter-book/tree/master/_data/toc.yml) for examples. 25 | 26 | 2. Build the textbook by navigating to the site root, and running the following command: 27 | 28 | make book 29 | 30 | This will: 31 | 32 | * Run `nbconvert` to turn the `.ipynb` files into markdown 33 | * Replace relative image file paths so that they work on your new built site 34 | * Clean up formatting issues for things like MathJax to display properly 35 | * Place all these generated files in the `/_build/` directory. 36 | 37 | You can the push the changes to GitHub, which will automatically build a Jekyll site with 38 | your newly-created Markdown files. We'll cover this next. 39 | -------------------------------------------------------------------------------- /_build/guide/05_publish.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Publish your book' 3 | prev_page: 4 | url: /guide/04_build 5 | title: 'Build your book' 6 | next_page: 7 | url: /guide/06_faq 8 | title: 'FAQ' 9 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 10 | --- 11 | Once you've generated the markdown for your notebooks, your site is ready to be 12 | pushed and served by GitHub. To do this, take the following steps: 13 | 14 | 0. Confirm that your site files are built. You should see a 15 | collection of markdown files/folders in the `_build` folder. 16 | 1. Commit and push your changes to your fork of the repository. 17 | 2. Confirm that `gh-pages` site-building is enabled for your repository. 18 | 19 | From your GitHub repository, click `Settings` then scroll down to the 20 | `GitHub Pages` section. You should see the message `Your site is published at `. 21 | 3. Go to the URL listed at `` and you should see your live site. 22 | 23 | ## To preview your built site locally 24 | 25 | You can also preview your built site using Jekyll on your computer. 26 | To do this, take the following steps: 27 | 28 | 1. Ensure that Jekyll and Ruby are installed. 29 | 2. Ensure that your notebooks have been converted to markdown, there should be a 30 | collection of them in `_build/` 31 | 3. Run the Jekyll site preview command: 32 | 33 | make serve 34 | 35 | This should open up a port on your computer with a live version of the textbook. -------------------------------------------------------------------------------- /_build/guide/06_faq.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'FAQ' 3 | prev_page: 4 | url: /guide/05_publish 5 | title: 'Publish your book' 6 | next_page: 7 | url: /guide/07_advanced 8 | title: 'Advanced' 9 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 10 | --- 11 | The following are some common issues and questions that have arisen when 12 | building your textbook with Jekyll. 13 | 14 | ## How can I update my fork of the repository? 15 | 16 | Sometimes this repository will get updates that you want to incorporate into 17 | a pre-existing course. If you want to pull in new changes, take the following 18 | steps: 19 | 20 | 1. Add this repository as a "remote" on your local git repo: 21 | 22 | git remote add upstream https://github.com/choldgraf/jupyter-book 23 | 24 | 2. Pull in the latest changes from the remote repository into your local `gh-pages` branch: 25 | 26 | git pull upstream master 27 | 28 | 3. Resolve any merge conflicts that may arise. Make sure that you don't over-write 29 | any important files (e.g. anything in your `content/` directory or in `_config.yml`) 30 | 4. **If there are lots of merge conflicts** you can try to "cherry pick" only the commit 31 | that you want to deploy to your textbook. `git` has a special command for this. 32 | First, go to the base repository for the textbook template and look up the "commits" 33 | page at the following URL: 34 | 35 | https://github.com/choldgraf/jupyter-book/commits/master 36 | 37 | Find the commit that you want to implement on *your* copy of the repository. Click the button with 38 | its hash (there's one on the right of each row). Finally, copy the long commit hash that's listed 39 | on the resulting page. This is a unique hash for this commit. 40 | 41 | Now, use `git cherry-pick` to make these changes to your repo: 42 | 43 | git cherry-pick 44 | 45 | 5. Push changes to your github repository once you're happy with the content: 46 | 47 | git push 48 | 49 | ## Why isn't my math showing up properly? 50 | 51 | This site uses MathJax to render all math, with `$` denoting inline math, 52 | and `$$` denoting multi-line math blocks. Make sure that all of your math 53 | is wrapped in these characters. 54 | 55 | Another tip is to make sure that your math isn't being escaped improperly. 56 | Jekyll strips escape characters, so you should make sure to add **two** 57 | escape characters when needed. This is done automatically for many escape 58 | characters in `generate_book.py`, and if you notice something that should 59 | be included in this script, please open an issue 60 | [at the textbook template issues page](https://github.com/choldgraf/jupyter-book/issues) 61 | 62 | ## What if I have an issue or question? 63 | 64 | If you've got questions, concerns, or suggestions, please open an issue at 65 | [at the jupyter book issues page](https://github.com/choldgraf/jupyter-book/issues) 66 | -------------------------------------------------------------------------------- /_build/guide/07_advanced.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Advanced' 3 | prev_page: 4 | url: /guide/06_faq 5 | title: 'FAQ' 6 | next_page: 7 | url: /01/what-is-data-science 8 | title: 'Data Science' 9 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 10 | --- 11 | This page contains more advanced and complete information about the 12 | [`jupyter-book` repository](https://github.com/choldgraf/jupyter-book). See the sections below. 13 | 14 | ## Relevant files 15 | 16 | There are a few moving parts associated with Jupyter Books, and this 17 | section tries to cover most of the relevant pieces. The following list contains some 18 | of the more important files/folders worth knowing about. 19 | 20 | ### Course materials 21 | 22 | * `contents/` contains all course content in Jupyter notebook or markdown form 23 | * `images/` contains images referenced in the book 24 | 25 | ### Auto-generated folders and files 26 | * `images/build` contains images *generated* during the notebook conversion 27 | * `_build/` contain notebooks automatically converted to markdown in the build process 28 | * `_site/` contains the HTML for the built site. It is created by Jekyll, and should only exist if you build the site locally 29 | 30 | ### Repository configuration and build files 31 | * `_config.yml` contains all site configuration. 32 | * `_data/toc.yml` contains the table of contents for the book (AKA, the sidebar) 33 | * `assets/` contains CSS and Javascript for the book and website 34 | * `environment.yml` contains the environment needed to build the jupyter book 35 | 36 | ### Helper scripts 37 | 38 | * `scripts/` contains scripts to generate the textbook from the Jupyter notebooks. These helper scripts are 39 | all run with the `Makefile` included with this repository. 40 | * `scripts/generate_book.py` will generate the markdown for your book. 41 | After you make any changes in `contents/`, you should run this script via 42 | `make book` so your site stays up-to-date. 43 | * `scripts/clean.py` is used to clean out any auto-generated files 44 | * `scripts/execute_all_notebooks.py` will use nbconvert to execute all notebooks in `contents/` in-place. 45 | -------------------------------------------------------------------------------- /_build/intro.md: -------------------------------------------------------------------------------- 1 | --- 2 | redirect_from: 3 | - "/" 4 | title: 'Home' 5 | prev_page: 6 | url: / 7 | title: '' 8 | next_page: 9 | url: /features/features 10 | title: 'Features' 11 | comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" 12 | --- 13 | # Books with Jupyter and Jekyll 14 | 15 | Jupyter Books lets you build an online book using a collection of Jupyter Notebooks 16 | and Markdown files. 17 | 18 | For an example of a book built with Jupyter Books, see the [textbook for Data 100](https://www.textbook.ds100.org/) at UC Berkeley. 19 | 20 | Here are a few features of Jupyter Books 21 | 22 | * All course content is written in markdown and Jupyter Notebooks, stored in `notebooks/` 23 | * The Jupyter Book repo comes packaged with helper scripts to convert these into Jekyll pages (in `scripts/`) that can be hosted for free on GitHub 24 | * Pages can have [Binder](https://mybinder.org) or JupyterHub links automatically added for interactivity. 25 | * The website itself is based on Jekyll, and is highly extensible and can be freely-hosted on GitHub. 26 | * There are lots of nifty HTML features under-the-hood, such as Turbolinks fast-navigation and 27 | click-to-copy in code cells. 28 | 29 | ## Getting started 30 | 31 | To get started, you may be interested in the following links. 32 | Here are a few links of interest: 33 | 34 | * **[Quickstart](ch/introduction/intro)** is a quick demo and overview of Jupyter Books. 35 | 36 | * **[The Jupyter Book Guide](ch/guide/00_intro)** 37 | will step you through the process of configuring and building your own Jupyter Book. 38 | 39 | * **[The Jupyter Book template repo](https://github.com/choldgraf/jupyter-book)** is the template 40 | repository you'll use as a start for your Jupyter Book. 41 | 42 | * **A demo of the Jupyter Book** can be browsed via the sidebar to the left. 43 | 44 | ## Installation 45 | 46 | Here's a brief rundown of how to create your own Jupyter Book using this site. For a more 47 | complete guide, see [the Jupyter Book guide](ch/guide/00_intro). 48 | 49 | * Fork the Jupyter Book template repo 50 | * Replace the demo notebooks in `notebooks/` with your own notebooks and markdown files. 51 | * Create a Table of Contents yaml file by editing `_data/toc.yaml`. 52 | * Generate the Jekyll markdown for your notebooks by running `scripts/generate_book.py` 53 | * Push your changes to GitHub (or wherever you host your site)! 54 | 55 | ## Acknowledgements 56 | 57 | Jupyter Books was originally created by [Sam Lau][sam] and [Chris Holdgraf][chris] 58 | with support of the **UC Berkeley Data Science Education Program and the Berkeley 59 | Institute for Data Science**. 60 | 61 | [sam]: http://www.samlau.me/ 62 | [chris]: https://predictablynoisy.com 63 | -------------------------------------------------------------------------------- /_data/toc.yml: -------------------------------------------------------------------------------- 1 | # This file contains the order and numbering for all sections in the book. 2 | # _includes/sidebar.html renders this as a sidebar. 3 | # 4 | # Each entry has the following schema: 5 | # 6 | # title: Title of chapter or section 7 | # url: URL of section. Use absolute URLs to link between pages 8 | # class: (optional) a CSS class to add to this link 9 | # sections: Contains chapter's sections 10 | # not_numbered: true if the section shouldn't have a number in the sidebar 11 | # (e.g. Introduction or appendices) 12 | # divider: true if this entry should just be rendered as a horizontal divider 13 | # in the sidebar. All other values are ignored. 14 | 15 | - title: Home 16 | url: /intro 17 | not_numbered: true 18 | 19 | - title: Features 20 | url: /features/features 21 | not_numbered: true 22 | sections: 23 | - title: Markdown files 24 | url: /features/markdown 25 | not_numbered: true 26 | - title: Jupyter notebooks 27 | url: /features/notebooks 28 | not_numbered: true 29 | 30 | - title: Guide 31 | url: /guide/00_intro 32 | not_numbered: true 33 | sections: 34 | - title: Overview 35 | url: /guide/01_overview 36 | not_numbered: true 37 | - title: Setup and Install 38 | url: /guide/02_setup 39 | not_numbered: true 40 | - title: Configuration 41 | url: /guide/03_configure 42 | not_numbered: true 43 | - title: Build your book 44 | url: /guide/04_build 45 | not_numbered: true 46 | - title: Publish your book 47 | url: /guide/05_publish 48 | not_numbered: true 49 | - title: FAQ 50 | url: /guide/06_faq 51 | not_numbered: true 52 | - title: Advanced 53 | url: /guide/07_advanced 54 | 55 | - divider: true 56 | - header: Demo textbook 57 | 58 | - title: Data Science 59 | url: /01/what-is-data-science 60 | sections: 61 | - title: Introduction 62 | url: /01/1/intro 63 | - title: Why Data Science? 64 | url: /01/2/why-data-science 65 | - title: Plotting the Classics 66 | url: /01/3/Plotting_the_Classics 67 | subsections: 68 | - title: Subsection Demo 1 69 | url: /01/3/subsection/subsections 70 | - title: Subsection Demo 2 71 | url: /01/3/subsection/subsectiontwo 72 | 73 | - title: Causality and Experiments 74 | url: /02/causality-and-experiments 75 | sections: 76 | - title: John Snow and the Broad Street Pump 77 | url: /02/1/observation-and-visualization-john-snow-and-the-broad-street-pump 78 | - title: "Snow\u2019s \u201CGrand Experiment\u201D" 79 | url: /02/2/snow-s-grand-experiment 80 | - title: Establishing Causality 81 | url: /02/3/establishing-causality 82 | - title: Randomization 83 | url: /02/4/randomization 84 | - title: Endnote 85 | url: /02/5/endnote 86 | 87 | - title: Programming in Python 88 | url: /03/programming-in-python 89 | sections: 90 | - title: Expressions 91 | url: /03/1/Expressions 92 | - title: Names 93 | url: /03/2/Names 94 | - title: Call Expressions 95 | url: /03/3/Calls 96 | - title: Introduction to Tables 97 | url: /03/4/Introduction_to_Tables 98 | 99 | - title: Data Types 100 | url: /04/Types 101 | sections: 102 | - title: Numbers 103 | url: /04/1/Numbers 104 | - title: Strings 105 | url: /04/2/Strings 106 | - title: Comparisons 107 | url: /04/3/Comparison 108 | -------------------------------------------------------------------------------- /_includes/css_entry.scss: -------------------------------------------------------------------------------- 1 | @import 'inuitcss/settings/settings.core'; 2 | @import 'settings/settings.global.scss'; 3 | 4 | @import 'inuitcss/tools/tools.font-size'; 5 | @import 'inuitcss/tools/tools.clearfix'; 6 | @import 'inuitcss/tools/tools.hidden'; 7 | @import 'inuitcss/tools/tools.mq'; 8 | 9 | @import 'inuitcss/elements/elements.page'; 10 | @import 'inuitcss/elements/elements.headings'; 11 | @import 'inuitcss/elements/elements.images'; 12 | @import 'inuitcss/elements/elements.tables'; 13 | @import 'elements/elements.typography'; 14 | @import 'elements/elements.syntax-highlighting'; 15 | @import 'elements/elements.tables'; 16 | @import 'elements/elements.links'; 17 | 18 | @import 'components/components.textbook__page'; 19 | -------------------------------------------------------------------------------- /_includes/dom-update.html: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /_includes/fb_tags.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | -------------------------------------------------------------------------------- /_includes/head.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | {% if page.title %}{{ page.title | escape }}{% else %}{{ site.title | escape }}{% endif %} 7 | 8 | 9 | 10 | 11 | 12 | {% include fb_tags.html %} 13 | 14 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | {% include mathjax.html %} 40 | 41 | {% include dom-update.html %} 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | {% include interact-update.html %} 62 | 63 | -------------------------------------------------------------------------------- /_includes/interact.html: -------------------------------------------------------------------------------- 1 | 2 | {% if page.interact_link %} 3 | {% if site.use_jupyterlab %} 4 | {% assign binder_interact_prefix="urlpath=lab/tree/" %} 5 | {% assign hub_app="lab" %} 6 | {% else %} 7 | {% assign binder_interact_prefix="filepath=" %} 8 | {% assign hub_app="notebook" %} 9 | {% endif %} 10 | {% if site.hub_type == "binder" %} 11 | {% capture interact_url %}v2/gh/{{ site.textbook_repo_org }}/{{ site.textbook_repo_name }}/{{ site.textbook_repo_branch }}?{{ binder_interact_prefix }}{{ page.interact_link | url_encode }}{% endcapture %} 12 | {% elsif site.hub_type == "jupyterhub" %} 13 | {% capture interact_url %}hub/user-redirect/git-pull?repo={{ site.textbook_repo_base }}/{{ site.textbook_repo_org }}/{{ site.textbook_repo_name }}&branch={{ site.textbook_repo_branch }}&subPath={{ page.interact_link | url_encode }}&app={{ hub_app }}{% endcapture %} 14 | {% endif %} 15 |
16 | {{ site.interact_text }} 17 |
18 | {% endif %} 19 | -------------------------------------------------------------------------------- /_includes/mathjax.html: -------------------------------------------------------------------------------- 1 | 2 | 17 | 18 | -------------------------------------------------------------------------------- /_includes/metadata.json: -------------------------------------------------------------------------------- 1 | { 2 | "@context": "http://schema.org", 3 | "@type": "NewsArticle", 4 | "mainEntityOfPage": 5 | "{{ page.url | replace:'index.html','' | prepend: site.baseurl | prepend: site.url }}", 6 | "headline": 7 | "{% if page.title %}{{ page.title | escape }}{% else %}{{ site.title | escape }}{% endif %}", 8 | "datePublished": 9 | "{% if page.date %}{{ page.date | date_to_xmlschema }}{% else %}{{ site.time | date_to_xmlschema }}{% endif %}", 10 | "dateModified": 11 | "{% if page.date %}{{ page.date | date_to_xmlschema }}{% else %}{{ site.time | date_to_xmlschema }}{% endif %}", 12 | "description": 13 | "{% if page.excerpt %}{{ page.excerpt | strip_html | strip_newlines | truncate: 160 }}{% else %}{{ site.description }}{% endif %}", 14 | "author": { 15 | "@type": "Person", 16 | "name": "{{ site.author }}" 17 | }, 18 | "publisher": { 19 | "@type": "Organization", 20 | "name": "Data 100 at UC Berkeley", 21 | "logo": { 22 | "@type": "ImageObject", 23 | "url": "{{ site.logo | prepend: site.baseurl | prepend: site.url }}", 24 | "width": 60, 25 | "height": 60 26 | } 27 | }, 28 | "image": { 29 | "@type": "ImageObject", 30 | "url": "{{ site.logo | prepend: site.baseurl | prepend: site.url }}", 31 | "height": 60, 32 | "width": 60 33 | } 34 | } 35 | -------------------------------------------------------------------------------- /_includes/onthispage.html: -------------------------------------------------------------------------------- 1 | 2 | {% capture tocWorkspace %} 3 | {%- comment -%} 4 | Version 1.0.2 5 | 6 | "...like all things liquid - where there's a will, and ~36 hours to spare, there's usually a/some way" ~jaybe 7 | 8 | Usage: 9 | {% include toc.html html=content sanitize=true class="inline_toc" id="my_toc" h_min=2 h_max=3 %} 10 | 11 | Parameters: 12 | * html (string) - the HTML of compiled markdown generated by kramdown in Jekyll 13 | 14 | Optional Parameters: 15 | * sanitize (bool) : false - when set to true, the headers will be stripped of any HTML in the TOC 16 | * class (string) : '' - a CSS class assigned to the TOC 17 | * id (string) : '' - an ID to assigned to the TOC 18 | * h_min (int) : 1 - the minimum TOC header level to use; any header lower than this value will be ignored 19 | * h_max (int) : 6 - the maximum TOC header level to use; any header greater than this value will be ignored 20 | 21 | Output: 22 | An unordered list representing the table of contents of a markdown block. This snippet will only generate the table of contents and will NOT output the markdown given to it 23 | {%- endcomment -%} 24 | 25 | {% capture my_toc %}{% endcapture %} 26 | {% assign minHeader = include.h_min | default: 1 %} 27 | {% assign maxHeader = include.h_max | default: 6 %} 28 | {% assign nodes = include.html | split: ' maxHeader %} 39 | {% continue %} 40 | {% endif %} 41 | 42 | {% if firstHeader %} 43 | {% assign firstHeader = false %} 44 | {% assign minHeader = headerLevel %} 45 | {% endif %} 46 | 47 | {% assign indentAmount = headerLevel | minus: minHeader | add: 1 %} 48 | {% assign _workspace = node | split: '' | first }}>{% endcapture %} 55 | {% assign header = _workspace[0] | replace: _hAttrToStrip, '' %} 56 | 57 | {% assign space = '' %} 58 | {% for i in (1..indentAmount) %} 59 | {% assign space = space | prepend: ' ' %} 60 | {% endfor %} 61 | 62 | {% capture my_toc %}{{ my_toc }} 63 | {{ space }}- [{% if include.sanitize %}{{ header | strip_html }}{% else %}{{ header }}{% endif %}](#{{ html_id }}){% endcapture %} 64 | 65 | {% endfor %} 66 | 67 | {% if include.class %} 68 | {% capture my_toc %}{:.{{ include.class }}} 69 | {{ my_toc | lstrip }}{% endcapture %} 70 | {% endif %} 71 | 72 | {% if include.id %} 73 | {% capture my_toc %}{: #{{ include.id }}} 74 | {{ my_toc | lstrip }}{% endcapture %} 75 | {% endif %} 76 | {% endcapture %}{% assign tocWorkspace = '' %} 77 | 78 | 79 | {% assign toc_items = my_toc | split: '#' %} 80 | {% if toc_items.size > 1 %} 81 | 87 | {% endif %} 88 | -------------------------------------------------------------------------------- /_includes/page-nav.html: -------------------------------------------------------------------------------- 1 | 14 | -------------------------------------------------------------------------------- /_includes/sidebar-toggle.html: -------------------------------------------------------------------------------- 1 |
2 | 3 | 12 |
13 | -------------------------------------------------------------------------------- /_layouts/default.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | {% include head.html %} 4 | 5 | 6 |
7 | {% include sidebar.html %} 8 | 9 |
10 | {% include sidebar-toggle.html %} 11 |
12 | {% include interact.html %} 13 | {% include onthispage.html sanitize=true html=content h_min=2 h_max=3 class="toc__menu" %} 14 | {{ content }} 15 | 16 | {% include page-nav.html %} 17 |
18 |
19 |
20 | 21 | 22 | 23 | -------------------------------------------------------------------------------- /_sass/components/_components.interact-button.scss: -------------------------------------------------------------------------------- 1 | /** 2 | * Stylings for Interact and Show Widget buttons. 3 | * 4 | * [1]: We abuse CSS selector specificity here since the buttons at the top of 5 | * the notebook might have both .interact-button and .js=nbinteract-widget. 6 | * [2]: We want the top buttons to be large. 7 | * [3]: However, a .js=nbinteract-widget appearing alone midway through the 8 | * notebook should be small. 9 | * 10 | */ 11 | 12 | $color-interact-button: #477dca !default; 13 | 14 | %interact-button { 15 | @include inuit-font-size(16px); 16 | background-color: $color-interact-button; 17 | border-radius: 3px; 18 | border: none; 19 | color: white; 20 | cursor: pointer; 21 | display: inline-block; 22 | font-weight: 700; 23 | /* [2] */ 24 | padding: $spacing-unit-tiny $spacing-unit-med; 25 | text-decoration: none; 26 | 27 | &:hover, 28 | &:focus { 29 | text-decoration: none; 30 | } 31 | } 32 | 33 | .buttons { 34 | margin-bottom: $spacing-unit; 35 | 36 | /* [1] */ 37 | .interact-button { 38 | @extend %interact-button; 39 | } 40 | } 41 | 42 | .js-nbinteract-widget { 43 | @extend %interact-button; 44 | 45 | /* [3] */ 46 | padding: $spacing-unit-tiny $spacing-unit; 47 | margin-bottom: $spacing-unit-small; 48 | } 49 | 50 | // If the interact button link is changed with a REST param 51 | div.interact-context { 52 | display: inline; 53 | padding-left: 1em; 54 | font-weight: 600; 55 | } -------------------------------------------------------------------------------- /_sass/components/_components.page__nav.scss: -------------------------------------------------------------------------------- 1 | /** 2 | * Styling for the Next Page / Previous Page links at the bottom of textbook 3 | * pages. 4 | */ 5 | 6 | $color-nav-links: rgba(0, 140, 255, 0.7); 7 | 8 | .c-page__nav { 9 | display: flex; 10 | justify-content: space-between; 11 | align-items: center; 12 | } 13 | 14 | .c-page__nav__prev, 15 | .c-page__nav__next { 16 | flex: 1; 17 | 18 | color: $color-nav-links; 19 | 20 | border: 1px solid $color-nav-links; 21 | border-radius: 3px; 22 | 23 | padding: $spacing-unit-small 0; 24 | } 25 | 26 | .c-page__nav__next { 27 | text-align: right; 28 | } 29 | -------------------------------------------------------------------------------- /_sass/components/_components.sidebar-toggle.scss: -------------------------------------------------------------------------------- 1 | .c-sidebar-toggle { 2 | margin-bottom: $spacing-unit; 3 | } 4 | 5 | .c-sidebar-toggle__label { 6 | @include inuit-font-size(12px); 7 | display: inline-block; 8 | margin-left: $spacing-unit-tiny; 9 | vertical-align: middle; 10 | text-transform: uppercase; 11 | } 12 | -------------------------------------------------------------------------------- /_sass/components/_components.textbook.scss: -------------------------------------------------------------------------------- 1 | /** 2 | * The website contains two main components: the sidebar and the textbook page. 3 | * This file specifies the layout and includes classes to show/hide the sidebar 4 | * on small screens. 5 | * 6 | * The actual styling for the sidebar and page are located in their respective 7 | * component SCSS files. This file manages the layout and width only. 8 | * 9 | * By default, the sidebar is not visible. 10 | * 11 | * [1]: The entire page is positioned relative so that when the page overflows 12 | * (e.g. sidebar open on small screens) the user can't scroll left/right. 13 | * [2]: The sidebar and the textbook page are positioned absolute so that we 14 | * can use translate() on the textbook page to reveal the sidebar. 15 | * [3]: Setting the background color hides the sidebar when it's behind the 16 | * page (otherwise the page is transparent). 17 | * 18 | * When the sidebar is visible: 19 | * 20 | * [4]: Shift the textbook page over to the left. On small screens, the page 21 | * will overflow since the sidebar takes up most of the screen. 22 | * [5]: On larger screens, the page and sidebar have enough room to read them 23 | * simultaneously, so make sure that the page doesn't overflow. 24 | */ 25 | 26 | $sidebar-width: 300px; 27 | 28 | .c-textbook { 29 | /* [1] */ 30 | position: relative; 31 | height: 100vh; 32 | overflow: hidden; 33 | } 34 | 35 | .c-textbook__sidebar, 36 | .c-textbook__page { 37 | /* [2] */ 38 | position: absolute; 39 | height: 100vh; 40 | overflow: auto; 41 | background-color: white; /* [3] */ 42 | } 43 | 44 | .c-textbook__sidebar { 45 | width: $sidebar-width; 46 | } 47 | 48 | .c-textbook__page { 49 | width: 100%; 50 | 51 | transition: transform 250ms ease; 52 | } 53 | 54 | .js-show-sidebar { 55 | .c-textbook__page { 56 | /* [4] */ 57 | transform: translate($sidebar-width, 0); 58 | 59 | @include mq($from: tablet) { 60 | /* [5] */ 61 | width: calc(100% - #{$sidebar-width}); 62 | } 63 | } 64 | } 65 | -------------------------------------------------------------------------------- /_sass/components/_components.textbook__page.scss: -------------------------------------------------------------------------------- 1 | /** 2 | * Styling for textbook pages. Jupyter notebooks generate their own HTML markup 3 | * which we style under the #ipython-notebook selector. 4 | * 5 | * Most of the textbook content is styled using this component. 6 | * 7 | * [1]: Don't add horizontal padding since the content lies within a .o-wrapper 8 | * [2]: Since we use JS to focus the page on load, hide the outline to avoid 9 | * visual cruft. 10 | * 11 | * Notebook styling: 12 | * 13 | * [3]: Add a border around cell input to distinguish it from the output. 14 | * [4]: Some tables are too wide for the page on smaller screens so we let the 15 | * user scroll horizontally. 16 | * [5]: Inline code snippets (usually variable names) should have a gray bg. 17 | */ 18 | 19 | .c-textbook__page { 20 | /* [1] */ 21 | padding: $spacing-unit-small 0; 22 | overflow-x: auto; 23 | @include mq($from: tablet, $until: desktop) { 24 | padding-left: $spacing-unit; 25 | padding-right: $spacing-unit; 26 | } 27 | 28 | @include mq($from: desktop) { 29 | padding-left: $spacing-unit-large; 30 | padding-right: $spacing-unit-large; 31 | } 32 | 33 | &:focus { 34 | /* [2] */ 35 | outline: none; 36 | } 37 | 38 | // Left margin if site is big enough 39 | @media (min-width: $site-margin-min-width) { 40 | margin-left: $left-site-margin; 41 | } 42 | } 43 | 44 | // To ensure enough room for the sidebar 45 | .o-wrapper { 46 | margin-left: 0%; 47 | max-width: 700px; 48 | position: relative; 49 | } 50 | 51 | /** 52 | * Jupyter notebook styling 53 | */ 54 | 55 | .input_area pre, 56 | .output_text pre { 57 | background-color: $color-light-gray; 58 | font-size: 0.9em; 59 | margin-bottom: $spacing-unit-small; 60 | padding: $spacing-unit-small; 61 | overflow-x: auto; 62 | } 63 | 64 | .input_area pre { 65 | /* [3] */ 66 | border: 1px solid $color-dark-gray; 67 | } 68 | 69 | .output_html { 70 | /* [4] */ 71 | overflow-x: auto; 72 | } 73 | 74 | /* [5] */ 75 | code { 76 | padding: 4px; 77 | 78 | @include inuit-font-size(14px); 79 | } 80 | 81 | blockquote { 82 | margin: $spacing-unit-small; 83 | padding: $spacing-unit-med; 84 | border-left: 4px solid $color-dark-gray; 85 | 86 | p:last-child { 87 | margin-bottom: 0; 88 | } 89 | } 90 | 91 | /* Outputs */ 92 | .output_stream, .output_data_text, .output_traceback_line { 93 | margin-left: 2% !important; 94 | border: none !important; 95 | border-radius: 4px !important; 96 | background-color: #fafafa !important; 97 | box-shadow: none !important; 98 | } 99 | 100 | .output_stream:before, .output_data_text:before, .output_traceback_line:before{ 101 | content: none !important; 102 | } 103 | 104 | .output_text pre { 105 | background-color: #F8F8FB !important; 106 | } 107 | 108 | .output_html,.output_png::before 109 | { 110 | padding:1em 1.5em !important; 111 | } 112 | 113 | .output_png img,p img 114 | { 115 | width:100% !important; 116 | max-width: 500px; 117 | display: block; 118 | margin-left: auto; 119 | margin-right: auto; 120 | } 121 | 122 | .hl-ipython3 pre::before,.output_subarea pre::before,.output_html::before,.output_png::before 123 | { 124 | color:#ccc !important; 125 | float:left !important; 126 | margin-bottom:.25em !important; 127 | width:100% !important; 128 | } 129 | 130 | /** 131 | * nbinteract styling 132 | */ 133 | .cell.nbinteract-left { 134 | width: 50%; 135 | float: left; 136 | } 137 | 138 | .cell.nbinteract-right { 139 | width: 50%; 140 | float: right; 141 | } 142 | 143 | .cell.nbinteract-hide_in > .input { 144 | display: none; 145 | } 146 | 147 | .cell.nbinteract-hide_out > .output_wrapper { 148 | display: none; 149 | } 150 | 151 | .cell:after { 152 | content: ''; 153 | display: table; 154 | clear: both; 155 | } 156 | 157 | div.output_subarea { 158 | max-width: initial; 159 | } 160 | 161 | .jp-OutputPrompt { 162 | display: none; 163 | } 164 | -------------------------------------------------------------------------------- /_sass/components/_components.textbook__sidebar-right.scss: -------------------------------------------------------------------------------- 1 | .sidebar__right { 2 | position: absolute; 3 | top: 0; 4 | right: 0; 5 | width: 250px; 6 | margin-right: -250px; 7 | padding-left: 1em; 8 | z-index: 10; 9 | } 10 | 11 | nav.onthispage { 12 | font-family: -apple-system,BlinkMacSystemFont,"Roboto","Segoe UI","Helvetica Neue","Lucida Grande",Arial,sans-serif; 13 | color: #7a8288; 14 | text-transform: uppercase; 15 | letter-spacing: 1px; 16 | background-color: #fff; 17 | border: 1px solid #f2f3f3; 18 | border-radius: 4px; 19 | box-shadow: 0 1px 1px rgba(0,0,0,0.125); 20 | } 21 | 22 | h4.nav__title { 23 | color: #fff; 24 | font-size: .75em; 25 | background: #7a8288; 26 | border-top-left-radius: 4px; 27 | border-top-right-radius: 4px; 28 | margin: 0; 29 | padding: 0.5rem 1rem; 30 | font-family: -apple-system,BlinkMacSystemFont,"Roboto","Segoe UI","Helvetica Neue","Lucida Grande",Arial,sans-serif; 31 | font-size: .8em; 32 | font-weight: bold; 33 | } 34 | 35 | ul.toc__menu { 36 | margin: 0; 37 | padding: 0; 38 | width: 100%; 39 | list-style: none; 40 | font-size: 0.8rem; 41 | } 42 | 43 | ul.toc__menu a { 44 | display: block; 45 | padding: 0.5rem 1rem; 46 | color: #898c8f; 47 | font-size: .8em; 48 | font-weight: bold; 49 | line-height: 1.5; 50 | border-bottom: 1px solid #f2f3f3; 51 | } 52 | 53 | .toc__menu li ul { 54 | 55 | li { 56 | list-style-type: none; 57 | } 58 | 59 | a { 60 | font-weight: normal; 61 | } 62 | } 63 | -------------------------------------------------------------------------------- /_sass/components/_components.textbook__sidebar.scss: -------------------------------------------------------------------------------- 1 | /** 2 | * Styling for the sidebar. 3 | * 4 | * [1]: The sidebar is implemented as ul and li elements so we need to remove 5 | * the bullets and margins. Also make chapter fonts a bit bigger. 6 | * [2]: The entries are tags so we need to remove the default styling. 7 | * [3]: The sidebar divider is just an empty element with a border. 8 | * [4]: The current section needs a higher specificity to override the :hover 9 | * selectors used previously. 10 | * [5]: The logo displayed above the sidebar 11 | */ 12 | $color-sidebar-bg: rgba(255, 255, 255, 0) !default; 13 | $color-sidebar-entry: #364149 !default; 14 | $color-sidebar-entry--active: $color-links !default; 15 | $color-sidebar-divider: #bbb !default; 16 | 17 | .c-textbook__sidebar { 18 | background-color: $color-sidebar-bg; 19 | padding: $spacing-unit-small; 20 | @include inuit-font-size(14px); 21 | border-right: 1px solid rgba(0, 0, 0, 0.07); 22 | opacity: .6; 23 | -webkit-transition: opacity 0.2s ease-in-out; 24 | transition: opacity 0.2s ease-in-out; 25 | &:hover { 26 | opacity: 1; 27 | } 28 | 29 | // Left margin if site is big enough 30 | @media (min-width: $site-margin-min-width) { 31 | margin-left: $left-site-margin; 32 | } 33 | } 34 | 35 | /* [1] */ 36 | .c-sidebar__chapters { 37 | list-style: none; 38 | margin-left: 0; 39 | margin-bottom: 0; 40 | } 41 | 42 | li.c-sidebar__chapter > a { 43 | font-size: 1.2em; 44 | } 45 | 46 | /* [1] */ 47 | .c-sidebar__sections { 48 | list-style: none; 49 | margin-left: $spacing-unit-small; 50 | margin-bottom: 0; 51 | } 52 | 53 | li.c-sidebar__subsection { 54 | margin-left: 20px; 55 | } 56 | 57 | /* [2] */ 58 | .c-sidebar__entry { 59 | display: block; 60 | 61 | padding: $spacing-unit-tiny; 62 | 63 | color: $color-sidebar-entry; 64 | text-decoration: none; 65 | 66 | &:hover { 67 | text-decoration: underline; 68 | } 69 | 70 | &:visited { 71 | color: $color-sidebar-entry; 72 | } 73 | } 74 | 75 | /* [4] */ 76 | .c-sidebar__entry--active.c-sidebar__entry--active { 77 | color: $color-sidebar-entry--active; 78 | } 79 | 80 | /* [3] */ 81 | .c-sidebar__divider { 82 | border-top: 1px solid $color-sidebar-divider; 83 | margin: $spacing-unit-tiny; 84 | } 85 | 86 | /* [5] */ 87 | img.textbook_logo { 88 | margin-top: 20px; 89 | max-height: 100px; 90 | margin: 0px auto 20px auto; 91 | display: block; 92 | } -------------------------------------------------------------------------------- /_sass/elements/_elements.links.scss: -------------------------------------------------------------------------------- 1 | /** 2 | * Styling for links 3 | */ 4 | 5 | a, 6 | a:visited { 7 | color: $color-links; 8 | text-decoration: none; 9 | } 10 | -------------------------------------------------------------------------------- /_sass/elements/_elements.syntax-highlighting.scss: -------------------------------------------------------------------------------- 1 | /** 2 | * Syntax highlighting for code cells 3 | */ 4 | 5 | pre.highlight { 6 | overflow-x: auto; 7 | padding: .5em; 8 | } 9 | .highlight { 10 | 11 | .c { color: #998; font-style: italic } // Comment 12 | .err { color: #a61717; background-color: #e3d2d2 } // Error 13 | .k { font-weight: bold } // Keyword 14 | .o { font-weight: bold } // Operator 15 | .cm { color: #998; font-style: italic } // Comment.Multiline 16 | .cp { color: #999; font-weight: bold } // Comment.Preproc 17 | .c1 { color: #998; font-style: italic } // Comment.Single 18 | .cs { color: #999; font-weight: bold; font-style: italic } // Comment.Special 19 | .gd { color: #000; background-color: #fdd } // Generic.Deleted 20 | .gd .x { color: #000; background-color: #faa } // Generic.Deleted.Specific 21 | .ge { font-style: italic } // Generic.Emph 22 | .gr { color: #a00 } // Generic.Error 23 | .gh { color: #999 } // Generic.Heading 24 | .gi { color: #000; background-color: #dfd } // Generic.Inserted 25 | .gi .x { color: #000; background-color: #afa } // Generic.Inserted.Specific 26 | .go { color: #888 } // Generic.Output 27 | .gp { color: #555 } // Generic.Prompt 28 | .gs { font-weight: bold } // Generic.Strong 29 | .gu { color: #aaa } // Generic.Subheading 30 | .gt { color: #a00 } // Generic.Traceback 31 | .kc { font-weight: bold } // Keyword.Constant 32 | .kd { font-weight: bold } // Keyword.Declaration 33 | .kp { font-weight: bold } // Keyword.Pseudo 34 | .kr { font-weight: bold } // Keyword.Reserved 35 | .kt { color: #458; font-weight: bold } // Keyword.Type 36 | .m { color: #099 } // Literal.Number 37 | .s { color: #d14 } // Literal.String 38 | .na { color: #008080 } // Name.Attribute 39 | .nb { color: #0086B3 } // Name.Builtin 40 | .nc { color: #458; font-weight: bold } // Name.Class 41 | .no { color: #008080 } // Name.Constant 42 | .ni { color: #800080 } // Name.Entity 43 | .ne { color: #900; font-weight: bold } // Name.Exception 44 | .nf { color: #900; font-weight: bold } // Name.Function 45 | .nn { color: #555 } // Name.Namespace 46 | .nt { color: #000080 } // Name.Tag 47 | .nv { color: #008080 } // Name.Variable 48 | .ow { font-weight: bold } // Operator.Word 49 | .w { color: #bbb } // Text.Whitespace 50 | .mf { color: #099 } // Literal.Number.Float 51 | .mh { color: #099 } // Literal.Number.Hex 52 | .mi { color: #099 } // Literal.Number.Integer 53 | .mo { color: #099 } // Literal.Number.Oct 54 | .sb { color: #d14 } // Literal.String.Backtick 55 | .sc { color: #d14 } // Literal.String.Char 56 | .sd { color: #d14 } // Literal.String.Doc 57 | .s2 { color: #d14 } // Literal.String.Double 58 | .se { color: #d14 } // Literal.String.Escape 59 | .sh { color: #d14 } // Literal.String.Heredoc 60 | .si { color: #d14 } // Literal.String.Interpol 61 | .sx { color: #d14 } // Literal.String.Other 62 | .sr { color: #009926 } // Literal.String.Regex 63 | .s1 { color: #d14 } // Literal.String.Single 64 | .ss { color: #990073 } // Literal.String.Symbol 65 | .bp { color: #999 } // Name.Builtin.Pseudo 66 | .vc { color: #008080 } // Name.Variable.Class 67 | .vg { color: #008080 } // Name.Variable.Global 68 | .vi { color: #008080 } // Name.Variable.Instance 69 | .il { color: #099 } // Literal.Number.Integer.Long 70 | } 71 | 72 | /* ANSI coloring for text_regex.ipynb */ 73 | .ansi-bold { 74 | font-weight: bold; 75 | } 76 | 77 | .ansi-yellow-bg { 78 | background-color: #DDB62B; 79 | } 80 | 81 | .ansi-black-intense-fg { 82 | color: #282C36; 83 | } 84 | -------------------------------------------------------------------------------- /_sass/elements/_elements.tables.scss: -------------------------------------------------------------------------------- 1 | /** 2 | * Styling for tables. In the textbook, almost all tables display the contents 3 | * of a pandas DataFrame. 4 | * 5 | * [1]: Some tables are very small, so we shouldn't force them to be full-width 6 | * [2]: Add striping to table rows to make them easier to read. 7 | */ 8 | 9 | table { 10 | /* [1] */ 11 | max-width: 100%; 12 | width: initial; 13 | 14 | border-collapse: collapse; 15 | border-spacing: 0; 16 | } 17 | 18 | table td, 19 | table th { 20 | padding: $spacing-unit-tiny $spacing-unit-small; 21 | border: 1px solid $color-dark-gray; 22 | text-align: right; 23 | } 24 | 25 | /* [2] */ 26 | table tr:nth-child(2n) { 27 | background-color: $color-light-gray; 28 | } 29 | -------------------------------------------------------------------------------- /_sass/elements/_elements.typography.scss: -------------------------------------------------------------------------------- 1 | /** 2 | * Site-wide typography 3 | */ 4 | 5 | body { 6 | // Use system font stack: 7 | // https://css-tricks.com/snippets/css/system-font-stack/ 8 | font-family: $global-font-family !important; 9 | $color: $color-text; 10 | } 11 | 12 | /** 13 | * Code-like elements. 14 | */ 15 | pre, 16 | code, 17 | kbd, 18 | samp { 19 | font-family: $monospace; 20 | font-style: normal; 21 | } 22 | 23 | /** 24 | * Header styling 25 | */ 26 | $header-font-family: $sans-serif !default; 27 | 28 | h1, 29 | h2, 30 | h3, 31 | h4, 32 | h5, 33 | h6 { 34 | margin: 2em 0 0.5em; 35 | line-height: 1.2; 36 | font-family: $header-font-family !important; 37 | font-weight: bold; 38 | } 39 | 40 | h1 { 41 | margin-top: 0; 42 | font-size: $type-size-3; 43 | } 44 | 45 | h2 { 46 | font-size: $type-size-4; 47 | } 48 | 49 | h3 { 50 | font-size: $type-size-5; 51 | } 52 | 53 | h4 { 54 | font-size: $type-size-6; 55 | } 56 | 57 | h5 { 58 | font-size: $type-size-6; 59 | } 60 | 61 | h6 { 62 | font-size: $type-size-6; 63 | } -------------------------------------------------------------------------------- /_sass/elements/_elements.variables.scss: -------------------------------------------------------------------------------- 1 | /** 2 | * Variables 3 | */ 4 | 5 | $serif: Georgia, Times, serif !default; 6 | $sans-serif: -apple-system, BlinkMacSystemFont, "Roboto", "Segoe UI", 7 | "Helvetica Neue", "Lucida Grande", Arial, sans-serif !default; 8 | $monospace: Monaco, Consolas, "Lucida Console", monospace !default; 9 | 10 | $global-font-family: $sans-serif !default; 11 | $header-font-family: $sans-serif !default; 12 | $caption-font-family: $serif !default; 13 | 14 | /* type scale */ 15 | $type-size-1: 2.441em !default; // ~39.056px 16 | $type-size-2: 1.953em !default; // ~31.248px 17 | $type-size-3: 1.563em !default; // ~25.008px 18 | $type-size-4: 1.25em !default; // ~20px 19 | $type-size-5: 1em !default; // ~16px 20 | $type-size-6: 0.75em !default; // ~12px 21 | $type-size-7: 0.6875em !default; // ~11px 22 | $type-size-8: 0.625em !default; // ~10px 23 | 24 | /* Left-margin (applied if screen is big enough) */ 25 | $left-site-margin: 20% !default; 26 | $site-margin-min-width: 1700px !default; -------------------------------------------------------------------------------- /_sass/generic/_generic.phone-scrolling.scss: -------------------------------------------------------------------------------- 1 | /** 2 | * Makes scrolling smooth for phones 3 | */ 4 | 5 | * { 6 | -webkit-overflow-scrolling: touch; 7 | } 8 | -------------------------------------------------------------------------------- /_sass/hamburgers/_base.scss: -------------------------------------------------------------------------------- 1 | // Hamburger 2 | // ================================================== 3 | .hamburger { 4 | padding: $hamburger-padding-y $hamburger-padding-x; 5 | display: inline-block; 6 | cursor: pointer; 7 | 8 | transition-property: opacity, filter; 9 | transition-duration: $hamburger-hover-transition-duration; 10 | transition-timing-function: $hamburger-hover-transition-timing-function; 11 | 12 | // Normalize (