index.html 10.9 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta http-equiv="last-modified" content="2017-08-04 00:20:27 +0200">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <!-- meta "search-domain" used for google site search function google_search() -->
    <meta name="search-domain" value="/swc-releases/2017.08/python-novice-inflammation">
    <link rel="stylesheet" type="text/css" href="../assets/css/bootstrap.css" />
    <link rel="stylesheet" type="text/css" href="../assets/css/bootstrap-theme.css" />
    <link rel="stylesheet" type="text/css" href="../assets/css/lesson.css" />
    
    <link rel="shortcut icon" type="image/x-icon" href="/favicon-swc.ico" />
    
    <!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
    <!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
    <!--[if lt IE 9]>
	<script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
	<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
	<![endif]-->
    <title>Programming with Python: Instructor Notes</title>
  </head>
  <body>
    <div class="container">
      
<nav class="navbar navbar-default">
  <div class="container-fluid">
    <div class="navbar-header">
      <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1" aria-expanded="false">
        <span class="sr-only">Toggle navigation</span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      </button>

      
      

      
      <a class="navbar-brand" href="../">Home</a>

    </div>
    <div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
      <ul class="nav navbar-nav">

	
        <li><a href="../conduct/">Code of Conduct</a></li>

	
        
        <li><a href="../setup/">Setup</a></li>
        <li class="dropdown">
          <a href="../" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Episodes <span class="caret"></span></a>
          <ul class="dropdown-menu">
            
            <li><a href="../01-numpy/">Analyzing Patient Data</a></li>
            
            <li><a href="../02-loop/">Repeating Actions with Loops</a></li>
            
            <li><a href="../03-lists/">Storing Multiple Values in Lists</a></li>
            
            <li><a href="../04-files/">Analyzing Data from Multiple Files</a></li>
            
            <li><a href="../05-cond/">Making Choices</a></li>
            
            <li><a href="../06-func/">Creating Functions</a></li>
            
            <li><a href="../07-errors/">Errors and Exceptions</a></li>
            
            <li><a href="../08-defensive/">Defensive Programming</a></li>
            
            <li><a href="../09-debugging/">Debugging</a></li>
            
            <li><a href="../10-cmdline/">Command-Line Programs</a></li>
            
	    <li role="separator" class="divider"></li>
            <li><a href="../aio/">All in one page (Beta)</a></li>
          </ul>
        </li>
	

	
	
        <li class="dropdown">
          <a href="../" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Extras <span class="caret"></span></a>
          <ul class="dropdown-menu">
            <li><a href="../reference/">Reference</a></li>
            
            <li><a href="../about/">About</a></li>
            
            <li><a href="../discuss/">Discussion</a></li>
            
            <li><a href="../figures/">Figures</a></li>
            
            <li><a href="../guide/">Instructor Notes</a></li>
            
          </ul>
        </li>
	

	
        <li><a href="../license/">License</a></li>
	
	<li><a href="/edit/gh-pages/_extras/guide.md">Improve this page <span class="glyphicon glyphicon-pencil" aria-hidden="true"></span></a></li>
	
      </ul>
      <form class="navbar-form navbar-right" role="search" id="search" onsubmit="google_search(); return false;">
        <div class="form-group">
          <input type="text" id="google-search" placeholder="Search..." aria-label="Google site search">
        </div>
      </form>
    </div>
  </div>
</nav>


<h1 class="maintitle"><a href="../">Programming with Python</a>: Instructor Notes</h1>

<h2 id="legend">Legend</h2>

<p>We are using a dataset with records on inflammation from patients following an
arthritis treatment.</p>

<p>We make reference in the lesson that this data is somehow strange. It is strange
because it is fabricated! The script used to generate the inflammation data
is included as <a href="tools/gen_inflammation.py"><code class="highlighter-rouge">tools/gen_inflammation.py</code></a>.</p>

<h2 id="overall">Overall</h2>

<p>This lesson is written as an introduction to Python,
but its real purpose is to introduce the single most important idea in programming:
how to solve problems by building functions,
each of which can fit in a programmer’s working memory.
In order to teach that,
we must teach people a little about
the mechanics of manipulating data with lists and file I/O
so that their functions can do things they actually care about.
Our teaching order tries to show practical uses of every idea as soon as it is introduced;
instructors should resist the temptation to explain
the “other 90%” of the language
as well.</p>

<p>The final example asks them to build a command-line tool
that works with the Unix pipe-and-filter model.
We do this because it is a useful skill
and because it helps learners see that the software they use isn’t magical.
Tools like <code class="highlighter-rouge">grep</code> might be more sophisticated than
the programs our learners can write at this point in their careers,
but it’s crucial they realize this is a difference of scale rather than kind.</p>

