Book Conventions

This handbook uses the following conventions to make learning easier. Please note that many of these conventions are also used in many other books, websites, projects… about programming, so it’s worth spending some time reading and understanding them.

Text format

italics will be used for these cases:

  • Highlight some technical terms
  • Book titles

Sometimes you will see text written in monospace. This refers to something related to code. It can be:

  • a function: i.e. help() (functions always end with ())
  • a file following the pattern script.py, notebook.ipynb or something more generic like *.py (filenames always have a name, a ., and a file extension)
  • a folder, like folder_name/. Folders always have a trailing / and don’t have a . and an extension.
  • a package or library, like Python’s pandas
  • any character or characters that need to be copied.

Placeholder texts

Sometimes, instead of using an exact name that needs to be copied in your script, we will be using a placeholder that may change in certain circumstances but they will always follow a certain structure. Placeholders are always written between <> like this: pd.read_csv(<filename>.py) this means that when you run your code, you will have to replace the placeholder <filename> with the actual name of your file, which may differ from one person to another. After replacing the placeholder, it could be something like this: pd.read_csv(my_fancy_file.csv)

Code blocks

Code blocks represent what you would need to type in your programming language’s terminal or script. You can copy their content and paste it in your IDE to run the code or copy and paste and try to modify it to experiment with it and learn how the code works.

Copying code block’s content

For your ease of use, you can copy the whole content of the code block by hovering over them and clicking on the icon on the top right.

The following is a code block:

# This is a comment in a code block.
import pandas as pd 

url = "https://raw.githubusercontent.com/WarwickCIM/IM939_handbook/main/content/labs/Lab_1/data/office_ratings.csv"

df = pd.read_csv(url)

Some blocks have the resulting code below, exactly as it would appear if we ran it in a terminal using R or Python1.

  • 1 In fact, this whole book has been created using literate programming, which combines text and code. The code displayed in these codeblocks has actually been run when creating the book, in exactly the same way it would have happened in a regular script.

    • # This is a code block with resulting code.
print("This is the output resulting from the code above")
    This is the output resulting from the code above

    Output can be a simple line (like above) or something more complex, like this:

    # We are displaying the first rows (head) of a dataframe.
df.head()
    season episode title imdb_rating total_votes air_date
    0 1 1 Pilot 7.6 3706 2005-03-24
    1 1 2 Diversity Day 8.3 3566 2005-03-29
    2 1 3 Health Care 7.9 2983 2005-04-05
    3 1 4 The Alliance 8.1 2886 2005-04-12
    4 1 5 Basketball 8.4 3179 2005-04-19

    or even interactive figures!

    Figure 1: ?(caption)
    Source: IM939_Lab_6_3-Choropleths.ipynb

    Callouts

    Callouts are texts that outstand from the regular content for some of these reasons:

    Note

    This is a note, used for…

    Pro-Tip

    This is a tip that will make your life easier.

    This is Important

    If you were to remember just some bits of what you’ve been reading, this text should be one of those important bits.

    Warning

    Danger, if you do not pay attention to this, things may not work as expected or not work at all!

    Action needed

    This is prompting you to do something, either answering a question or doing some exercise.

    Additionally, some callouts can be expanded to see their content. This can be either because:

    1. their contents are optional, and they are collapsed by default not to overwhelm you with unnecessary information.

    Although strictly speaking, you might not need to learn this, it will make your life easier.

    1. they give a solution to a question

    This is an answer

    Bibliographical references

    Sometimes you’ll see texts with bliographical references such as: “See Knuth (1984) for additional discussion of literate programming.”

    You can click over the reference to see the full details or visit chapter References