Podręcznik uczestnika z objaśnieniami, przykładami i ćwiczeniami do samodzielnej nauki

4. Organizacja projektu i plików

Notebook jest centralnym dokumentem analizy, ale sam nie wystarczy do jej powtórzenia. Potrzebujesz danych wejściowych, miejsca na dane przetworzone, wyników zapisanych do plików i krótkiej dokumentacji. Wszystkie te elementy powinny znajdować się w jednym katalogu głównym projektu.

Struktura projektu

eksploatacja_urzadzen/
├── data/
│   ├── raw/
│   └── processed/
├── notebooks/
│   └── M1_szkielet_analizy.ipynb
├── outputs/
│   ├── figures/
│   └── tables/
├── docs/
│   └── slownik_danych.md
└── README.md

Miejsce

Przeznaczenie

Przykład

data/raw

Niezmienione dane źródłowe

pomiary_eksploatacyjne.csv

data/processed

Dane utworzone przez kod

pomiary_clean.csv

notebooks

Notebooki analityczne

M1_szkielet_analizy.ipynb

outputs/figures

Wykresy przeznaczone do raportu

awarie_top5.png

outputs/tables

Tabele i zestawienia

ranking_awarii.csv

docs

Opis danych i decyzji

slownik_danych.md

Dane źródłowe jako punkt odniesienia

Katalog data/raw traktuj jak archiwum. Kod może z niego czytać, ale nie powinien nadpisywać oryginalnych plików. Nie poprawiaj ręcznie wartości w arkuszu, nie usuwaj podejrzanych rekordów bez kryterium i nie zapisuj wyników obok źródła. Przekształcenia wykonuj kodem, a przygotowaną wersję danych zapisuj oddzielnie w data/processed.

Czytelna nazwa pliku powinna mówić o jego zawartości lub roli. Nazwy dane_final.csv, dane_final2.csv i ostateczny.csv nie tworzą dokumentacji. Pomiary_eksploatacyjne.csv, pomiary_clean.csv i ranking_awarii.csv mówią, co zawiera plik i na jakim etapie pracy powstał.

Ścieżki względem projektu

Ścieżka bezwzględna zawiera dysk, konto użytkownika i układ katalogów jednego komputera. Po przeniesieniu projektu do innego systemu zwykle przestaje działać. Zamiast niej ustal katalog projektu raz, a wszystkie ścieżki buduj względem niego za pomocą pathlib.

from pathlib import Path
 
# Założenie: bieżący katalog roboczy to notebooks/
PROJECT_DIR = Path.cwd().parent
RAW_DIR = PROJECT_DIR / "data" / "raw"
DATA_FILE = RAW_DIR / "pomiary_eksploatacyjne.csv"
 
print("Plik istnieje:", DATA_FILE.exists())

Jeżeli plik nie zostanie znaleziony, nie zmieniaj kodu na oślep. Najpierw wyświetl bieżący katalog roboczy za pomocą Path.cwd(), potem zbudowaną ścieżkę i dopiero na końcu wynik DATA_FILE.exists(). To pozwala odróżnić błąd w założeniu o katalogu od literówki w nazwie pliku.

Minimum dokumentacji

  • README.md opisuje cel projektu, strukturę katalogów, sposób uruchomienia, wymagane pliki i wyniki.
  • docs/slownik_danych.md wyjaśnia znaczenie pól, jednostki, typy danych, dopuszczalne wartości oraz znane ograniczenia.
  • Wykresy i tabele są zapisywane przez kod do przewidywalnych katalogów wynikowych.

Ćwiczenie Struktura projektu

Przygotuj katalog projektu Eksploatacja urządzeń.

  1. Utwórz katalog główny oraz data/raw, data/processed, notebooks, outputs/figures, outputs/tables i docs.
  2. Umieść otrzymane pliki wejściowe w data/raw bez zmiany ich zawartości.
  3. Zapisz notebook w katalogu notebooks.
  4. Dodaj README.md i słownik danych, a w notebooku zdefiniuj ścieżki z pathlib.
  5. Sprawdź metodą exists(), czy plik wejściowy jest dostępny.

Sprawdź się: Gotowy projekt można spakować i przenieść jako jeden katalog.