# فصل ۰۷ — گزارشی که کسی می‌خواند

<div dir="rtl">

# فصل ۰۷ — گزارشی که کسی می‌خواند

## در این فصل چه یاد می‌گیری

شش فصل عدد ساختیم. حالا باید به دستِ کسی برسانیمشان که وقتش کم است، `SQL` بلد نیست، و باید تا آخرِ هفته تصمیم بگیرد.

بیشترِ گزارش‌ها اینجا می‌میرند. نه به این دلیل که عددهایشان غلط است — به این دلیل که **شش عددِ درست کنارِ هم می‌گذارند و هیچ‌کدام نمی‌گوید چه کاری باید بشود.** خواننده جدول را نگاه می‌کند، سری تکان می‌دهد، و همان کارِ همیشگی را می‌کند.

این فصل همان دو جدولِ فصلِ ۴ را به یک صفحه تبدیل می‌کند که پیامش یک جمله است: **نسیم در نرخِ خام ۷۲٫۰ و مرکزی ۶۲٫۳ درصد است؛ بعد از تعدیل، مرکزی ۷۱٫۸ و نسیم ۶۳٫۲ — ولی دسته‌های کتاب از ۵۰٫۹ تا ۸۷٫۵ درصد پخش‌اند و همین از هر دو مهم‌تر است.**

![یک شاسیِ حروف‌چینی که فقط یک سطرِ بزرگ در آن بسته شده و کنارش یک سینیِ پر از حروفِ ریزِ چیده‌نشده مانده است](/lesson-assets/t6-s07-reporting/prompt/01-image-one-headline-plate.png)

آخر این فصل می‌توانی:

- گزارشت را دورِ **یک** پیامِ اصلی ببندی، نه دورِ هر چیزی که حساب کرده‌ای
- بگویی کجا جدول لازم است و کجا نمودار، و چرا هر دو با هم معمولاً اشتباه است
- روی هر عدد سه برچسبِ اجباری بگذاری: واحد، دوره، دانه‌بندی
- محدودیت‌ها را طوری بنویسی که گزارشت را قوی‌تر کنند، نه ضعیف‌تر

## قبل از شروع

**از فصلِ ۴:** نرخِ خام و نرخِ تعدیل‌شده و گروهِ مرجع. **از فصلِ ۳:** آنچه از قلم می‌افتد. **از فصلِ ۶:** «چه چیزی نظرم را عوض می‌کند».

**دوره و تاریخِ برش در این فصل ثابت‌اند و همه‌جا تکرار می‌شوند:** دوره از `2024-01-01` تا `2025-04-01`، و تاریخِ برشِ داده `AS_OF`. این تکرار عمدی است و بخشِ ۴ می‌گوید چرا.

> 📓 **نوت‌بوک:** [نوت‌بوک این فصل را در Colab باز کن](/notebooks/avand/term-6-number-to-decision/session-07-reporting.ipynb) — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

</div>

| جدول | تعدادِ سطر | زمانِ ساخت |
|---|---|---|
| `members` | ۱٬۴۰۰ | آنی |
| `titles` | ۱٬۲۰۰ | آنی |
| `loans` | ۱۶٬۸۳۴ | کمتر از دو ثانیه |
| `visits` | ۲۵٬۰۱۴ | کمتر از دو ثانیه |

<div dir="rtl">

## ۱. شش عددِ درست که هیچ گزارشی نیستند

این چیزی است که معمولاً تحویل داده می‌شود. هر شش عدد درست‌اند و با یک پرسشِ سالم درآمده‌اند:

</div>

```python
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))
```

```text
اعضای ثبت‌شده        : 1400
امانت‌ها             : 16834
بازدیدها             : 25014
میانگین صفحه         : 496.2
عناوین               : 1200
نرخ بازگشت به‌موقع    : 66.9
```

<div dir="rtl">

**شش عددِ درست، و هیچ‌کدام نمی‌گوید فردا چه کار کنیم.**

آزمونِ فصلِ ۶ را رویشان بزن: برای هر مقدارِ دیگری از «میانگین صفحه» چه کارِ متفاوتی می‌کردی؟ هیچ. **پس آن عدد در گزارش جا ندارد** — نه به این دلیل که غلط است، به این دلیل که خرجی ندارد.

## ۲. یک پیامِ اصلی

گزارشِ خوب یک جمله دارد که همه‌چیزِ دیگرش پشتیبانی از همان جمله است. جملهٔ ما از فصلِ ۴ می‌آید:

</div>

```python
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), "واحد")
```

```text
  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 واحد
```

<div dir="rtl">

**و یک صداقتِ لازم همین‌جا: تعدیل دامنه را کوچک نکرد، بزرگ‌ترش کرد — از ۹٫۷ به ۱۱٫۷ واحد.** پس نمی‌شود نوشت «بعد از تعدیل معلوم شد شعبه‌ها شبیهِ هم‌اند». چیزی که تعدیل عوض کرد **ترتیب** بود، نه اندازهٔ اختلاف.

