pandas · Chapter 1 of 22
Why pandas, and your first DataFrame
By the end of this chapter you can say why Kargha moves its sales from a spreadsheet to pandas, make a Series and a DataFrame from Python data, say what a column and the index are, read a CSV file with pd.read_csv, take a first look at any table with head, tail, shape, len and dtypes, and pick one column (a Series) or several (a DataFrame). Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: Tables from zero
- 4 tasks
- pandas
- Free chapter
Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.
Why you need this
Kargha sells handloom sarees, dupattas, stoles and kurtas woven by 38 weaver families around Varanasi. It sells in three places, and each one sends its orders in its own format: the website a CSV file with one row for every order line, a marketplace an Excel workbook, and the flagship store in Varanasi a JSON file of bills. The courier sends the returns as one more CSV. In October 2025, the Diwali month, the website alone sent 1,559 order lines.
Shabnam, the founder, wants to know every month which designs sell, in which cities and when, so the weavers know what to put on their looms. Harpreet, who runs finance, needs the month's sales to the rupee: weavers are paid from them. Gopal, who runs the warehouse, counts the stock every Sunday and reorders what is running out.
Today all of it goes into one spreadsheet, by hand, and it breaks in quiet ways. In October Harpreet copied the total's formula from the month before; it still added up rows 2 to 1,201, so the sheet said ₹76.97 lakh while the 1,559 lines came to ₹1.02 crore. In September Gopal sorted the on_hand column of his stock sheet to see what was running out, and sorted only that column: every sku got another sku's count, and three sarees were reordered that were sitting on the shelf. Nothing warned either of them.
Plain Python does not fix this. Read the catalogue with Python's csv module and every value is text, and nothing holds a row together:
import csv
with open("/workspace/data/products.csv", encoding="utf-8") as f:
rows = list(csv.DictReader(f))
print(len(rows))
skus = [r["sku"] for r in rows]
mrps = [r["mrp_rs"] for r in rows]
print(skus[:3], mrps[:3])
print(sorted(mrps)[:4])
120
['KG-SAR-001', 'KG-SAR-002', 'KG-SAR-003'] ['16900', '32800', '10000']
['10000', '10100', '10200', '10400']
The prices are strings, so they sort like words: "10000" comes first, though the cheapest product costs ₹649. And once the prices are a list of their own, sorting it is Gopal's mistake again: nothing ties a price to its sku any more. Devika, Kargha's staff data scientist, is moving all of it to pandas, Python's library for tables, built on NumPy. You do it with her. You know Python and NumPy's arrays; this lab starts from there.
The lesson
A table that keeps its rows together
Here is the same catalogue in pandas, sorted by price. Every piece of this is in this chapter except sorting, which is chapter 11:
import pandas as pd
catalogue = pd.read_csv("/workspace/data/products.csv")
cheapest = catalogue.sort_values("mrp_rs")
print(cheapest[["sku", "category", "mrp_rs"]].head(4))
sku category mrp_rs
91 KG-STL-010 stole 649
82 KG-STL-001 stole 699
88 KG-STL-007 stole 749
85 KG-STL-004 stole 849
The prices are numbers, so ₹649 comes first. Each row moved as a whole: KG-STL-010 still has its own price, and its label, 91, came with it. That label is how pandas knows a row wherever it goes.
A Series: one column with labels
A Series is one column: values of one dtype, like a NumPy array, and a label for each value. Made from a list, the labels are 0, 1, 2 and so on:
import pandas as pd
counts = pd.Series([14, 3, 22, 0])
print(counts)
0 14
1 3
2 22
3 0
dtype: int64
The left column is the labels, the right one the values, and the last line their dtype. Give it your own labels with index= and a name with name=:
on_hand = pd.Series(
[14, 3, 22, 0],
index=["KG-DUP-004", "KG-SAR-019", "KG-STL-002", "KG-KUR-011"],
name="on_hand",
)
print(on_hand)
print(on_hand["KG-SAR-019"])
print(on_hand.index)
print(on_hand.values)
KG-DUP-004 14
KG-SAR-019 3
KG-STL-002 22
KG-KUR-011 0
Name: on_hand, dtype: int64
3
Index(['KG-DUP-004', 'KG-SAR-019', 'KG-STL-002', 'KG-KUR-011'], dtype='str')
[14 3 22 0]
- The index holds the labels, and
on_hand["KG-SAR-019"]looks a value up by its label, like a dict. .valuesis the NumPy array underneath (no commas: an array).- Arithmetic works on every value at once, as with arrays:
on_hand * 2is a new Series of 28, 6, 44 and 0 with the same labels.
A dict works too: pd.Series takes its keys as the labels and its values as the values, in the dict's order.
A DataFrame: columns that share one index
A DataFrame is a table: columns side by side, each one a Series, all sharing one index. The plainest way to make one is a dict of lists, one list per column:
week = pd.DataFrame({
"sku": ["KG-DUP-004", "KG-SAR-019", "KG-STL-002"],
"sold": [6, 2, 9],
"mrp_rs": [1899, 21500, 1099],
"on_sale": [False, True, False],
})
print(week)
print(week.dtypes)
print(week.columns)
print(week.index)
sku sold mrp_rs on_sale
0 KG-DUP-004 6 1899 False
1 KG-SAR-019 2 21500 True
2 KG-STL-002 9 1099 False
sku str
sold int64
mrp_rs int64
on_sale bool
dtype: object
Index(['sku', 'sold', 'mrp_rs', 'on_sale'], dtype='str')
RangeIndex(start=0, stop=3, step=1)
- Each key is a column name, each list its values, in the dict's order.
columnsholds the names. - One dtype per column, not one for the whole table as in a NumPy array:
stris pandas' type for text, thenint64andbool. That is why a table of text and numbers can still do sums. - The rows got the labels 0, 1, 2 on their own: a RangeIndex, which stores only its start, stop and step.
Every column must be as long as the others, because a row is one value from each:
ValueError: All arrays must be of the same length
Two columns of the same table line up row by row, so week["sold"] * week["mrp_rs"] is each row's takings: 11394, 43000 and 9891, labelled 0, 1 and 2.
Reading a CSV file
Nobody types a catalogue in. pd.read_csv reads a CSV file into a DataFrame:
catalogue = pd.read_csv("/workspace/data/products.csv")
print(type(catalogue))
print(catalogue.shape)
print(len(catalogue))
print(list(catalogue.columns))
print(catalogue.index)
<class 'pandas.DataFrame'>
(120, 8)
120
['sku', 'name', 'category', 'fabric', 'weaver_id', 'cost_rs', 'mrp_rs', 'launched']
RangeIndex(start=0, stop=120, step=1)
What read_csv does, in order: it reads the first line as the column names, splits every other line at its commas, looks at each column's values to choose its dtype, and gives the rows a RangeIndex. A name like "Katan silk saree, kadwa, rani pink" has commas inside it, so the file puts it in double quotes, and read_csv keeps it as one value:
$ head -2 /workspace/data/products.csv
sku,name,category,fabric,weaver_id,cost_rs,mrp_rs,launched
KG-SAR-001,"Katan silk saree, kadwa, rani pink",saree,Katan silk,W22,8980,16900,2026-03-25
shapeis a tuple of the rows and the columns,(120, 8); it is an attribute, so no brackets.len(catalogue)is just the number of rows.list(catalogue.columns)turns the names into a plain list.
A first look: head, tail and dtypes
A table of 120 rows is too long to print whole. head(n) gives the first n rows (5 if you give no number) and tail(n) the last:
print(catalogue.head(3))
print(catalogue.tail(2))
print(catalogue.dtypes)
sku name ... mrp_rs launched
0 KG-SAR-001 Katan silk saree, kadwa, rani pink ... 16900 2026-03-25
1 KG-SAR-002 Kadhua silk saree, kadwa, black ... 32800 2023-09-15
2 KG-SAR-003 Georgette saree, jaal, gold ... 10000 2024-04-06
[3 rows x 8 columns]
sku name ... mrp_rs launched
118 KG-KUR-019 Cotton kurta, butti, red ... 1499 2023-12-23
119 KG-KUR-020 Silk kurta, pintuck, mustard ... 3549 2024-09-13
[2 rows x 8 columns]
sku str
name str
category str
fabric str
weaver_id str
cost_rs int64
mrp_rs int64
launched str
dtype: object
- head and tail are methods, so they have brackets, and they return a new, smaller DataFrame; the rows keep their own labels (118 and 119).
- The
...is pandas fitting the table to the screen's width: the middle columns are hidden, not lost. A wider terminal shows more. dtypesis a Series: one dtype for each column, labelled by the column's name. The prices areint64, ready for maths.launchedis still text: dates are chapter 18.
Look at a new file this way before trusting it: its shape, its columns, its dtypes and a few rows.
One column or several
Square brackets with one column name give that column, a Series. A list of names gives a DataFrame of those columns, in the list's order:
mrp = catalogue["mrp_rs"]
print(type(mrp))
print(mrp.head(3))
pair = catalogue[["name", "category"]]
print(type(pair))
print(pair.head(3))
<class 'pandas.Series'>
0 16900
1 32800
2 10000
Name: mrp_rs, dtype: int64
<class 'pandas.DataFrame'>
name category
0 Katan silk saree, kadwa, rani pink saree
1 Kadhua silk saree, kadwa, black saree
2 Georgette saree, jaal, gold saree
The outer brackets select; the inner ones make the list. A Series takes its column's name as its own (Name: mrp_rs) and keeps the table's row labels. A DataFrame has columns, a shape of two numbers and the methods of a table; a Series has values, a shape of one number and no columns.
Two mistakes you will make. A name that is not a column:
KeyError: 'price'
And two names without the inner brackets, which pandas reads as one name, the tuple ('sku', 'mrp_rs'):
KeyError: ('sku', 'mrp_rs')
Both are the last line of a long traceback; read the last line first.
Columns of one table line up by row, so the margin on every product is one subtraction: catalogue["mrp_rs"] - catalogue["cost_rs"] is a Series that starts 7920, 16600 and 4590.
Your turn
Four tasks, one file each. Task 1 reads the weavers' CSV and prints its shape, its columns and its first three rows; the Check runs it on other files too, so print what the DataFrame says. Task 2 builds Gopal's stock count as a Series, labelled by sku and named, and as a DataFrame with its columns in order. Task 3 writes Devika's three first looks at any table. Task 4 is an interview question: Harpreet's mrp_table returns a Series where her report needs a DataFrame, and Devika will ask what one bracket and two brackets each give. Run a file with python3 weavers.py, or try functions in ipython first: from first_look import first_rows.
What you build: 4 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
weavers.py: the weavers at a glance
The starter keeps the file's path in the line path = "/workspace/data/weavers.csv". Keep that line as it is. Read the CSV file at path into a DataFrame, then print its shape after shape: and a space, its column names as a Python list after columns: and a space, and then its first three rows the way pandas prints a DataFrame. For weavers.csv the first two lines are exactly:
shape: (39, 5)
columns: ['weaver_id', 'name', 'village', 'looms', 'joined']
and the next four lines are the header of column names and the rows labelled 0, 1 and 2, as printing the first three rows shows them.
The Check also runs the file with the path line changed to one of Gopal's stock counts (/opt/track/data/stock/stock_2026-09-06.csv, 3 columns) and to a small CSV file of 2 rows. Then the shape, the columns and the rows are different (a file of 2 rows prints only 2), so print what the DataFrame says, never typed-in text.
- Task 2
stock.py: Gopal's count as a Series and a DataFrame
Write two functions in stock.py.
stock_series(counts) is given a dict whose keys are skus and whose values are how many pieces are on the shelf, for example {"KG-SAR-007": 4, "KG-DUP-011": 0}. It returns a pandas Series named on_hand, whose labels (its index) are the skus in the dict's order and whose values are the counts, as whole numbers. The Check tries a dict of 4 skus and a dict of 1.
stock_table(skus, counts, counted_by) is given three lists of the same length: the skus, the counts and who counted each one. It returns a pandas DataFrame with exactly three columns in this order, sku, on_hand and counted_by, one row for each sku in the lists' order, labelled 0, 1, 2 and so on (pandas' default labels). The Check tries lists of 4 and lists of 1.
- Task 3
first_look.py: a first look at any table
Write three functions in first_look.py, each given a DataFrame called table, which they must not change.
first_rows(table, n) returns a DataFrame of the table's first n rows, with every column and the rows' own labels. The Check tries the catalogue (products.csv) with 5, the weavers with 2 and the courier's returns with 1.
column_types(table) returns a Series with each column's dtype, labelled by the column names in the table's order: for the weavers, weaver_id is str and looms is int64.
count_rows(table) returns the number of rows as one whole number (an int), not the shape: 120 for the catalogue. The Check also tries a table with no rows, which has 0.
- Task 4 · interview question
Interview: mrp_table.py, one bracket or two
Harpreet's price report needs a DataFrame of one column, the catalogue's mrp_rs, because it reads the table's columns and shape. Her mrp_table(catalogue) returns something else, and the report stops with AttributeError: 'Series' object has no attribute 'columns'. Fix it so it returns a DataFrame with exactly one column, mrp_rs, with the catalogue's own row labels: for products.csv, a DataFrame of shape (120, 1). The Check also calls it with a small catalogue of 3 rows labelled by sku, whose columns are name and mrp_rs.
Devika will ask: what is the difference between catalogue["mrp_rs"] and catalogue[["mrp_rs"]], and when do you want each?
What you will learn
- Why pandas: a table whose rows stay together and whose columns each have one type.
- Series: one column of values with a label for each.
- DataFrame: columns side by side that share one set of row labels, the index.
- pd.read_csv: a CSV file into a DataFrame.
- A first look: head, tail, shape, len, columns and dtypes.
- Selecting columns: one name gives a Series, a list of names a DataFrame.
More in Tables from zero
Build "Why pandas, and your first DataFrame" yourself
Kargha, a Varanasi handloom brand, sells through a website, a marketplace and a store. You make one true picture of its sales. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.
Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.