در این فصل چه یاد میگیری#
شش فصل عدد ساختیم. حالا باید به دستِ کسی برسانیمشان که وقتش کم است، SQL بلد نیست، و باید تا آخرِ هفته تصمیم بگیرد.
بیشترِ گزارشها اینجا میمیرند. نه به این دلیل که عددهایشان غلط است — به این دلیل که شش عددِ درست کنارِ هم میگذارند و هیچکدام نمیگوید چه کاری باید بشود. خواننده جدول را نگاه میکند، سری تکان میدهد، و همان کارِ همیشگی را میکند.
این فصل همان دو جدولِ فصلِ ۴ را به یک صفحه تبدیل میکند که پیامش یک جمله است: نسیم در نرخِ خام ۷۲٫۰ و مرکزی ۶۲٫۳ درصد است؛ بعد از تعدیل، مرکزی ۷۱٫۸ و نسیم ۶۳٫۲ — ولی دستههای کتاب از ۵۰٫۹ تا ۸۷٫۵ درصد پخشاند و همین از هر دو مهمتر است.

آخر این فصل میتوانی:
- گزارشت را دورِ یک پیامِ اصلی ببندی، نه دورِ هر چیزی که حساب کردهای
- بگویی کجا جدول لازم است و کجا نمودار، و چرا هر دو با هم معمولاً اشتباه است
- روی هر عدد سه برچسبِ اجباری بگذاری: واحد، دوره، دانهبندی
- محدودیتها را طوری بنویسی که گزارشت را قویتر کنند، نه ضعیفتر
قبل از شروع#
از فصلِ ۴: نرخِ خام و نرخِ تعدیلشده و گروهِ مرجع. از فصلِ ۳: آنچه از قلم میافتد. از فصلِ ۶: «چه چیزی نظرم را عوض میکند».
دوره و تاریخِ برش در این فصل ثابتاند و همهجا تکرار میشوند: دوره از 2024-01-01 تا 2025-04-01، و تاریخِ برشِ داده AS_OF. این تکرار عمدی است و بخشِ ۴ میگوید چرا.
📓 نوتبوک: نوتبوک این فصل را در Colab باز کن — همهٔ کدهای این فصل آماده و بهترتیب داخلش هست.
| جدول | تعدادِ سطر | زمانِ ساخت |
|---|---|---|
members |
۱٬۴۰۰ | آنی |
titles |
۱٬۲۰۰ | آنی |
loans |
۱۶٬۸۳۴ | کمتر از دو ثانیه |
visits |
۲۵٬۰۱۴ | کمتر از دو ثانیه |
۱. شش عددِ درست که هیچ گزارشی نیستند#
این چیزی است که معمولاً تحویل داده میشود. هر شش عدد درستاند و با یک پرسشِ سالم درآمدهاند:
WINDOW_END = "2025-04-01"
print("اعضای ثبتشده :", int(q("SELECT COUNT(*) AS n FROM members").iloc[0, 0]))
print("امانتها :", int(q("SELECT COUNT(*) AS n FROM loans").iloc[0, 0]))
print("بازدیدها :", int(q("SELECT COUNT(*) AS n FROM visits").iloc[0, 0]))
print("میانگین صفحه :", round(float(q("SELECT AVG(pages) AS p FROM titles").iloc[0, 0]), 1))
print("عناوین :", int(q("SELECT COUNT(*) AS n FROM titles").iloc[0, 0]))
print("نرخ بازگشت بهموقع :",
round(float(q("""
SELECT 100.0 * SUM(returned_at <= due_at) / COUNT(*) AS p
FROM loans WHERE returned_at IS NOT NULL AND borrowed_at < ?
""", (WINDOW_END,)).iloc[0, 0]), 1))
اعضای ثبتشده : 1400
امانتها : 16834
بازدیدها : 25014
میانگین صفحه : 496.2
عناوین : 1200
نرخ بازگشت بهموقع : 66.9
شش عددِ درست، و هیچکدام نمیگوید فردا چه کار کنیم.
آزمونِ فصلِ ۶ را رویشان بزن: برای هر مقدارِ دیگری از «میانگین صفحه» چه کارِ متفاوتی میکردی؟ هیچ. پس آن عدد در گزارش جا ندارد — نه به این دلیل که غلط است، به این دلیل که خرجی ندارد.
۲. یک پیامِ اصلی#
گزارشِ خوب یک جمله دارد که همهچیزِ دیگرش پشتیبانی از همان جمله است. جملهٔ ما از فصلِ ۴ میآید:
branch = q("""
WITH cell AS (
SELECT l.branch_id, t.category, COUNT(*) AS n,
SUM(l.returned_at <= l.due_at) AS on_time
FROM loans AS l
JOIN titles AS t ON t.id = l.title_id
WHERE l.returned_at IS NOT NULL AND l.borrowed_at < ?
GROUP BY l.branch_id, t.category
),
weight AS (SELECT category, SUM(n) AS n FROM cell GROUP BY category),
total AS (SELECT SUM(n) AS n FROM cell)
SELECT b.name AS branch,
SUM(c.n) AS returned_loans,
ROUND(100.0 * SUM(c.on_time) / SUM(c.n), 1) AS raw_pct,
ROUND(SUM(100.0 * c.on_time / c.n * w.n) / (SELECT n FROM total), 1) AS adjusted_pct
FROM cell AS c
JOIN weight AS w ON w.category = c.category
JOIN branches AS b ON b.id = c.branch_id
GROUP BY c.branch_id, b.name
ORDER BY raw_pct DESC
""", (WINDOW_END,))
print(branch)
print()
print("دامنه نرخ خام :", round(branch["raw_pct"].max() - branch["raw_pct"].min(), 1), "واحد")
print("دامنه نرخ تعدیلشده:", round(branch["adjusted_pct"].max() - branch["adjusted_pct"].min(), 1), "واحد")
branch returned_loans raw_pct adjusted_pct
0 نسیم 2796 72.0 63.2
1 بهار 1685 68.1 66.3
2 دانش 2267 67.6 67.3
3 کوشا 2046 67.4 68.9
4 پویا 1726 64.8 60.1
5 مرکزی 3298 62.3 71.8
دامنه نرخ خام : 9.7 واحد
دامنه نرخ تعدیلشده: 11.7 واحد
و یک صداقتِ لازم همینجا: تعدیل دامنه را کوچک نکرد، بزرگترش کرد — از ۹٫۷ به ۱۱٫۷ واحد. پس نمیشود نوشت «بعد از تعدیل معلوم شد شعبهها شبیهِ هماند». چیزی که تعدیل عوض کرد ترتیب بود، نه اندازهٔ اختلاف.
پیامِ اصلی باید همان چیزی باشد که داده میگوید، نه چیزی که دوست داشتیم بگوید:
رتبهبندیِ شعبهها به ترکیبِ کتابهایشان بند است، و خودِ آن ترکیب اثری بزرگتر از هر تفاوتِ شعبهای دارد.
بخشِ بعد نیمهٔ دومِ همین جمله را نشان میدهد.
۳. جدول یا نمودار؟#
قاعدهاش دو خط است: جدول وقتی که خواننده باید عددِ دقیق را بردارد و جایی ببرد؛ نمودار وقتی که باید یک شکل یا یک ترتیب را در یک نگاه ببیند.
جدولِ بخشِ ۲ جدول ماند، چون شش عددش هرکدام باید دقیق خوانده شوند. ولی این یکی شکل است، نه عدد:
category = q("""
SELECT t.category,
COUNT(*) AS returned_loans,
ROUND(100.0 * SUM(l.returned_at <= l.due_at) / COUNT(*), 1) AS on_time_pct
FROM loans AS l
JOIN titles AS t ON t.id = l.title_id
WHERE l.returned_at IS NOT NULL AND l.borrowed_at < ?
GROUP BY t.category
ORDER BY on_time_pct
""", (WINDOW_END,))
def bar(value, top=100.0, width=30):
"""یک میله متنی — تا خروجی روی هر ماشینی دقیقا همان باشد."""
filled = int(round(width * value / top))
return "#" * filled + "." * (width - filled)
category["shape"] = category["on_time_pct"].apply(bar)
print(category.to_string(index=False))
category returned_loans on_time_pct shape
تاریخ 2047 50.9 ###############...............
فلسفه 1673 52.1 ################..............
هنر 899 57.0 #################.............
زندگینامه 1100 59.6 ##################............
علم 1706 63.1 ###################...........
شعر 1174 71.2 #####################.........
رمان 2651 75.6 #######################.......
کودک 2568 87.5 ##########################....
۵۰٫۹ تا ۸۷٫۵ — سیوشش و ششدهم واحد اختلاف، در برابرِ ۹٫۷ واحدِ شعبهها.
میلهها را با کاراکتر کشیدیم تا خروجی روی هر ماشینی دقیقاً همین باشد؛ در کارِ واقعی همین جدول را به ابزارِ نموداری میدهی. نکتهٔ درس شکلِ میله نیست، این است که ستونِ returned_loans کنارِ آن مانده — یک میلهٔ بلند که پشتش ۸۹۹ سطر است با میلهای که پشتش ۲٬۶۵۱ سطر است یکی نیست، و نمودارِ بدونِ تعداد دقیقاً همین را پنهان میکند.
۴. هر عدد سه برچسب دارد#
هیچ عددی تنها فرستاده نمیشود. سه برچسب اجباریاند: واحد، دوره، و دانهبندی.
🔧 اگر کار نکرد: وقتی دوره را صریح میکنی، معمولاً یک پارامترِ دوم به پرسش اضافه میشود و همانجاست که این خطا میآید:
try:
q("""
SELECT COUNT(*) AS n FROM loans
WHERE borrowed_at >= ? AND borrowed_at < ?
""", (WINDOW_END,))
except Exception as error:
print(type(error).__module__ + "." + type(error).__name__)
print(error)
pandas.errors.DatabaseError
Execution failed on sql '
SELECT COUNT(*) AS n FROM loans
WHERE borrowed_at >= ? AND borrowed_at < ?
': Incorrect number of bindings supplied. The current statement uses 2, and there are 1 supplied.
پیام دقیقاً میگوید چند تا لازم بود و چند تا دادی. حالا با هر دو کران، و با سه برچسب بالای جدول:
labelled = q("""
SELECT b.name AS branch,
COUNT(*) AS returned_loans_in_window,
ROUND(100.0 * SUM(l.returned_at <= l.due_at) / COUNT(*), 1) AS on_time_pct
FROM loans AS l
JOIN branches AS b ON b.id = l.branch_id
WHERE l.returned_at IS NOT NULL AND l.borrowed_at >= ? AND l.borrowed_at < ?
GROUP BY b.id, b.name
ORDER BY on_time_pct DESC
""", ("2024-01-01", WINDOW_END))
print("سنجه : نرخ بازگشت بهموقع (درصد)")
print("دانهبندی: یک سطر = یک شعبه؛ هر درصد روی امانتهای برگشته حساب شده")
print("دوره : 2024-01-01 تا", WINDOW_END, "| تاریخ برش داده:", AS_OF)
print()
print(labelled)
سنجه : نرخ بازگشت بهموقع (درصد)
دانهبندی: یک سطر = یک شعبه؛ هر درصد روی امانتهای برگشته حساب شده
دوره : 2024-01-01 تا 2025-04-01 | تاریخ برش داده: 2025-06-12
branch returned_loans_in_window on_time_pct
0 نسیم 2796 72.0
1 بهار 1685 68.1
2 دانش 2267 67.6
3 کوشا 2046 67.4
4 پویا 1726 64.8
5 مرکزی 3298 62.3
سه خطِ بالای جدول همانقدر بخشِ گزارشاند که خودِ عددها. بدونِ آنها همین جدول شش ماهِ دیگر — وقتی کسی فایل را دوباره باز میکند — قابلِ استفاده نیست، چون معلوم نیست دربارهٔ کدام دوره و کدام سطرها حرف میزند.
و نامِ ستون هم عوض شد: returned_loans_in_window بهجای loans. اسمی که خودش دوره را حمل میکند، بعداً کسی را گمراه نمیکند — درسِ فصلِ ۱، این بار از سمتِ نویسنده.
۵. گفتنِ آنچه نمیدانیم#
unknown = q("""
SELECT (SELECT COUNT(*) FROM loans WHERE returned_at IS NULL) AS still_out,
(SELECT COUNT(*) FROM visits WHERE member_id IS NULL) AS anonymous_visits,
(SELECT COUNT(*) FROM members WHERE home_branch_id IS NULL) AS members_without_branch,
(SELECT COUNT(*) FROM loans WHERE borrowed_at >= ?) AS loans_after_window
""", (WINDOW_END,))
print(unknown.T)
0
still_out 1332
anonymous_visits 7070
members_without_branch 101
loans_after_window 2535
چهار عدد که هیچکدام «نتیجه» نیستند و هر چهارتا باید در گزارش بیایند.
و اینجا همان جایی است که بیشترِ آدمها اشتباه میکنند: فکر میکنند نوشتنِ محدودیتها گزارش را ضعیف نشان میدهد. عکسش درست است. گزارشی که میگوید «۱٬۳۳۲ امانت هنوز برنگشته و در هیچ نرخی نیست» دقیقاً همان چیزی را جواب داده که اولین آدمِ باهوشِ اتاق قرار بود بپرسد. گزارشی که نگفته، سرِ همان سؤال از دست میرود.
قاعدهٔ عملی: هر عددی که در فصلِ ۳ از قلم افتاد، در گزارش یک سطر دارد.
۶. یک صفحه، تمام#
حالا همهچیز کنارِ هم. توجه کن که هیچ عددی در متنِ زیر تایپ نشده — همهشان از همان متغیرهایی میآیند که بالا حساب شدند، و همین جلوی رایجترین خطای گزارشنویسی را میگیرد: متنی که با جدولِ کنارش نمیخواند چون یکی بهروز شده و دیگری نه.
top = branch.sort_values("adjusted_pct", ascending=False).iloc[0]
bottom_raw = branch.sort_values("raw_pct").iloc[0]
lines = [
"گزارش: بازگشت بهموقع کتاب — دوره 2024-01-01 تا " + WINDOW_END,
"تاریخ برش داده: " + AS_OF,
"",
"پیام اصلی: رتبه خام شعبهها به ترکیب کتابشان بند است و اثر دسته از هر اختلاف شعبهای بزرگتر است.",
"",
"۱. نرخ خام بین %.1f و %.1f درصد است (دامنه %.1f واحد)." %
(branch["raw_pct"].min(), branch["raw_pct"].max(),
branch["raw_pct"].max() - branch["raw_pct"].min()),
"۲. بعد از تعدیل بر ترکیب دسته، %s از آخر به اول میرود (%.1f به %.1f)." %
(bottom_raw["branch"], bottom_raw["raw_pct"], bottom_raw["adjusted_pct"]),
"۳. خود دسته از %.1f تا %.1f درصد فرق میکند — بزرگتر از هر تفاوت شعبهای." %
(category["on_time_pct"].min(), category["on_time_pct"].max()),
"",
"توصیه: سیاست بر اساس دسته کتاب بسته شود، نه بر اساس رتبه شعبه.",
"",
"آنچه نمیدانیم:",
"- %d امانت هنوز برنگشته و در هیچ نرخی نیست." % int(unknown["still_out"][0]),
"- %d بازدید به هیچ عضوی نچسبیده." % int(unknown["anonymous_visits"][0]),
"- %d عضو شعبه خانگی ندارند؛ امانتشان به شعبه محل امانت نوشته شده." %
int(unknown["members_without_branch"][0]),
"- %d امانت بعد از پایان دوره گرفته شده و عمدا کنار گذاشته شده." %
int(unknown["loans_after_window"][0]),
"",
"چه چیزی نظرمان را عوض میکند: اگر ترکیب دسته در دو شعبه یکسان شود و",
"اختلاف نرخ خام باقی بماند، آنوقت تفاوت واقعا مال شعبه است.",
]
print("\n".join(lines))
گزارش: بازگشت بهموقع کتاب — دوره 2024-01-01 تا 2025-04-01
تاریخ برش داده: 2025-06-12
پیام اصلی: رتبه خام شعبهها به ترکیب کتابشان بند است و اثر دسته از هر اختلاف شعبهای بزرگتر است.
۱. نرخ خام بین 62.3 و 72.0 درصد است (دامنه 9.7 واحد).
۲. بعد از تعدیل بر ترکیب دسته، مرکزی از آخر به اول میرود (62.3 به 71.8).
۳. خود دسته از 50.9 تا 87.5 درصد فرق میکند — بزرگتر از هر تفاوت شعبهای.
توصیه: سیاست بر اساس دسته کتاب بسته شود، نه بر اساس رتبه شعبه.
آنچه نمیدانیم:
- 1332 امانت هنوز برنگشته و در هیچ نرخی نیست.
- 7070 بازدید به هیچ عضوی نچسبیده.
- 101 عضو شعبه خانگی ندارند؛ امانتشان به شعبه محل امانت نوشته شده.
- 2535 امانت بعد از پایان دوره گرفته شده و عمدا کنار گذاشته شده.
چه چیزی نظرمان را عوض میکند: اگر ترکیب دسته در دو شعبه یکسان شود و
اختلاف نرخ خام باقی بماند، آنوقت تفاوت واقعا مال شعبه است.
یک پیام، سه شاهد، یک توصیه، چهار محدودیت، و یک شرطِ ابطال. نوزده خط، و هر خطش خرجی دارد.
✅ چک کن: عددهای متنِ گزارش باید دقیقاً با جدولِ بخشِ ۲ و ۳ بخوانند — ۶۲٫۳ و ۷۲٫۰ و ۷۱٫۸ و ۵۰٫۹ و ۸۷٫۵. اگر یکیشان فرق کرد، جایی عدد را دستی تایپ کردهای، و همین یک عادت رایجترین راهِ خراب شدنِ یک گزارشِ درست است.
📏 اندازه بگیر: یک سطر یعنی چه؟ در جدولِ بخشِ ۲ و ۴ یک سطر یک شعبه است، در بخشِ ۳ یک دستهٔ کتاب، و در هر دو حالت درصدها روی امانتهای برگشته در دورهٔ اعلامشده حساب شدهاند. با کدام شمارشِ دوم سنجیدی؟ با دوتا: ستونِ
returned_loansکه کنارِ هر نرخ مانده تا هیچ درصدی بدونِ مخرجش خوانده نشود، و ستونِraw_pctکه در دو جدولِ مستقلِ بخشِ ۲ و ۴ عیناً یکی درآمد. چه کسی از قلم افتاد؟ همان چهار سطرِ بخشِ ۵ — که این بار در متنِ خودِ گزارش نوشته شدهاند، نه در پاورقی.
🤖 از دستیارت بپرس: «یک گزارشِ تحلیلی چه ساختاری باید داشته باشد تا کسی که وقت ندارد بتواند رویش تصمیم بگیرد؟» بعد این را بپرس: «چرا نوشتنِ محدودیتهای یک تحلیل آن را قویتر میکند و نه ضعیفتر؟» — جوابِ درست میگوید محدودیتِ نوشتهشده جلوی یک نتیجهگیریِ غلط را میگیرد. اگر جواب گفت «برای اینکه صادق بهنظر برسی»، سطحی است: مسئله ظاهر نیست، مسئله این است که خواننده نداند کجا نباید به این عدد تکیه کند.
واژههای تازهٔ این فصل#
| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| headline finding | هدلاین فایندینگ | پیامِ اصلی؛ یک جمله که کلِ گزارش پشتیبانیاش میکند |
| caveat | کویت | محدودیتی که کنارِ عدد نوشته میشود |
| data cut date | دیتا کات دیت | تاریخِ برشِ داده؛ آخرین روزی که داده دارد |
| executive summary | اگزکیوتیو سامری | خلاصهٔ یکصفحهای برای کسی که وقتِ خواندنِ همهاش را ندارد |
تمرینها
اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.
در فصل بعد#
گزارش تحویل شد. سه هفتهٔ بعد کسی همان را دوباره میخواهد، و عدد فرق میکند.
فصلِ بعد نشان میدهد چرا و چطور جلویش را بگیریم — و با همین سنجهٔ اعضای فعال شروع میکند که با سه تاریخِ برشِ متفاوت سه عددِ متفاوت میدهد: ۸۲۹ و ۸۳۳ و ۸۵۱، بدونِ اینکه یک خط از پرسش عوض شده باشد.
به آخر این فصل رسیدی!
اگر ساختی و جواب داد، این دکمه مال توست.