پیامِ اصلی باید همان چیزی باشد که داده می‌گوید، نه چیزی که دوست داشتیم بگوید:

> **رتبه‌بندیِ شعبه‌ها به ترکیبِ کتاب‌هایشان بند است، و خودِ آن ترکیب اثری بزرگ‌تر از هر تفاوتِ شعبه‌ای دارد.**

بخشِ بعد نیمهٔ دومِ همین جمله را نشان می‌دهد.

## ۳. جدول یا نمودار؟

قاعده‌اش دو خط است: **جدول وقتی که خواننده باید عددِ دقیق را بردارد و جایی ببرد؛ نمودار وقتی که باید یک شکل یا یک ترتیب را در یک نگاه ببیند.**

جدولِ بخشِ ۲ جدول ماند، چون شش عددش هرکدام باید دقیق خوانده شوند. ولی این یکی شکل است، نه عدد:

</div>

```python
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))
```

```text
  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 ##########################....
```

<div dir="rtl">

**۵۰٫۹ تا ۸۷٫۵ — سی‌وشش و شش‌دهم واحد اختلاف، در برابرِ ۹٫۷ واحدِ شعبه‌ها.**

میله‌ها را با کاراکتر کشیدیم تا خروجی روی هر ماشینی دقیقاً همین باشد؛ در کارِ واقعی همین جدول را به ابزارِ نموداری می‌دهی. **نکتهٔ درس شکلِ میله نیست، این است که ستونِ `returned_loans` کنارِ آن مانده** — یک میلهٔ بلند که پشتش ۸۹۹ سطر است با میله‌ای که پشتش ۲٬۶۵۱ سطر است یکی نیست، و نمودارِ بدونِ تعداد دقیقاً همین را پنهان می‌کند.

## ۴. هر عدد سه برچسب دارد

هیچ عددی تنها فرستاده نمی‌شود. سه برچسب اجباری‌اند: **واحد**، **دوره**، و **دانه‌بندی**.

> 🔧 **اگر کار نکرد:** وقتی دوره را صریح می‌کنی، معمولاً یک پارامترِ دوم به پرسش اضافه می‌شود و همان‌جاست که این خطا می‌آید:

</div>

```python
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)
```

```text
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.
```

<div dir="rtl">

پیام دقیقاً می‌گوید چند تا لازم بود و چند تا دادی. حالا با هر دو کران، و با سه برچسب بالای جدول:

</div>

```python
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)
```

```text
سنجه : نرخ بازگشت به‌موقع (درصد)
دانه‌بندی: یک سطر = یک شعبه؛ هر درصد روی امانت‌های برگشته حساب شده
دوره : 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
```

<div dir="rtl">

**سه خطِ بالای جدول همان‌قدر بخشِ گزارش‌اند که خودِ عددها.** بدونِ آن‌ها همین جدول شش ماهِ دیگر — وقتی کسی فایل را دوباره باز می‌کند — قابلِ استفاده نیست، چون معلوم نیست دربارهٔ کدام دوره و کدام سطرها حرف می‌زند.

و نامِ ستون هم عوض شد: `returned_loans_in_window` به‌جای `loans`. **اسمی که خودش دوره را حمل می‌کند، بعداً کسی را گمراه نمی‌کند** — درسِ فصلِ ۱، این بار از سمتِ نویسنده.

## ۵. گفتنِ آنچه نمی‌دانیم

</div>

```python
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)
```

```text
                           0
still_out               1332
anonymous_visits        7070
members_without_branch   101
loans_after_window      2535
```

<div dir="rtl">

چهار عدد که هیچ‌کدام «نتیجه» نیستند و هر چهارتا باید در گزارش بیایند.

**و اینجا همان جایی است که بیشترِ آدم‌ها اشتباه می‌کنند:** فکر می‌کنند نوشتنِ محدودیت‌ها گزارش را ضعیف نشان می‌دهد. عکسش درست است. گزارشی که می‌گوید «۱٬۳۳۲ امانت هنوز برنگشته و در هیچ نرخی نیست» **دقیقاً همان چیزی را جواب داده که اولین آدمِ باهوشِ اتاق قرار بود بپرسد.** گزارشی که نگفته، سرِ همان سؤال از دست می‌رود.

**قاعدهٔ عملی: هر عددی که در فصلِ ۳ از قلم افتاد، در گزارش یک سطر دارد.**

## ۶. یک صفحه، تمام

حالا همه‌چیز کنارِ هم. توجه کن که هیچ عددی در متنِ زیر تایپ نشده — همه‌شان از همان متغیرهایی می‌آیند که بالا حساب شدند، و همین جلوی رایج‌ترین خطای گزارش‌نویسی را می‌گیرد: **متنی که با جدولِ کنارش نمی‌خواند چون یکی به‌روز شده و دیگری نه.**

</div>

```python
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))
```

```text
گزارش: بازگشت به‌موقع کتاب — دوره 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 امانت بعد از پایان دوره گرفته شده و عمدا کنار گذاشته شده.

چه چیزی نظرمان را عوض می‌کند: اگر ترکیب دسته در دو شعبه یکسان شود و
اختلاف نرخ خام باقی بماند، آن‌وقت تفاوت واقعا مال شعبه است.
```

