7. Transformacje łączenie i walidacja wyniku

Wynik modułu ma być zrozumiały także dla osoby, która nie obserwowała twojej pracy. Przygotujesz więc czytelne nazwy, kolumny pochodne i jednoznaczne połączenie z kartoteką. Następnie sprawdzisz rezultat, zapiszesz plik i ponownie go odczytasz. Dokumentacja pozostanie częścią wyniku, ponieważ nazwa clean nie oznacza braku ograniczeń.

Nazwy i kolumny pochodne

Zmień nazwę typ na typ_urzadzenia, aby po połączeniu było jasne, czego dotyczy. Pole rok_miesiac utwórz z czasu pomiaru. Zapis YYYY-MM ułatwi agregowanie danych w module 3, ale nie zastępuje dokładnego znacznika czasu.

urzadzenia_clean = urzadzenia_clean.rename(
    columns={"typ": "typ_urzadzenia"}
)
urzadzenia_clean["urzadzenie"] = (
    urzadzenia_clean["urzadzenie"].astype("string")
)
urzadzenia_clean["data_instalacji"] = pd.to_datetime(
    urzadzenia_clean["data_instalacji"], errors="raise"
)
pomiary_clean["rok_miesiac"] = (
    pomiary_clean["czas"].dt.to_period("M").astype("string")
)
assert set(pomiary_clean["rok_miesiac"]) == {"2026-01", "2026-02"}

Kolumna pochodna potrzebuje definicji: danych wejściowych, reguły, typu i jednostki, jeżeli ma sens liczbowy. Zapisz, że rok_miesiac powstaje z czas i ma typ string. Pozostawienie obu pól umożliwia sprawdzenie, czy przypisanie do miesiąca jest poprawne.

Kontrakt połączenia

Wiele pomiarów jednego urządzenia łączysz z jednym rekordem kartoteki. Taka relacja to wiele do jednego, w Pandas many_to_one. Oczekujesz jednego zestawu metadanych na każdy pomiar i niezmienionej liczby wierszy. Klucz kartoteki musi więc być kompletny i unikalny.

Połączenie left zachowuje wszystkie pomiary, ujawniając brak dopasowania jako brak metadanych. Inner zachowałoby tylko dopasowane wiersze, więc przy nieznanym urządzeniu mogłoby ukryć problem przez usunięcie jego pomiarów. Wybór rodzaju połączenia wynika z celu, nie z tego, który wariant akurat działa na aktualnych danych.

Łączenie z kontrolą liczby rekordów

Przed połączeniem sprawdź klucze obu tabel i zapamiętaj liczbę pomiarów. Kartoteka może zawierać urządzenia bez pomiarów w danym okresie; taki przypadek należy odnotować, ale nie jest tym samym co pomiar bez kartoteki.

assert pomiary_clean["urzadzenie"].notna().all()
assert urzadzenia_clean["urzadzenie"].notna().all()
assert urzadzenia_clean["urzadzenie"].is_unique
ids_p = set(pomiary_clean["urzadzenie"])
ids_u = set(urzadzenia_clean["urzadzenie"])
assert not (ids_p - ids_u)
print("Urządzenia bez pomiarów:", ids_u - ids_p)
liczba_przed = len(pomiary_clean)
pomiary_clean = pomiary_clean.merge(
    urzadzenia_clean, on="urzadzenie", how="left",
    validate="many_to_one", indicator=True
)
assert len(pomiary_clean) == liczba_przed
assert pomiary_clean["_merge"].eq("both").all()
pomiary_clean = pomiary_clean.drop(columns="_merge")

Validate zatrzymuje operację, jeżeli kartoteka narusza relację wiele do jednego. Indicator tworzy kolumnę _merge do kontroli dopasowania. W aktualnych danych jest 720 dopasowań both. Przy left nie powstają rekordy right_only; urządzenia występujące wyłącznie w kartotece sprawdzaj różnicą zbiorów albo osobnym diagnostycznym outer merge.

Gdyby dopisać drugi rekord U-03 w kartotece i nie zastosować validate, 90 pomiarów tego urządzenia uzyskałoby po dwa dopasowania. Tabela urosłaby z 720 do 810 wierszy. Sam fakt, że merge() zwrócił wynik, nie potwierdza poprawności relacji.

Wiek urządzenia w dniu pomiaru

