Reading function documentation:basics

Today I would like to discuss a topic, we’ve been told to practice, I’m bad at, and haven’t been able to find advice for online: reading documentation. Specifically, we’ll be looking at some pandas documentation since that’s what I’ve done the most this past week.

I’d like to start with the first thing you’ll probably see when you open a pandas documentation page:

This is what I like to call the argument line, and if you’re like me this may have caused you a lot of trouble when trying to read through documentation. A lot of my struggles have been opening up some documentation seeing an argument line then getting so caught up in trying to decode it that I just end up frustrated and look for information secondhand.

If this sounds familiar, you’re in luck, because I have one simple piece of advice to help out: ignore this portion till later. While this section does have important information in it, if you are only opening up a piece of documentation for the first time it’ll be difficult to decrypt what it means, especially without the full context and information, which will be provided later. So until that section you’ll probably be better off ignoring the argument line.

The one piece of information I would recommend looking at to start out with is the portion preceding the functions name. This will tell you what kind of object you need in order to call the function in the first place, and generally won’t be laid out more clearly than in the argument line. In the case of out example, you would need to use a Series object in order to call the value_counts() function.

The second part of the documentation probably looks something like this:

And is where I think you should really start when looking at documentation. This section is the general description of what the function actually does and is usually pretty clear about it. The two pieces I find myself most looking for in documentation is usually found here, specifically the data type of the returned object, in this case a series, and what object might be required to be passed into the function. Notably the Series.Value_counts() function we’ve been observing does not have a required input, but you’ll usually want to be on the watch for the that.

I would also like to mention that if you’re having trouble understanding what the function does from this description due to technical language, to keep in mind that a lot of the time the function is named descriptively, so referring back to the name might help you understand what’s actually going on. Since the name won’t use such technical language, the simplicity can help clarify what it all means.

Moving on: remember how I mentioned wanting to skip over the first section since it’s difficult to understand, the third section is where it comes back.

This Parameters section exists purely to explain what all that incomprehensible text at the start actually means and how to use it. A lot of these arguments will make minor modifications to how the function normally works, and I’d recommend reading over them carefully in case one will be useful for you case. For example, knowing how to switch from sorting in ascending and descending order has definitely come in handy. You may want to make special note of these arguments accepted data types as well as their default values, since often you might not even need to include them in your own function call.

The final portion of the documentation will usually provide the reader with some simple examples. I would like to note that a lot of the time these examples are almost overly simple, such as by working with a single series, rather than a full data frame. As a result, the actual utility of these examples can be limited if your running into trouble with your function. However, it does demonstrate what this code might look like in action, so a preliminary look can help you check that you’ve properly digested the information

So to review:

1 quickly glance over the argument, noting the data type used to call the function

2. read over the description paragraphs, taking careful note of the datatype of the functions output and required inputs.

3. look over the Parameters taking note of default values, and the accepted datatypes for the arguments

4. quickly look at the example section to confirm how the syntax should look it context

5. return to the argument line, to help while formatting your own function call.