Lab1: Communicating science We would all like to be good citizens of the scientific community. An important part of being a good citizen is being able to communicate results, papers, and ideas. Since many of our colleagues live in different parts of the world and hence have different resources available to them we cannot always assume that they have the same commercial software package (including upgrades) for preparing manuscripts that we do. Moreover, how can equations be exchanged easily by e-mail? A modern day solution is to make use of the open source computing network available on the Internet. In other words, we only require that our colleagues have access to the Internet. There are all sorts of computer software packages available on the Internet; many of them are exactly the same softwares that are presently used at the cutting edges of scientific research (for example, check out the SciPy website). A big advantage is that once we become familiar with these products we have access to them anywhere in the world. Study abroad students from The Claremont Colleges have already been able to use their experience with the open source computing network to help students, workers and scientists in the countries they have visited. Computer setup: This lab manual has been written with the assumption that your instructors have placed LaTeX, XPPAUT and Python onto a central Linux computer that can be accessed either using computer terminal in a computer laboratory or, perhaps, by logging into using your laptop. However, it is now relatively easy to install all of these packages onto your own laptop for free. This is the preferred way to do these labs because you retain the use of these tools for your own purposes after you complete the course 1. 1 Beginning fall, 2014 we require all students in this course to install these computer packages onto their personal laptops. We do this in three stages: Week 1 (LaTeX); Week 2 (XPPAUT) and Week 3 (Python). Our experience is that installing these packages is easier for students with PC s than those possessing Mac s. Nonetheless all students with perseverance and the help of IT can 1
LaTeX: See for example latex-project.org/ftp.html. Most students using PC s first installed MikTek (miktek.org) followed by Winshell (e.g. www.winshell.de). Latex if often provided on the disks that come with the purchase of a new Mac. XPP/XPPAUT: See www.math.pitt.edu/ bard/xpp.html. Python: We very strongly recommend that students install Enthought s Canopy Express (https://store.enthought.com). A huge advantage is that packages required to work with images and animation can readily be installed and managed through Canopy Express. Today s lab: In this lab we address how to prepare manuscripts containing equations and figures. The software package we will use is called LaTeX. This is the same software package that is used by the publishers of most journals and books that you read which contain equations. LaTeX is a completely different concept than, for example, a word processor such as WORD. Packages such as WORD are actually programs that produce the document the way that the programmers who designed this package wanted it to be produced. In contrast, when we use LaTeX we write the program ourselves that will be used to generate the document. In fact, for many of you preparing a LaTeX document will be the first computer program that you have written! Since we are writing the program ourselves we can get an article that looks exactly like we want it to look. More importantly, the program is written using a text editor 2 and hence has the form of an ASCII file. This means that we can easily send it to our colleagues by email and they can then run it locally on their own computer to generate the document. It is really not very hard to learn to use LaTeX. We focus on the skill set necessary to make the most basic LaTeX file (Appendix B). Of course there are many advanced features available in LaTeX that are available which you can learn about as you search the Internet and/or discuss LaTeX with your colleagues. However, our goal is to be able to collaborate with others. We cannot assume that our colleagues know these advanced features or are even interested in learning how to accomplish these tasks. 2 A text editor is an editor which does not add any hidden format commands to the document. In other words, what you see is what you get. In Microsoft environments, the text editors are Notepad and Wordpad; in LINUX two commonly used text editors are vi and emacs. 2
use them. Thus, in our experience, collaboration is most successful when lines of communication are kept as simple as possible. Most people learn LaTeX by doing it, i.e. their first experience is usually the result of having to prepare their own paper because the journal publisher has asked for it. This is in fact how you will learn to use LaTeX. Your first assignment will be to reproduce two pages from a bio-mathematics book (see section labeled deliverable at end of the laboratory description). Of course it is necessary to know the basic structure of the LaTeX file: the various commands that you need come from looking them up as you need them. This is why the Internet is so useful. Indeed we had to look up a number of commands that we had never used before in order to make up these notes! In this way we know them now! Background: The main components of a LaTeX file are: 1) Preamble (Top matter), 2) Main body, 3) Math modes, 4) Figures and Tables, and 5) Bibliography. An introduction to math modes is desribed in Appendix B which is available on the website. The use of the basic commands are illustrated in today s lab. We will discuss how figures are introduced into a document in Lab 3. We do not need to know how to construct Tables or a bibliography for our purposes; however, these issues are well documented on the Internet. Here we discuss the basic format of a LaTeX file. Preamble: The first line in the LaTeX program has the form \documentclass[12pt]{article} The term 12pt means twelve points and sets the size of the print (This document has been printed using 12pt.). Points are the units that type-setters use to define the size of characters on the printed page of, for example, a newspaper page. If you want smaller print you could use, for example, 10pt, or bigger, 14pt, and so on. The term article refers to the style that the paper will be prepared. Another style which is often used is book. Other styles are possible. The preamble, or top matter, is everything from this line to the line \begin{document} A typical preamble for passing in assignments to this course is \usepackage{graphicx,times} \title{bio-133: Assignment number xxx} \author{your Name\\ Your College} 3
The preamble tells the program what fonts and style to use, the title and author of the article, and whether additional packages of commands need to be accessed in order to produce the article. The preamble can be quite long since it is possible to define new latex commands and environments. Additional packages are entered by \usepackage. Here we added the package graphicx and times: graphicx is the package that allow you to incorporate either *.eps or *.png into your document (discussed in Lab 3) and times means that the font will be New York Times style. Often journals, such as Nature, have there own packages and require you to declare them in the usepackage statement. These *.sty files, and others, can readily be located and downloaded from the Internet. In fact you could make up your own *.sty file and include it here (minus the extension); however, most people don t do this. Main Body: The main body of LaTeX file is everything that lies between the command \begin{document} and the command \end{document} The basic structure of the main body is \begin{document} \maketitle \section{your section heading here} \subsection{your sub-section heading here} \section*{your section heading here} \subsection*{your section heading here}...... \end{document} The commands \begin{document} and \end{document} are mandatory. The line \maketitle is included only if you made use of the lines \title{} 4
and/or \author{} in the preamble (which you will need to do for your assignments). The lines \section{} and \subsection{} generate, respectively, the appropriate section and sub section numbers, whereas the lines \section*{} and \subsection*{} generate the same headings without the numbers. Browser use: Anything that you would ever want to know about LaTeX can readily be tracked down on the Internet. Thus you will find it useful to have a browser open in a second window of your computer as you prepare your first LaTeX document. Appendix B includes all of the math mode information that you will need for this course. Housekeeping: Perhaps the biggest issue when working with open source tools, such as LaTeX, is dealing with the directory system of the computer. Most present day computer users don t have to worry about directories and paths: just point, click, and drag! However, for computer programmers issues related to directories and paths are very important. We need to make directories to organize our work in a way that makes it easy for us to find things and we need paths so that a computer program can find items that it needs to complete its calculations such as figure files, data files, and where the outputs of the program should be written. Paths always start from the root directory. On a PC the root directory is, by default, the hard disk specified by C, D, E, and so on. When we are in root the prompt on the command window will look like, for example, C:\. If you are a user in a Linux environment, the root directory is your home directory (the system s administrator has access to the root directory). Referring to Figure 1, the root directory can be thought of as the root of a tree from which many branches arise which themselves have branches, and so on. Let us suppose that the root directory contains three sub directories named apple, orange and pear. If we are in root (i.e. on the screen we see C:\>), then we can type dir or ls to obtain <DIR> apple <DIR> orange <DIR> pear The <DIR> do not appear when using Linux. Within the directory apple we have two directories, Ant and Bee, in the directory Orange we have the directories Walk and Run, and so on. What is the path for the directory Ant? The answer is C:\Apple\Ant 5
Figure 1: Example of path structure on a root directory. See text for discussion. Useful commands: These commands assume that either you are using the Command Prompt window on a PC or are working on a Linux terminal (including Mac OSX). cd This means change directory. If we are in the root directory and want to be in the directory Orange we type cd Orange If we are in the directory C:\Pear\Grass and want to go to the directory C:\Apple\Ant we type cd C:\Apple\Ant If you want to move up one directory you can use the command cd... Finally if you want to move back to root you can use cd in Linux and cd C:\ on a PC (in the Command Prompt window). 6
pwd This command means pathway to directory. Another way to think of this command is that it answers the question, Where am I? Thus when you are in any directory, you can obtain the path to that directory by typing pwd at the prompt. mkdir You can create a directory with the command mkdir name rmdir You can remove a directory with the command rmdir name cp (copy) or mv (move) It is possible to move or copy files using the commands mv and cp (on PCs, respectively, move and copy. The move commands can be used to rename a file, e.g. mv test.dat test_new.dat What is the command to move a file named test.dat located in the directory Grass to the directory Bee. The command depends on whether you are currently in Grass or somewhere else. If in Grass the command is mv test.dat C:\Apple\Bee\. or, in Linux, mv test.dat \Apple\Bee\. The. means that the moved file is to have the same name in the new directory. Of course you could move and changed the file name with one command, namely, mv test.dat \Apple\Bee\new_name.dat If we are not in the directory Grass we can still move the file by using the command mv \Grass\test.dat \Apple\Bee\. It is important to organize our computer directories carefully so that you can easily find things in the future. In your home directory make a directory called mtex which will contain your LaTeX documents (see below). It is useful to make sub directories, each of which corresponds to one of the labs. For example, the 7
document prepared for today s lab would be called Lab1 and so on. The path to this sub directory from the home directory is /mtex/lab1. Questions to answer: You will be provided with 1.5-2 pages from a mathematical biology textbook to reproduce. The LaTeXed article must be more than 1 page long in order to complete the exercise described in Lab 3. So let us know if it isn t. Each of you will have a different 1-2 pages to use to prepare your document. Deliverable: Your LaTeX document must be completed before we do Lab 3. You will use your *.tex file to complete the exercise described in Lab 3 and then submit a *.pdf at that time. 8