pomiary_clean["wiek_urzadzenia_dni"] = (
    pomiary_clean["czas"].dt.normalize()
    - pomiary_clean["data_instalacji"]
).dt.days.astype("Int64")
assert pomiary_clean["wiek_urzadzenia_dni"].notna().all()
assert pomiary_clean["wiek_urzadzenia_dni"].ge(0).all()

Normalize sprowadza czas pomiaru do początku dnia. Różnica oznacza wiek od daty instalacji do dnia pomiaru, nie do dzisiejszej daty. W zbiorze wynosi 1361–3516 dni. Dla instalacji 5 listopada 2020 i pomiaru 1 stycznia 2026 otrzymasz 1883 dni.

Jawny schemat pliku wynikowego

Porządek kolumn ma pokazywać model danych: identyfikację i czas, kartotekę, pomiary, a na końcu kontekst pracy. Po dodaniu czterech pól kartoteki i dwóch pól pochodnych otrzymasz 14 kolumn. Schemat zapisany w kodzie przyda się także po ponownym odczycie CSV.

KOLUMNY_WYNIK = [
    "czas", "rok_miesiac", "urzadzenie",
    "typ_urzadzenia", "lokalizacja", "moc_nominalna_kw",
    "data_instalacji", "wiek_urzadzenia_dni",
    "temperatura", "drgania", "energia", "produkcja",
    "tryb", "status"
]
SCHEMAT_WYNIK = {
    "rok_miesiac": "string", "urzadzenie": "string",
    "typ_urzadzenia": "string", "lokalizacja": "string",
    "moc_nominalna_kw": "float64", "temperatura": "float64",
    "drgania": "float64", "energia": "float64",
    "wiek_urzadzenia_dni": "Int64", "produkcja": "Int64",
    "tryb": pd.CategoricalDtype(
        pd.Index(["auto", "oszczedny"], dtype="string")),
    "status": pd.CategoricalDtype(pd.Index(["OK"], dtype="string"))
}
pomiary_clean = pomiary_clean[KOLUMNY_WYNIK].astype(SCHEMAT_WYNIK)

Dwie kolumny dat zostały przygotowane wcześniej. Pozostałe typy odtwarza SCHEMAT_WYNIK. CategoricalDtype określa również dozwolone kategorie i tekstowy typ ich etykiet, aby odczyt odtworzył ten sam schemat. Jawna lista kolumn pozwala wykryć przypadkowe dodanie, pominięcie lub przestawienie pola.

Kontrola przed zapisem

assert pomiary_clean.shape == (720, 14)
assert not pomiary_clean.duplicated(subset=KLUCZ).any()
assert pomiary_clean["energia"].isna().sum() == 2
assert pomiary_clean["produkcja"].isna().sum() == 1
assert pomiary_clean["produkcja"].dropna().ge(0).all()
META = ["typ_urzadzenia", "lokalizacja",
        "moc_nominalna_kw", "data_instalacji"]
assert pomiary_clean[META].notna().all().all()
assert pomiary_clean["wiek_urzadzenia_dni"].ge(0).all()
assert pomiary_clean["drgania"].gt(2).sum() == 1
assert np.isclose(pomiary_clean["energia"].sum(),
                  10001.16, rtol=0, atol=0.005)

Te liczby kontrolne dotyczą konkretnej wersji danych kursowych. Dla nowego źródła ustal oczekiwania na nowo. Gdy asercja zatrzyma notebook, zbadaj przyczynę; nie zmieniaj oczekiwanej liczby tylko po to, aby test przeszedł. Asercje są tutaj kontrolami wykonywanymi w zwykłej sesji notebooka, nie kompletnym systemem walidacji produkcyjnej.

Zapis i ponowny odczyt

CSV przechowuje wartości tekstowe, nie schemat Pandas. Nie zachowuje kategorii ani typu Int64. Dlatego po odczycie ponownie interpretujesz daty i ustawiasz typy. Index=False zapobiega zapisaniu technicznego indeksu jako dodatkowej kolumny.

DATA_PROCESSED = PROJECT_DIR / "data" / "processed"
TABLES = PROJECT_DIR / "outputs" / "tables"
DATA_PROCESSED.mkdir(parents=True, exist_ok=True)
TABLES.mkdir(parents=True, exist_ok=True)
plik_wynik = DATA_PROCESSED / "pomiary_clean.csv"
pomiary_clean.to_csv(
    plik_wynik, index=False, encoding="utf-8",
    date_format="%Y-%m-%d %H:%M"
)
wczytany = pd.read_csv(
    plik_wynik, encoding="utf-8",
    parse_dates=["czas", "data_instalacji"]
).astype(SCHEMAT_WYNIK)
assert wczytany.columns.tolist() == KOLUMNY_WYNIK
pd.testing.assert_frame_equal(
    pomiary_clean.reset_index(drop=True),
    wczytany.reset_index(drop=True),
    check_exact=False, rtol=1e-12, atol=1e-12
)