<div dir="rtl">

**یک پیام، سه شاهد، یک توصیه، چهار محدودیت، و یک شرطِ ابطال.** نوزده خط، و هر خطش خرجی دارد.

> ✅ **چک کن:** عددهای متنِ گزارش باید دقیقاً با جدولِ بخشِ ۲ و ۳ بخوانند — ۶۲٫۳ و ۷۲٫۰ و ۷۱٫۸ و ۵۰٫۹ و ۸۷٫۵. اگر یکی‌شان فرق کرد، جایی عدد را دستی تایپ کرده‌ای، و همین یک عادت رایج‌ترین راهِ خراب شدنِ یک گزارشِ درست است.

> 📏 **اندازه بگیر:** **یک سطر یعنی چه؟** در جدولِ بخشِ ۲ و ۴ یک سطر یک شعبه است، در بخشِ ۳ یک دستهٔ کتاب، و در هر دو حالت درصدها روی امانت‌های **برگشته** در دورهٔ اعلام‌شده حساب شده‌اند. **با کدام شمارشِ دوم سنجیدی؟** با دوتا: ستونِ `returned_loans` که کنارِ هر نرخ مانده تا هیچ درصدی بدونِ مخرجش خوانده نشود، و ستونِ `raw_pct` که در دو جدولِ مستقلِ بخشِ ۲ و ۴ عیناً یکی درآمد. **چه کسی از قلم افتاد؟** همان چهار سطرِ بخشِ ۵ — که این بار در متنِ خودِ گزارش نوشته شده‌اند، نه در پاورقی.

> 🤖 **از دستیارت بپرس:** «یک گزارشِ تحلیلی چه ساختاری باید داشته باشد تا کسی که وقت ندارد بتواند رویش تصمیم بگیرد؟» بعد این را بپرس: **«چرا نوشتنِ محدودیت‌های یک تحلیل آن را قوی‌تر می‌کند و نه ضعیف‌تر؟»** — جوابِ درست می‌گوید محدودیتِ نوشته‌شده جلوی یک نتیجه‌گیریِ غلط را می‌گیرد. اگر جواب گفت «برای اینکه صادق به‌نظر برسی»، سطحی است: مسئله ظاهر نیست، مسئله این است که خواننده نداند کجا نباید به این عدد تکیه کند.

## واژه‌های تازهٔ این فصل

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| headline finding | هدلاین فایندینگ | پیامِ اصلی؛ یک جمله که کلِ گزارش پشتیبانی‌اش می‌کند |
| caveat | کویت | محدودیتی که کنارِ عدد نوشته می‌شود |
| data cut date | دیتا کات دیت | تاریخِ برشِ داده؛ آخرین روزی که داده دارد |
| executive summary | اگزکیوتیو سامری | خلاصهٔ یک‌صفحه‌ای برای کسی که وقتِ خواندنِ همه‌اش را ندارد |

<div dir="rtl">

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا «میانگین صفحه» از گزارش بیرون رفت؟

**تمرینِ اجباری:** همان قالبِ بخشِ ۶ را برای یک پرسشِ دیگر بنویس: «اعضای فعال چند نفرند و روند دارند یا نه؟» **از سنجهٔ فصلِ ۲ استفاده کن و تعریفش را در همان صفحه بیاور.** گزارشت باید یک پیامِ اصلی، دستِ‌کم دو شاهدِ عددی، سه برچسب روی هر جدول، و بخشِ «آنچه نمی‌دانیم» داشته باشد — و **هیچ عددی در متن دستی تایپ نشود.**

**تمرینِ ستاره‌دار ⭐:** گزارشِ بخشِ ۶ را دو بار بنویس: یک بار برای مدیرِ کتابخانه و یک بار برای کارمندِ میزِ امانت. **همان عددها، دو پیامِ اصلیِ متفاوت.** حالا سؤالِ سخت: **آیا این کار صادقانه است؟** جوابت باید بینِ «انتخابِ چیزی که برای این خواننده به کار می‌آید» و «پنهان کردنِ چیزی که به ضررِ نتیجه‌گیریِ من است» خط بکشد، و بگوید کدام بخشِ گزارش در هر دو نسخه باید عیناً یکی بماند.

## در فصل بعد

گزارش تحویل شد. سه هفتهٔ بعد کسی همان را دوباره می‌خواهد، و عدد فرق می‌کند.

فصلِ بعد نشان می‌دهد چرا و چطور جلویش را بگیریم — و با همین سنجهٔ اعضای فعال شروع می‌کند که با سه تاریخِ برشِ متفاوت سه عددِ متفاوت می‌دهد: **۸۲۹ و ۸۳۳ و ۸۵۱**، بدونِ اینکه یک خط از پرسش عوض شده باشد.

</div>

---
Source: https://yaadestan.com/courses/avand/lessons/t6/s07-reporting (یادستان, Yaadestan)
