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ń.
- Utwórz katalog główny oraz data/raw, data/processed, notebooks, outputs/figures, outputs/tables i docs.
- Umieść otrzymane pliki wejściowe w data/raw bez zmiany ich zawartości.
- Zapisz notebook w katalogu notebooks.
- Dodaj README.md i słownik danych, a w notebooku zdefiniuj ścieżki z pathlib.
- Sprawdź metodą exists(), czy plik wejściowy jest dostępny.
Sprawdź się: Gotowy projekt można spakować i przenieść jako jeden katalog.