Porównujesz nie tylko kształt, lecz również wartości, braki i typy. Mała tolerancja liczb zmiennoprzecinkowych uwzględnia techniczny zapis i odczyt, nie służy do ukrywania merytorycznych różnic. Pomyślna kontrola samego shape nie wykryłaby na przykład zamiany dwóch wartości energii.

Tożsamość pliku i odtwarzalność

import hashlib
suma_sha256 = hashlib.sha256(plik_wynik.read_bytes()).hexdigest()
print("SHA-256:", suma_sha256)

Wynik SHA-256 ma 64 znaki szesnastkowe i identyfikuje dokładną zawartość pliku. Zapisz go w README.md wraz z datą utworzenia rezultatu. Zmiana formatowania CSV może zmienić sumę mimo równoważności danych. Zgodny skrót nie dowodzi jakości; potwierdza jedynie zgodność bajtów z wcześniej odnotowaną wersją.

Na zakończenie zapisz notebook, zrestartuj kernel i wykonaj wszystkie komórki od góry. Wyniki powinny powstać ponownie z data/raw, bez ręcznych poprawek i dodatkowych obiektów pozostałych w pamięci. Kod zapisu zastępuje wcześniejszy rezultat w data/processed; archiwizuj osobno wersję, którą chcesz zachować do porównania.

Tabela jakości i dokumentacja

Utwórz jedno porównanie stanu przed i po. Nie przepisuj ręcznie samych oczekiwanych liczb — oblicz je z ramek. Przykładowa funkcja zbiera podstawowe miary, a przyrost liczby kolumn pokaże efekt dołączenia kartoteki i pól pochodnych.

def miary_jakosci(df):
    return pd.Series({
        "rekordy": len(df), "kolumny": df.shape[1],
        "duplikaty_klucza": df.duplicated(KLUCZ).sum(),
        "braki_energia": df["energia"].isna().sum(),
        "braki_produkcja": df["produkcja"].isna().sum(),
        "produkcja_ujemna": df["produkcja"].lt(0).sum(),
        "warianty_tryb": df["tryb"].nunique(),
        "warianty_status": df["status"].nunique(),
        "drgania_iqr": wykryj_iqr(df["drgania"])[0].sum(),
        "drgania_powyzej_2": df["drgania"].gt(2).sum()
    })
audyt = pd.DataFrame({"przed": miary_jakosci(pomiary_raw),
                      "po": miary_jakosci(wczytany)})
audyt.loc["braki_metadanych", "po"] = (
    wczytany[META].isna().any(axis=1).sum())
audyt.rename_axis("kontrola").to_csv(
    TABLES / "M2_audyt_jakosci.csv", encoding="utf-8"
)

Brak wartości „przed” dla metadanych znaczy „nie dotyczy tabeli wejściowej”, a nie zero. W notebooku dopisz interpretację: rekordów nadal jest 720, kolumn 14, wariantów trybu i statusu odpowiednio dwa i jeden, braków energii dwa, produkcji jeden. Trzy sygnały IQR drgań i jeden pomiar powyżej 2 mm/s pozostają zachowane.

Uzupełnij docs/slownik_danych.md o typ_urzadzenia, rok_miesiac i wiek_urzadzenia_dni oraz zasady dopuszczenia braków. Zachowaj opis źródłowego pola typ, wskazując jego nową nazwę w wyniku. Dziennik decyzji w notebooku powinien obejmować także zachowane nietypowe wartości, a README — środowisko i kolejność odtworzenia.

Jeśli korzystasz z LLM, zapisuj prompt, odpowiedź, test, werdykt i uzasadnienie w docs/rejestr_uzycia_LLM.csv, z wartością M2 w polu modul. Rejestruj rzeczywiste użycie, nie przykładową rozmowę jako wykonaną. Przekazuj modelowi tylko potrzebny, dozwolony kontekst; nie wysyłaj haseł ani poufnych danych.

Sprawdź rozumienie 6

Po połączeniu otrzymujesz 810 zamiast 720 wierszy. Dlaczego to sygnał do zatrzymania pracy? Która kontrola powinna wykryć przyczynę przed zapisaniem wyniku?