<p>Explain that we use Python because:</p>

<ul>
  <li>It’s free.</li>
  <li>It has a lot of scientific libraries, and more are constantly being added.</li>
  <li>It has a large scientific user community.</li>
  <li>It’s easier for novices to learn than most of the mature alternatives.
(Software Carpentry originally used Perl;
when we switched,
we found that we could cover as much material in two days in Python
as we’d covered in three days in Perl,
and that retention was higher.)</li>
</ul>

<p>We do <em>not</em> include instructions on running the Jupyter Notebook in the tutorial
because we want to focus on the language rather than the tools.
Instructors should, however, walk learners through some basic operations:</p>

<ul>
  <li>Launch from the command line with <code class="highlighter-rouge">jupyter notebook</code>.</li>
  <li>Create a new notebook.</li>
  <li>Enter code or data in a cell and execute it.</li>
  <li>Explain the difference between <code class="highlighter-rouge">In[#]</code> and <code class="highlighter-rouge">Out[#]</code>.</li>
</ul>

<p>Watching the instructor grow programs step by step
is as helpful to learners as anything to do with Python.
Resist the urge to update a single cell repeatedly
(which is what you’d probably do in real life).
Instead,
clone the previous cell and write the update in the new copy
so that learners have a complete record of how the program grew.
Once you’ve done this,
you can say,
“Now why don’t we just break things into small functions right from the start?”</p>

<p>The discussion of command-line scripts
assumes that students understand standard I/O and building filters,
which are covered in the lesson on the shell.</p>

<h2 id="frequently-argued-issues-fai">Frequently Argued Issues (FAI)</h2>

<ul>
  <li>
    <p><code class="highlighter-rouge">import ... as ...</code> syntax.</p>

    <p>This syntax is commonly used in the scientific Python community;
it is explicitly recommended in documentation to <code class="highlighter-rouge">import numpy as np</code>
and <code class="highlighter-rouge">import matplotlib.pyplot as plt</code>. Despite that, we have decided
not to introduce aliasing imports in this novice lesson due to the
additional cognitive load it puts on students, despite the typing that
it saves. A good summary of arguments for and against can be found in
<a href="https://github.com/swcarpentry/python-novice-inflammation/pull/61">PR #61</a>.</p>

    <p>It is up to you as an individual instructor whether you want to introduce
these aliases when you teach this lesson, but we encourage you to please
read those arguments thoroughly before deciding one way or the other.</p>
  </li>
  <li>
    <p>NumPy methods.</p>

    <p>We used to use NumPy array methods in the first <a href="../01-numpy/">NumPy topic</a>.
We switched these methods to the equivalent functions because a majority
of instructors supported the change; see
<a href="https://github.com/swcarpentry/python-novice-inflammation/pull/244">PR #244</a>
for detailed arguments for and against the change.</p>
  </li>
  <li>
    <p>Underscores vs. hyphens in filenames</p>

    <p>We used to use hyphens in filenames in order to signify that these Python
files should only be run as scripts and never imported. However, after some
<a href="https://github.com/swcarpentry/python-novice-inflammation/pull/254">discussion</a>,
including an informal Twitter poll, we switched over to underscores because
many files that start off as Python scripts end up being imported eventually.
For that reason, we also added <code class="highlighter-rouge">if __name__ == '__main__'</code> guards around
<code class="highlighter-rouge">main()</code> calls, which is how real-world Python scripts ensure that imports
do not result in side-effects.</p>
  </li>
</ul>

<p>After discussing the challenges is a good time to introduce the <code class="highlighter-rouge">b *= 2</code> syntax.</p>


      
      
<footer>
  <div class="row">
    <div class="col-md-6" align="left">
      <h4>
	Copyright &copy; 2016–2017
	
	<a href="https://software-carpentry.org">Software Carpentry Foundation</a>
	
      </h4>
    </div>
    <div class="col-md-6" align="right">
      <h4>
	
	<a href="/edit/gh-pages/_extras/guide.md">Edit on GitHub</a>
	
	/
	<a href="/blob/gh-pages/CONTRIBUTING.md">Contributing</a>
	/
	<a href="/">Source</a>
	/
	<a href="/blob/gh-pages/CITATION">Cite</a>
	/
	<a href="">Contact</a>
      </h4>
    </div>
  </div>
</footer>

      
    </div>
    
<script src="../assets/js/jquery.min.js"></script>
<script src="../assets/js/bootstrap.min.js"></script>
<script src="../assets/js/lesson.js"></script>
<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
  ga('create', 'UA-37305346-2', 'auto');
  ga('send', 'pageview');
</script>

  </body>
</html>