Merge branch 'gh-pages' into documentation

Author: janash

Diff for: README.md

@@ -1,8 +1,19 @@
-# FIXME Lesson title
+# Python Scripting for the Computational Molecular Sciences
 
-[![Create a Slack Account with us](https://img.shields.io/badge/Create_Slack_Account-The_Carpentries-071159.svg)](https://swc-slack-invite.herokuapp.com/)
+This is the GitHub repository for the Python Data and Scripting Workshop developed by [The Molecular Sciences Software Institute](https://molssi.org). This website template is based on a template developed by [The Software Carpentries](https://software-carpentry.org). You can find the rendered website for this material [here](https://molssi-education.github.io/python_scripting_cms/).
 
-FIXME
+The MolSSI Python Data and Scripting workshop is designed for students who are currently involved in, or planning to start computational chemistry research. This workshop is designed to help students develop practical programming skills that will benefit their undergraduate research, and will take students through introductory programming and scripting with Python to version control and sharing their code with others. NO prior programming experience is required.
+
+### Workshop Topics
+- Basic Python syntax and control structures
+- Reading and writing files
+- File manipulation and parsing
+- Analyzing and graphing data
+- Writing functions
+- Creating command line programs from Python scripts
+- Basic testing using PyTest
+- Version control with git
+- Sharing code on GitHub
 
 ## Contributing
 
@@ -15,7 +26,8 @@ how to write new episodes.
 
 ## Maintainer(s)
 
-* FIXME
+* Jessica A. Nash ([email protected], GitHub: janash)
+* Ashley Ringer McDonald
 
 ## Authors
 

Diff for: _episodes/01-introduction.md

@@ -48,7 +48,7 @@ Now that our notebook is set-up, we're ready to start learning some Python!
 Any python interpreter can work just like a calculator.  This is not very useful. Type the following into the next cell of your Jupyter notebook.
 
 ```
-3+7
+3 + 7
 ```
 {: .language-python}
 
@@ -68,7 +68,7 @@ Let's see this in action with a calculation. Type the following into the next ce
 deltaH = -541.5   #kJ/mole
 deltaS =  10.4     #kJ/(mole K)
 temp = 298      #Kelvin
-deltaG = deltaH - temp*deltaS
+deltaG = deltaH - temp * deltaS
 ```
 {: .language-python}
 
@@ -93,7 +93,7 @@ In the previous code block, we introduced the `print()` function.  Often, we wil
 Note that if you do not specify a new name for a variable, then it doesn't automatically change the value of the variable; this is called being *immutable*.  For example if we typed
 ```
 print(deltaG)
-deltaG*1000
+deltaG * 1000
 print(deltaG)
 ```
 {: .language-python}
@@ -106,7 +106,7 @@ print(deltaG)
 Nothing happened to the value of `deltaG`.  If we wanted to change the value of `deltaG` we would have to re-save the variable using the same name to overwrite the existing value.
 ```
 print(deltaG)
-deltaG = deltaG*1000
+deltaG = deltaG * 1000
 print(deltaG)
 ```
 {: .language-python}
@@ -119,7 +119,7 @@ print(deltaG)
 There are situations where it is reasonable to overwrite a variable with a new value, but you should always think carefully about this.  Usually it is a better practice to give the variable a new name and leave the existing variable as is.  
 ```
 print(deltaG)
-deltaG_joules = deltaG*1000
+deltaG_joules = deltaG * 1000
 print(deltaG)
 print(deltaG_joules)
 ```
@@ -137,7 +137,7 @@ Python can do what is called multiple assignment where you assign several variab
 ```
 #I can assign all these variables at once
 deltaH, deltaS, temp = -541.5, 10.4, 298
-deltaG = deltaH - temp*deltaS
+deltaG = deltaH - temp * deltaS
 print(deltaG)
 ```
 {: .language-python}
@@ -201,7 +201,7 @@ print(energy_kcal[0])
 You can use an element of a list as a variable in a calculation.  
 ```
 # Convert the second list element to kilojoules.
-energy_kilojoules = energy_kcal[1]*4.184
+energy_kilojoules = energy_kcal[1] * 4.184
 print(energy_kilojoules)
 ```
 {: .language-python}
@@ -263,7 +263,7 @@ energy_kcal[0:2]
 print(energy_kcal)
 ```
 {: .language-python}
-nothing happens to `energy_kcal.
+nothing happens to `energy_kcal`.
 ```
 [-13.4, -2.7, 5.4, 42.1]
 [-13.4, -2.7, 5.4, 42.1]
@@ -279,10 +279,14 @@ for variable in list:
 ```
 {: .language-python}
 
-Indentation is very important in python.  There is nothing like an `end` or `exit` statement that tells you that you are finished with the loop.  The indentation shows you what statements are in the loop.  Let's use a loop to change all of our energies in kcal to kJ.
+There are two very important pieces of syntax for the `for` loop. Notice the colon `:` after the word list. You will always have a colon at the end of a `for` statement. If you forget the colon, you will get an error when you try to run your code.
+
+The second thing to notice is that the lines of code under the `for` loop (the things you want to do several times) are indented. Indentation is very important in python.  There is nothing like an `end` or `exit` statement that tells you that you are finished with the loop. The indentation shows you what statements are in the loop. Each indentation is 4 spaces by convention in Python 3. However, if you are using an editor which understands Python, it will do the correct indentation for you when you press the tab key on your keyboard. In fact, the Jupyter notebook will notice that you used a colon (`:`) in the previous line, and will indent for you (so you will not need to press tab).
+
+Let's use a loop to change all of our energies in kcal to kJ.
 ```
 for number in energy_kcal:
-    kJ = number*4.184
+    kJ = number * 4.184
     print(kJ)
 ```
 {: .language-python}
@@ -304,7 +308,7 @@ list_name.append(new_thing)
 Try running this block of code.  See if you can figure out why it doesn't work.
 ```
 for number in energy_kcal:
-    kJ = number*4.184
+    kJ = number * 4.184
     energy_kJ.append(kJ)
 
 print(energy_kJ)
@@ -329,7 +333,7 @@ This code doesn't work because on the first iteration of our loop, the list `ene
 ```
 energy_kJ = []
 for number in energy_kcal:
-    kJ = number*4.184
+    kJ = number * 4.184
     energy_kJ.append(kJ)
 
 print(energy_kJ)
@@ -347,7 +351,7 @@ Within your code, you may need to evaluate a variable and then do something if t
 negative_energy_kJ = []
 
 for number in energy_kJ:
-    if number<0:
+    if number < 0:
         negative_energy_kJ.append(number)
 
 print(negative_energy_kJ)
@@ -369,7 +373,7 @@ You can also use `and`, `or`, and `not` to check more than one condition.
 ```
 negative_numbers = []
 for number in energy_kJ:
-    if number<0 or number==0:
+    if number < 0 or number == 0:
         negative_numbers.append(number)
 
 print(negative_numbers)

Diff for: _episodes/02-file_parsing.md

@@ -50,7 +50,7 @@ or similar to this if you are on Windows
 ~~~
 {: .output}
 
-Notice that the file paths are different for these two systems. The Windows system uses a forward slash ('\\'), while Mac and Linux use a backslash ('/') for filepaths.
+Notice that the file paths are different for these two systems. The Windows system uses a backslash ('\\'), while Mac and Linux use a forward slash ('/') for filepaths.
 
 When we write a script, we want it to be usable on any operating system, thus we will use a python module called `os.path` that will allow us to define file paths in a general way.
 
@@ -69,7 +69,7 @@ data/outfiles/ethanol.out
 ~~~
 {:. .output}
 
-Here, we have specified that our filepath contains the 'data' and 'outfiles' directory, and the `os.path` module has made this into a filepath that is usable by our system. If you are on Windows, you will instead see that a forward slash is used.
+Here, we have specified that our filepath contains the 'data' and 'outfiles' directory, and the `os.path` module has made this into a filepath that is usable by our system. If you are on Windows, you will instead see that a backslash is used.
 
 > ## Absolute and relative paths
 > File paths can be *absolute*, or *relative*.
@@ -108,6 +108,18 @@ outfile.close()
 ~~~
 {: .language-python}
 
+> ## An alternative way to open a file.
+> Alternatively, you can open a file using `context-manager`. In this case, the context manager will automatically handle closing of the file. To use a context manager to open and close the file, you use the word `with`, and put everything you want to be done while the file is open in an indented block.
+> ~~~
+> with open(ethanol_file,"r") as outfile:
+>     data = outfile.readlines()
+> ~~~
+> {: .language-python}
+>
+> This is often the preferred way to deal with files because you do not have to remember to close the file.
+{: .callout}
+
+
 > ## Check Your Understanding
 > Check that your file was read in correctly by determining how many lines are in the file.
 >> ## Answer
@@ -129,7 +141,7 @@ Let's take a look at what's in the file.
 
 ~~~
 for line in data:
-  print(line)
+    print(line)
 ~~~
 {: .language-python}
 
@@ -196,12 +208,24 @@ print(words)
 
 From this `print` statement, we now see that we have a list called words, where we have split `energy_line`.  The energy is actually the fourth element of this list, so we can now save it as a new variable.
 
-```
+```python
 energy = words[3]
 print(energy)
 ```
 {: .language-python}
 
+> ## Python negative indexing
+> We also recogize that "energy" is the last element of the list. Therefore, an alternative way to assign `energy` is:
+> ```python
+> energy = words[-1]
+> print(energy)
+> ```
+>
+> In the example above,  the index value of `-1` gives the last element, and `-2` would give the second last element of a list, and so on. An excelent tutorial on Python list accessed by index can be found [here](https://realpython.com/python-lists-tuples/#list-elements-can-be-accessed-by-index)
+{: .callout}
+
+
+
 ```
 -154.09130176573018
 ```
@@ -237,48 +261,48 @@ energy = float(words[3])
 >## Exercise on File Parsing (should we move this to the end?)
 Use the provided sapt.out file.  In this output file, the program calculates the interaction energy for an ethene-ethyne complex.  The output reports four interaction energy components: electrostatics, induction, exchange, and dispersion.  Parse each of these energies, in kcal/mole, from the output file.  (Hint: study the file in a text editor to help you decide what to search for.) Calculate the total interaction energy by adding the four components together.  Your code's output should look something like this:
 > ~~~
-> Electrostatics : -2.25850118 kcal/mole
-> Exchange : 2.27730198 kcal/mole
-> Induction : -0.5216933 kcal/mole
-> Dispersion : -0.9446677 kcal/mole
-> Total Energy : 1.4475602000000003 kcal/mole
+> Electrostatics : -2.25850118 kcal/mol
+> Exchange : 2.27730198 kcal/mol
+> Induction : -0.5216933 kcal/mol
+> Dispersion : -0.9446677 kcal/mol
+> Total Energy : 1.4475602000000003 kcal/mol
 > ~~~
 > {: language.python}
 >
 > > ## Solution
 >>
 >> This is one possible solution for the SAPT parsing exercise
 >> ~~~
->> saptout = open('SAPT.out','r')
->> saptlines = saptout.readlines()
->> important_lines=[]
->> energies=[]
->> for line in saptlines:
->>     if 'Electrostatics    ' in line:
->>        electro_line = line
->>        important_lines.append(electro_line)
->>    if 'Exchange       ' in line:
->>        exchange_line = line
->>        important_lines.append(exchange_line)
->>    if 'Induction      ' in line:
->>        induction_line = line
->>        important_lines.append(induction_line)
->>    if 'Dispersion     ' in line:
->>        dispersion_line = line
->>        important_lines.append(dispersion_line)
->>
->> #print(important_lines)
->>
+>> important_lines = []
+>> energies = []
+>> 
+>> with open('SAPT.out','r') as saptout:
+>>     for line in saptout:
+>>         if 'Electrostatics    ' in line:
+>>             electro_line = line
+>>             important_lines.append(electro_line)
+>>         if 'Exchange       ' in line:
+>>             exchange_line = line
+>>             important_lines.append(exchange_line)
+>>         if 'Induction      ' in line:
+>>             induction_line = line
+>>             important_lines.append(induction_line)
+>>         if 'Dispersion     ' in line:
+>>             dispersion_line = line
+>>             important_lines.append(dispersion_line)
+>> 
+>> # print(important_lines)
+>> 
 >> for line in important_lines:
->>    words = line.split()
->>    #print(words)
->>    energy_type = words[0]
->>    energy_kcal = float(words[3])
->>    energies.append(energy_kcal)
->>    print(energy_type, ':', energy_kcal, 'kcal/mole')
->>
->> total_energy=energies[0]+energies[1]+energies[2]+energies[3]
->> print('Total Energy', ':', total_energy, 'kcal/mole')
+>>     words = line.split()
+>>     # print(words)
+>>     energy_type = words[0]
+>>     energy_kcal = float(words[3])
+>>     energies.append(energy_kcal)
+>>     print('{} : {} kcal/mol'.format(energy_type, energy_kcal))
+>> 
+>> total_energy = sum(energies)
+>> print('Total Energy : {} kcal/mol'.format(total_energy))
 >> ~~~
 >> {: .language-python}
 > {: .solution}
@@ -300,6 +324,13 @@ for linenum, line in enumerate(list_name):
 
 In this notation, there are now *two* variables you can use in your loop commands, `linenum` (which can be named something else) will keep up with what iteration you are on in the loop, in this case what line you are on in the file. The variable `line` (which could be named something else) functions exactly as it did before, holding the actual information from the list.  Finally, instead of just giving the list name you use `enumerate(list_name)`.  
 
+> ## `Enumerate` with index other than 0:
+> `enumerate(list_name)` will start with 0-index so the first line will be label as '0', to change this behavior, use `start` variable in enumerate. For example, to start with index of "1" you can do:
+> ```python
+> for linenum, line in enumerate(data, start=1):
+>   # do something with 'linenum' and 'line'
+{: .callout}
+
 This block of code searches our file for the line that contains "Center" and reports the line number.
 ```
 for linenum, line in enumerate(data):
@@ -313,7 +344,7 @@ for linenum, line in enumerate(data):
        Center              X                  Y                   Z               Mass       
 ```
 {: .output}
-Now we know that this is line 77 in our file (remember that you start counting at zero!).  
+Now we know that this is line 77 in our file (remember that you start counting at zero!). 
 
 >## Check Your Understanding
 >What would be printed if you entered the following:
@@ -345,6 +376,6 @@ Now we know that this is line 77 in our file (remember that you start counting a
 {: .challenge}
 
 ## A final note about regular expressions
-Sometimes you will need to match something more complex than just a particular word or phrase in your output file.  Sometimes you will need to match a particular word, but only if it is found at the beginning of a line.  Or perhaps you will need to match a particular pattern of data, like a capital letter followed by a number, but you won't know the exact letter and number you are looking for.  These types of matching situations are handled with something called *regular expressions* which is accessed through the python module `re`.  While using regular expressions is outside the scope of this tutorial, they are very useful and you might want to learn more about them in the future.  A tutorial can be found at _______.  
+Sometimes you will need to match something more complex than just a particular word or phrase in your output file.  Sometimes you will need to match a particular word, but only if it is found at the beginning of a line.  Or perhaps you will need to match a particular pattern of data, like a capital letter followed by a number, but you won't know the exact letter and number you are looking for.  These types of matching situations are handled with something called *regular expressions* which is accessed through the python module `re`.  While using regular expressions (regex) is outside the scope of this tutorial, they are very useful and you might want to learn more about them in the future.  A tutorial can be found at [Automate the Boring Stuff with Python](https://automatetheboringstuff.com/2e/chapter7/) book.  A great test site for regex is [here](https://regex101.com/)
 
 {% include links.md %}