15 - Dictionaries I - the basics.ipynb

Kernel: Python 3 (system-wide)

Dictionaries I - the basics

Dictionaries comprise items of key:value pairs

As we've seen, a list variable allows us to store many values simultaneously in a single variable, for example

cell_types = ['Neutrophil', 'Eosinophil', 'Basophil', 'Small lymphocyte', 'Large lymphocyte', 'Monocyte']

stores six strings in a single list variable called cell_types.

There is another variable type in Python that allows us to store values simultaneously in a single variable: a dictionary.

Dictionaries are a little more complicated than lists though. The best way to think of them is a table with just two columns and as many rows as is needed. Let's revisit the table of average cell diameters of human white blood cells:

Cell type	Diameter ($\mu$m)
Neutrophil	11
Eosinophil	11
Basophil	13.5
Small lymphocyte	7.5
Large lymphocyte	13.5
Monocyte	22.5

This table can be represented as a Python dictionary and assigned to a dictionary variable. Let's call it white_cells:

white_cells = {'Neutrophil'       : 11,
               'Eosinophil'       : 11,
               'Basophil'         : 13.5,
               'Small lymphocyte' : 7.5,
               'Large lymphocyte' : 13.5,
               'Monocyte'         : 22.5
              }

The first thing to notice are the curly brackets { }. Remember, lists have square brackets [] and dictionaries have curly brackets { }.

Each row in the above table is represented in the dictionary. The notation is important. A colon separates each pair of values. And every pair of values is separated by a comma.

Note that we don't need to write each pair on a separate line. This was done for clarity and to show the correspondence between the table and the dictionary. It's perfectly acceptable and normal to write the dictionary on a single line like so:

white_cells = { 'Neutrophil':11, 'Eosinophil':11,  'Basophil':13.5, 'Small lymphocyte':7.5, 'Large lymphocyte':13.5, 'Monocyte':22.5 }

Nor do we need spaces either side of the colon. You can choose whichever format you prefer.

Now for some jargon. The cell types (Neutrophil, Eosinophil, etc.) are called dictionary keys (or keys for short), and their diameters (11, 11, 13.5, etc) are called dictionary values (or values for short). So each item in a dictionary (corresponding to a row in a table) is made up of a key : value pair.

Note we will use the terms "item" and "key:value pair" interchangeably.

The following code shows how to retrieve just the keys or just the values from a dictionary. Run it to see how this works.

# Assign a dictionary of white blood cell type and their average diameters to the variable white_cells.
white_cells = { 'Neutrophil':11, 'Eosinophil':11,  'Basophil':13.5, 'Small lymphocyte':7.5, 'Large lymphocyte':13.5, 'Monocyte':22.5 }

# Print the keys of the dictionary, i.e., the types of white cells, using the "keys()" method.
print( white_cells.keys() )

print() # Print a blank line.

# Print the values of the dictionary, i.e., the diameters of white cells, using the "values()" method.
print( white_cells.values() )

dict_keys(['Neutrophil', 'Eosinophil', 'Basophil', 'Small lymphocyte', 'Large lymphocyte', 'Monocyte'])

dict_values([11, 11, 13.5, 7.5, 13.5, 22.5])

Dictionary keys are unique

There is an important restriction in dictionaries: each key must be unique. In other words, we are not allowed to have the same key appearing more than once in a dictionary. For example we are not allowed to have Neutrophil appearing twice.

This restriction is actually a good thing and makes dictionaries very useful for many tasks.

Run the following code in which the key Neutrophil appears twice but with different values of 11 and 12.

# Assign a dictionary with two identical keys to the variable test_dict.
test_dict = { 'Neutrophil':11, 'Neutrophil':12 }

print( test_dict )

{'Neutrophil': 12}

Notice that the dictionary only contains the key:value pair of the last instance of the key Neutrophil. The first instance of Neutrophil is ignored.

Dictionary values do not need to be unique

Unlike dictionary keys, dictionary values do not need to be unique. Notice in the dictionary white_cells that Neutrophil and Eosinophil both have the same diameter value of 11.

Getting the number of items

The number of items in a dictionary is called its length. And, as for strings and lists, we use the function len() to get a dictionary's length.

# Get the number of items in white_cells and assign it to the numerical variable n
n = len( white_cells )
print(n)

6

Getting the value of a key

A very common thing to do with dictionaries is to get the value of a key:value pair by supplying the key.

For example if you want the diameter of basophil cells you would use the code in the following cell. The value can be assigned to a variable if needed.

# Get the diameter of basophil cells
print( white_cells['Basophil'] )

13.5

Note the notation here. The key Basophil is surrounded by square brackets and immediately follows the name of the dictionary. This does not mean that ['Basophil'] is a list as you might expect. When working with a dictionary the square brackets refer to a key in that dictionary.

KeyError

If we use a key that isn't in the dictionary we get a KeyError.

Try running the following code where we use the key Macrophage which isn't in our dictionary.

# Printing the value of a key not in the dictionary gives a KeyError
print( white_cells['Macrophage'] )

---------------------------------------------------------------------------
KeyError                                  Traceback (most recent call last)
<ipython-input-5-4513c9835af2> in <module>
      1 # Printing the value of a key not in the dictionary gives a KeyError
----> 2 print( white_cells['Macrophage'] )

KeyError: 'Macrophage'

Adding an item

Say we had created our dictionary of white cell diameters but forgotten to include monocytes. We can add this item easily to the dictionary.

Run the following code to see how this is done.

white_cells = { 'Neutrophil':11, 'Eosinophil':11,  'Basophil':13.5, 'Small lymphocyte':7.5, 'Large lymphocyte':13.5 }

# Add the key 'Monocyte' and its value of 22.5 to the white_cells dictionary.
white_cells['Monocyte'] = 22.5

white_cells

{'Neutrophil': 11,
 'Eosinophil': 11,
 'Basophil': 13.5,
 'Small lymphocyte': 7.5,
 'Large lymphocyte': 13.5,
 'Monocyte': 22.5}

Changing the value of an item

The following code demonstrates how to change the value of an item.

# Change the value of 'Monocyte' to 21.2 in the "white_cells" dictionary.
white_cells['Monocyte'] = 21.2

white_cells

{'Neutrophil': 11,
 'Eosinophil': 11,
 'Basophil': 13.5,
 'Small lymphocyte': 7.5,
 'Large lymphocyte': 13.5,
 'Monocyte': 21.2}

Creating an empty dictionary

Sometimes we want to start with an empty dictionary and add items as we go along. We'll see an example of this in a later Notebook.

The following code shows how to initialise an empty dictionary.

# Initialise an empty dictionary to be added to later
an_empty_dict = {}

Testing if a key is already in a dictionary

We might want to test if a key already exists in a dictionary. Depending on the answer you might want to take different actions.

To test if a key already exists in a dictionary we use the in membership operator as we did for strings and lists.

Run the following code to see how this works.

cell_type = 'Leucocyte'

# Test if the value assigned to cell_type is a key in the dictionary white_cells.
if cell_type in white_cells:
    print( f'A {cell_type} is a white blood cell' )

else:
    print( f'{cell_type} is not a white blood cell' )

Leucocyte is not a white blood cell

We assign the string 'Leucocyte' to the string variable cell_type and then test if 'Leucocyte' is a key in the dictionary white_cells. It isn't so we output that a leucocyte is not a white blood cell.

Change Leucocyte to Neutrophil and rerun the code. The output will be that a neutrophil is a white blood cell.

Exercise Notebook

Dictionaries I - the basics

Next Notebook

Dictionaries II - looping