Podręcznik uczestnika z objaśnieniami, przykładami i ćwiczeniami do samodzielnej nauki
3. Od notebooka eksploracyjnego do finalnego
Redakcja notebooka jest pracą nad tokiem rozumowania, a nie tylko nad wyglądem. Zachowaj kopię roboczą i utwórz notebooks/M6_raport_redakcja.ipynb. Dopiero po kontroli zapisz wersję notebooks/M6_raport_finalny.ipynb. Nie nadpisuj jedynego egzemplarza analizy, w którym pozostają uzasadnienia wcześniejszych decyzji.
Najpierw przejrzyj przynajmniej dziesięć komórek. Każdej przypisz funkcję, związek z pytaniem raportu, decyzję redakcyjną i miejsce docelowe. Poniższa mapa pokazuje sposób myślenia, nie obowiązkowy rozkład komórek.
|
Komórka robocza |
Decyzja |
Miejsce i uzasadnienie |
|---|---|---|
|
Importy rozproszone |
Połącz |
Jedna sekcja konfiguracji na początku. |
|
Kolejny odczyt CSV |
Usuń powtórzenie |
Jeden jawny odczyt przygotowanych danych. |
|
Podgląd 720 wierszy |
Skróć |
Paszport danych i niezbędna próbka. |
|
Kontrola klucza |
Zostaw |
Warunek wiarygodności agregacji. |
|
Bilans braków |
Zostaw |
Uzasadnia różne liczebności wyników. |
|
Próba starego filtra |
Usuń z kopii |
Archiwum robocze; sprawdź, czy nic od niej nie zależy. |
|
Ranking median |
Zostaw |
Wynik odpowiadający pytaniu głównemu. |
|
Trzy wersje słupków |
Wybierz jedną |
Wersja czytelna i zgodna z tabelą. |
|
Diagnostyka korelacji |
Skróć i przenieś |
Wniosek w części głównej, szczegóły w aneksie. |
|
Wpis użycia LLM |
Uporządkuj |
Krótka informacja w raporcie i pełny ślad weryfikacji. |
Po zmianie kolejności komórek usuń zależności od ukrytego stanu pamięci. Zmienna powinna powstawać przed pierwszym użyciem, a filtr powinien być widoczny w kodzie prowadzącym do wyniku. Ogólne nazwy typu df1, wynik2 i test nie pomagają odczytać sensu operacji; używaj nazw takich jak pomiary_clean, ranking_drgan i energia_okres.
Refaktoryzacja może zmieniać organizację kodu, ale nie powinna po cichu zmieniać zbioru, miary, sposobu obsługi braków ani kolejności istotnej dla obliczeń. Porównaj wartości przed i po redakcji. Sam fakt, że wykres nadal się pojawia, nie dowodzi zgodności.
Jedno wejście i jawne ścieżki
W przykładach przyjmujemy, że notebook leży w folderze notebooks, a katalog roboczy kernela jest właśnie tym folderem. Path.cwd() pokazuje katalog roboczy procesu, nie automatycznie położenie pliku notebooka. Jeśli uruchamiasz Jupytera inaczej, sprawdź tę wartość i świadomie ustaw katalog główny projektu.
from pathlib import Path
import hashlib
import pandas as pd
import matplotlib.pyplot as plt
NOTEBOOK_DIR = Path.cwd()
PROJECT_DIR = NOTEBOOK_DIR.parent
PLIK_DANYCH = PROJECT_DIR / "data/processed/pomiary_clean.csv"
TABLES = PROJECT_DIR / "outputs/tables"
FIGURES = PROJECT_DIR / "outputs/figures"
assert PLIK_DANYCH.is_file(), "Sprawdź katalog roboczy i ścieżkę"
TABLES.mkdir(parents=True, exist_ok=True)
FIGURES.mkdir(parents=True, exist_ok=True)
pomiary_clean = pd.read_csv(
PLIK_DANYCH, parse_dates=["czas", "data_instalacji"]
)
suma_sha256 = hashlib.sha256(PLIK_DANYCH.read_bytes()).hexdigest()
print("Źródło:", PLIK_DANYCH)
print("SHA-256:", suma_sha256)
W całym projekcie stosujemy outputs, a nie output. Zgodność nazwy folderu w notebooku, README i instrukcji eksportu jest częścią odtwarzalności. Ścieżki względne względem PROJECT_DIR pozwalają przenieść projekt bez przepisywania nazwy dysku czy konta użytkownika.
SHA-256 identyfikuje zawartość pliku na poziomie bajtów. Zapisz rzeczywisty wynik ze swojego uruchomienia wraz z pochodzeniem danych. Nie przepisuj przykładowego skrótu z prezentacji. Zgodny skrót nie dowodzi poprawności danych, a zmiana sposobu zapisu CSV może go zmienić mimo zachowania tych samych wartości.
Ten notebook zaczyna analizę od przygotowanego pliku. Nie dowodzi samodzielnie, że cały proces od danych surowych jest odtwarzalny. Aby wykazać również ten etap, zachowaj notebook M2, źródła i dokumentację jego decyzji oraz sprawdź kolejność wykonania opisaną w README.
Nie uruchamiaj przykładów eksportu w folderze zawierającym jedyną kopię własnych rezultatów. Zapis pod tą samą nazwą zastępuje wcześniejszy plik wynikowy; wersję potrzebną do porównania zarchiwizuj osobno.
Kontrole przed obliczeniami i po redakcji
Przed budowaniem tabel sprawdź oczekiwany kształt danych, kompletność klucza i liczebność grup. Poniższe oczekiwania dotyczą konkretnego zbioru kursowego. Dla nowego zbioru ustala się je na podstawie źródła, a nie po to, żeby dopasować test do uzyskanego wyniku.
KLUCZ = ["czas", "urzadzenie"]
assert pomiary_clean.shape == (720, 14)
assert pomiary_clean[KLUCZ].notna().all().all()
assert not pomiary_clean.duplicated(KLUCZ).any()
assert pomiary_clean["urzadzenie"].nunique() == 8
assert pomiary_clean.groupby("urzadzenie").size().eq(90).all()
assert pomiary_clean["czas"].min() == pd.Timestamp("2026-01-01 08:00")
assert pomiary_clean["czas"].max() == pd.Timestamp("2026-02-14 20:00")
assert pomiary_clean[["temperatura", "drgania"]].notna().all().all()
assert pomiary_clean["energia"].count() == 718
assert pomiary_clean["produkcja"].count() == 719
Nie traktuj niepowodzenia asercji jako przeszkody, którą trzeba szybko usunąć. Zatrzymanie może ujawnić inny plik, nieprawidłowy odczyt lub zmianę danych. Sprawdź przyczynę i udokumentuj decyzję. Mechaniczne zastąpienie oczekiwanej liczby nową liczbą odbiera kontroli sens.
Test czystego uruchomienia
Zapisz notebook, zrestartuj kernel i wykonaj wszystkie komórki od góry. Jeśli wystąpi błąd, popraw pierwszą przyczynę i ponownie zacznij od restartu. Uruchomienie tylko poprawionej komórki nie sprawdza, czy wszystkie zależności są już jawne. Po udanym przebiegu zapisz notebook z aktualnymi wynikami.
Następnie porównaj wyniki po redakcji z zatwierdzoną analizą: wartości median, liczebności, filtry, zakres dat i miary korelacji. Do porównania ramek służy pd.testing.assert_frame_equal; wcześniej ustal wspólny porządek kolumn i wierszy. Nie wystarczy porównać samego shape — dwie różne tabele mogą mieć identyczne wymiary.
Na końcu przeczytaj notebook tak, jak przeczytałaby go osoba, która nie widziała eksperymentów. Czy każdą tabelę poprzedza cel, a po niej następuje objaśnienie? Czy komentarz nadal opisuje aktualny kod? Czy wnioski nie korzystają z liczby, której nigdzie nie wyliczono?
Sprawdź rozumienie 2
Notebook działa po uruchomieniu jednej komórki, ale po restarcie zgłasza brak zmiennej. Co to mówi o jego odtwarzalności? Jak sprawdzisz, że po uporządkowaniu kodu nie zmieniła się treść wyników?