Lab_03_Konwolucyjne_sieci_neuronowe.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div align=\"center\">\n",
    "\n",
    "<font size=\"5\">\n",
    "\n",
    "Laboratorium z przedmiotu: \\\n",
    "**Głębokie uczenie i analiza obrazów**\n",
    "\n",
    "Ćwiczenie 3: \\\n",
    "**Konwolucyjne sieci neuronowe**\n",
    "\n",
    "</font>\n",
    "\n",
    "\\\n",
    "Marta Szarmach \\\n",
    "Zakład Telekomunikacji Morskiej \\\n",
    "Wydział Elektryczny \\\n",
    "Uniwersytet Morski w Gdyni\n",
    "\n",
    "09.2023\n",
    "</div>\n",
    "\n",
    "\n",
    "\n",
    "# 1. Wprowadzenie\n",
    "\n",
    "**Konwolucyjne sieci neuronowe** (ang. *convolutional neural networks*, CNN) to sieci, których działanie opiera się na konwolucji. W skrócie, sygnał dostarczony do sieci neuronowej (np. zdjęcie) analizowany jest fragment po fragmencie poprzez wykonanie konwolucji (wymnożenia i zsumowania) tegoż fragmentu z pewnym **filtrem** (ang. *kernel*). Zadaniem filtra jest (poprzez konwolucję) rozpoznanie w analizowanym sygnale pewnych cech (np. krawędzi), a na późniejszych etapie nawet pewnych obiektów. To właśnie na zawartość filtra składają się parametry sieci konwolucyjnej, wyznaczane w ramach jej treningu. \n",
    "\n",
    "Z racji swojej budowy i działania, konwolucyjne sieci neuronowe znalazły szerokie zastosowanie w analizie obrazów. Obrazy są najczęściej przedstawiane w formie 3-kanałowych macierzy (RGB), a następnie poddawane są konwolucji z filtrami, na którą wzór można zapisać tak:\n",
    "\\begin{equation*}\n",
    "    (A * H)[m,n] = \\sum_j \\sum_k H[j,k] \\cdot A[m-j,n-k]\n",
    "\\end{equation*}\n",
    "Każdy filtr ma za zadanie wykryć pewną konkretną cechę/zawartość analizowanego fragmentu obrazu. Zaczyna się zazwyczaj od odnajdywania prostych elementów, takich, jak krawędzie, a następnie, na kolejnych warstwach, sieć jest w stanie wykrywać coraz bardziej złożone kształty i obiekty. Zazwyczaj z każdą kolejną warstwą konwolucyjną zwiększa się ilość kanałów sygnału (tj. wykrywa się więcej kształtów).\n",
    "\n",
    "<div align=\"center\">\n",
    "\n",
    "<img src='https://i0.wp.com/developersbreach.com/wp-content/uploads/2020/08/cnn_banner.png?fit=1400%2C658&ssl=1'/>\n",
    "\n",
    "<font size=\"1\">Grafika: developersbreach.com</font>\n",
    "</div>\n",
    "\n",
    "Typowa budowa sieci konwolucyjnej przedstawiona jest na powyższym rysunku. Zazwyczaj sieci te buduje się z kilku występującycj po sobie bloków, złożonych z warstwy konwolucyjnej (wykonującej właściwą konwolucję), warstwy aktywacyjnej (np. ReLU) oraz innych, takich jak *dropout* czy *BatchNorm*. Na końcu sieci znajduje się najczęściej warstwa Flatten, która sprowadza dane dlań wejściowe do postaci 1-wymiarowego tensora, a za nią dane te przekształcane są przez jedną bądź kilka warstw liniowych. Na końcu sieci występuje warstwa przeprowadzająca ostateczną predykcję - w zależności od rozwiązywanego problemu, może to być Sigmoid, Softmax, itp.\n",
    "\n",
    "Pomiędzy blokami konwolucyjnymi możemy użyć także dodatkowej warstwy, zwanej *pooling layer*, która ma na celu zmiejszenie wymiaru ,,obrazu'' przekazywanego do następnej warstwy. Mamy fo wyboru:\n",
    "* *max pooling* - grupa pikseli zastępowana jest jednym, o wartości największej z grupy,\n",
    "* *average pooling* - grupa pikseli zastępowana jest jednym, o wartości średniej całej grupy.\n",
    "\n",
    "Hiperparametrami regulującymi działanie konwolucyjnych sieci neuronowych, które nie występowały w ,,zwykłych'' sieciach neuronowych (opartych na warstwach liniowych), są:\n",
    "* *kernel_size* - wielkość filtra,\n",
    "* *padding* - określa, jak „szeroka” ma być dodana (na dowolnej warstwie) do obrazu ramka z zer, co ma przeciwdziałać nadmiernemu zmiejszaniu się wymiarów obrazu wraz z kolejnymi konwolucjami, a także umożliwić dokładniejszą analizę brzegów obrazu,\n",
    "* *stride* - określa, za ile pikseli filtr wykona następną konwolucję.\n",
    "\n",
    "\n",
    "\n",
    "# 2. Cel ćwiczenia\n",
    "\n",
    "**Celem niniejszego ćwiczenia** jest zapoznanie się z budową i działaniem konwolucyjnych sieci neuronowych poprzez:\n",
    "* implementacji architektury pewnej konwolucyjnej sieci neuronowej o niewielkiej ilości warstw z wykorzystaniem biblioteki PyTorch i języka programowania Python,\n",
    "* skorzystanie z implementacji gotowej sieci konwolucyjnej, realizującej klasyfikację obrazów - AlexNet.\n",
    "\n",
    "\n",
    "# 3. Stanowisko laboratoryjne\n",
    "\n",
    "Do wykonania niniejszego ćwiczenia niezbędne jest stanowisko laboratoryjne, składające się z komputera klasy PC z zainstalowanym oprogramowaniem:\n",
    "* językiem programowania Python (w wersji 3.8),\n",
    "* IDE obsługującym pliki Jupyter Notebook (np. Visual Studio Code z rozszerzeniem ipykernel).\n",
    "\n",
    "\n",
    "# 4. Przebieg ćwiczenia\n",
    "## 4.1. Implementacja konwolucyjnej sieci neuronowej z wykorzystaniem biblioteki PyTorch\n",
    "\n",
    "Na początku wykonaj poniższy fragment kodu, aby zaimportować biblioteki niezbędne do wykonania poniższego ćwiczenia:\n",
    "* **PyTorch** - biblioteka wspomagająca budowanie architektur sieci neuronowych, posiadająca wbudowane moduły odpowiadające różnym warstwom sieci neuronowych, automatyczne obliczanie gradientów (*autograd*) niezbędne do przeprowadzenia treningu sieci neuronowych,\n",
    "* **NumPy** - biblioteka umożliwiająca wykonywanie wysoko zoptymalizowanych obliczeń matematycznych na objektach typu *numpy array* (wielowymiarowych tablic),\n",
    "* **Matplotlib** - biblioteka wspomagająca wizualizację pracy czy analizę danych poprzez wyświetlanie wykresów,\n",
    "* **Scikit-learn** - biblioteka zawierająca gotowe implementacje wielu algorytmów klasycznego uczenia maszynowego, a także zbiory danych czy metryki; tutaj skorzystamy ze zbioru danych MNIST - `datasets.load_digits` oraz metody `model_selection.train_test_split` służącej do podziału danych na zestaw treningowy i testowy,\n",
    "* **Optuna** - biblioteka zawierająca narzędzia automatyzujące optymalizację danej funkcji."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-11-09T10:00:51.453782700Z",
     "start_time": "2023-11-09T10:00:45.724739700Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": "<torch._C.Generator at 0x1bcb1c92a90>"
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# ! python -m pip install torch==2.0.1\n",
    "# ! python -m pip install numpy==1.22.3\n",
    "# ! python -m pip install scikit-learn==0.24.2\n",
    "# ! python -m pip install matplotlib==3.4.2\n",
    "# ! python -m pip install optuna\n",
    "\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "import torch\n",
    "from sklearn.datasets import load_digits\n",
    "from sklearn.model_selection import train_test_split\n",
    "import optuna\n",
    "# (dla zachowania powtarzalności wyników)\n",
    "np.random.seed(10) \n",
    "torch.manual_seed(10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Wczytanie i przygotowanie danych\n",
    "\n",
    "Na początku przygotujmy dane, na których będziemy dziś pracować. Tym razem korzystać będziemy ze zbioru MNIST, zawierającego *num_samples* = 1797 obrazków o rozmiarze 8x8, przedstawiających odręcznie pisane cyfry. Uruchom kod z poniższej komórki, aby:\n",
    "* wczytać oryginalne dane z zestawu MNIST (`digits`) do zmiennej $X$ i ich etykiety do zmiennej $y$,\n",
    "* obliczyć (z wykorzystaniem metody `numpy.unique`) w automatyczny sposób ilość klas występujących w naszym zbiorze danych (tj. ilość unikalnych wartości w etykietach) - wiemy, że powinno ich być 10, tyle, ile cyfr,\n",
    "* z pomocą `train_test_split` wydzielić 70% obrazków jako zestaw treningowy $Xtrain$, a pozostałą część danych po równo podzielić na zestaw walidacyjny $Xval$ i testowy $Xtest$ (po 15%),\n",
    "* przygotować etykiety tak, aby współpracowały z funkcją kosztu `CrossEntropyLoss`, którą zastosujemy przy treningu naszej sieci - odpowiedź od każdego neuronu zbierana będzie w osobnej kolumnie tablicy, dlatego nasze etykiety w formacie (*num_samples*,), zawierające wartości 0,1,...9 przekształcimy za pomocą one-hot-encodingu do postaci (*num_samples*, *num_classes*), np. 2 -> [0,0,1]\n",
    "* ostatecznie, dane i przekształcone etykiety, które będą przekazywane sieci neuronowej, przekształcić do formatu `torch.tensor`, aby były zrozumiałe dla PyTorcha; jednocześnie wyodrębniając w danych jako drugi wymiar ilość kanałów (w tym przypadku jest to 1): nasze dane wejściowe mają teraz kształt (*num_samples*, *num_channels*, *sample_size*, *sample_size*), gdzie *num_channels* = 1 (dla obrazów RGB byłoby to 3), *sample_size*=8."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-11-09T10:00:51.472823Z",
     "start_time": "2023-11-09T10:00:51.454787400Z"
    }
   },
   "outputs": [],
   "source": [
    "# --------------------------- Inicjalizacja ----------------------------\n",
    "# Wczytanie danych\n",
    "digits = load_digits()\n",
    "X = digits.images\n",
    "y = digits.target\n",
    "num_classes = (np.unique(y)).shape[0]\n",
    "# Podziel dane na zestaw treningowy (70%), walidacyjny (15%) i testowy (15%) z wykorzystaniem metody train_test_split\n",
    "Xtrain, Xtest, ytrain, ytest = train_test_split(X,y,train_size=0.6)\n",
    "Xval, Xtest, yval, ytest = train_test_split(Xtest,ytest,train_size=0.5)\n",
    "# Dokonaj one-hot-encodingu etykiet z zestawu treningowego i walidacyjnego\n",
    "ytrain_ohe = np.identity(num_classes)[ytrain]\n",
    "yval_ohe = np.identity(num_classes)[yval]\n",
    "# Przekonwertuj dane wejściowe na tensory, by mogłby być obsługiwane przez PyTorch\n",
    "# i jednocześnie wydziel wymiar 1 jako ilość kanałów\n",
    "Xtrain = torch.tensor(Xtrain.reshape(-1, 1, Xtrain.shape[1], Xtrain.shape[2]))\n",
    "ytrain_ohe = torch.tensor(ytrain_ohe) \n",
    "Xval = torch.tensor(Xval.reshape(-1, 1, Xval.shape[1], Xval.shape[2])) \n",
    "yval_ohe = torch.tensor(yval_ohe)\n",
    "Xtest = torch.tensor(Xtest.reshape(-1, 1, Xtest.shape[1], Xtest.shape[2]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Określenie struktury naszej sieci neuronowej\n",
    "\n",
    "W kolejnym kroku zdefiniujemy strukturę naszej konwolucyjnej  sieci neuronowej, korzystając z klas dostępnych w bibliotece PyTorch! Tak samo, jak ostatnio, zrobimy to w naszej własnej klasie - nazwijmy ją `ConvNet` - która musi dziedziczyć z klasy `torch.nn.Module`, w której umieścimy dwie metody:\n",
    "* metodę-konstruktor `__init__()` - opisującą budowę sieci; skorzystamy tu ze znanych już wcześniej warstw `torch.nn.Linear`, `torch.nn.ReLU`, `torch.nn.Dropout`, `torch.nn.Softmax` czy `torch.nn.Sequential`, ale użyjemy także kilku nowych, charakterystycznych dla konwolucyjnych sieci neuronowych:\n",
    "    * `torch.nn.Conv2d` - ([TUTAJ](https://pytorch.org/docs/stable/generated/torch.nn.Conv2d.html)) - realizująca właściwą konwolucję pomiędzy filtrami a fragmentami obrazów; wymaga takich argumentów, jak: ilość kanałów wejściowych/wyjściowych, wielkość filtra, *padding*, *stride*,\n",
    "    * `torch.nn.BatchNorm` - ([TUTAJ](https://pytorch.org/docs/stable/generated/torch.nn.BatchNorm2d.html)) i ([TUTAJ](https://pytorch.org/docs/stable/generated/torch.nn.BatchNorm1d.html)) - realizująca normalizację wsadową, zarówno na obrazach (2d), jak i na 1-wymiarowych tensorach (1d),\n",
    "    * `torch.nn.Flatten` - ([TUTAJ](https://pytorch.org/docs/stable/generated/torch.nn.Flatten.html)) - realizująca ,,wypłaszczenie'' wejściowego sygnału 2d do postaci 1-wymiarowego tensora.\n",
    "* metodę `forward()` - w której określamy przepływ danych pomiędzy warstwami.\n",
    "\n",
    "Uzupełnij zatem poniższy kod! Oto założenia:\n",
    "* Niech nasza sieć neuronowa składa się z następujących warstw:\n",
    "\n",
    "2 x (`Conv2d` -> `BatchNorm2d` -> `Dropout` -> `ReLU`) -> `Flatten` -> `Linear` -> `BatchNorm1d` -> `Dropout` -> `Softmax`.\n",
    "* Podczas pierwszej konwolucji, niech wyznaczonych zostanie 16 kanałów, a po drugiej - 32 (ilość kanałów przechowywana jest w tablicy `num_conv_channels`).\n",
    "* Prawdopodobieństwo odrzucenia neuronu przez `dropout` niech wynosi 0,25.\n",
    "\n",
    "Wskazówki:\n",
    "* Po każdej konwolucji, wymiary obrazu (szerokość i długość) zmieniają się zgodnie z poniższym wzorem:\n",
    "\\begin{equation*}\n",
    "    sample\\_size_{\\textrm{new}} = \\frac{sample\\_size_{\\textrm{original}} + 2 \\cdot padding - kernel\\_size}{stride} + 1 \n",
    "\\end{equation*}\n",
    "* Zastanów się, jak długi tensor zwróci nam warstwa ```Flatten``` (będzie Ci to potrzebne do właściwej inicjalizacji warstwy ```Linear```) - do policzenia tego, na pewno będziesz potrzebować wymiaru obrazka po ostatniej konwolucji, a także ilości kanałów po tejże konwolucji!\n",
    "* `BatchNorm2d` jako argument  `num_features` wymaga ilości kanałów w analizowanych przezeń danych, natomiast `BatchNorm1d` - ilość neuronów z ostatniej warstwy Linear.\n",
    "* Wszystkie niezbędne dane przekazywać będziemy konstruktorowi jako argumenty."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-11-09T10:00:51.494405200Z",
     "start_time": "2023-11-09T10:00:51.473827300Z"
    }
   },
   "outputs": [],
   "source": [
    "class ConvNet(torch.nn.Module):\n",
    "    \"\"\"\n",
    "    Model konwolucyjnej sieci neuronowej:\n",
    "    (Conv -> BatchNorm -> Dropout -> ReLU) -> (Conv -> BatchNorm -> Dropout -> ReLU) -> (Flatten -> Linear -> BatchNorm -> Dropout -> Softmax)\n",
    "    \"\"\"\n",
    "    \n",
    "    def __init__(self, input_channels, sample_size, output_layer_size, kernel_size, padding, stride):\n",
    "        \"\"\"\n",
    "        Definiuje budowę sieci. Argumenty: \\n\n",
    "        - input_channels - ilość kanałów w wejściowych obrazkach (skalar, int)\n",
    "        - sample_size - długość/szerokość wejściowego obrazka (skalar, int)\n",
    "        - output_layer_size - ilość neuronów na ostatniej warstwie (skalar, int)\n",
    "        - kernel_size - wielkość filtra do konwolucji (skalar, int)\n",
    "        - padding - ,,grubość'' ramki z zer dodowananej do obrazka (skalar, int)\n",
    "        - stride - co ile pikseli obrazka wykonywana jest konwolucja (skalar, int)\n",
    "        \"\"\"\n",
    "        super().__init__()\n",
    "        num_conv_channels = [16, 32] # Do dowolnej modyfikacji - ilość kanałów po kolejnych konwolucjach\n",
    "        # ---------------------- UZUPEŁNIJ KOD -----------------------------------\n",
    "        # Oblicz rozmiary obrazków po pierwszej konwolucji\n",
    "        size1 = ((sample_size + 2 * padding - kernel_size) / stride) + 1\n",
    "        # Oblicz rozmiary obrazków po drugiej konwolucji\n",
    "        size2 = int(((size1 + 2 * padding - kernel_size) / stride) + 1)\n",
    "        # Zacznij definiować budowę sieci:\n",
    "        self.first_layer = torch.nn.Sequential(\n",
    "            # Warstwa konwolucyjna\n",
    "            torch.nn.Conv2d(\n",
    "                 in_channels=input_channels,\n",
    "                 out_channels=num_conv_channels[0],\n",
    "                 kernel_size=kernel_size,\n",
    "                 padding=padding,\n",
    "                 stride=stride\n",
    "            ),\n",
    "            # BatchNorm2d\n",
    "            torch.nn.BatchNorm2d(num_features=num_conv_channels[0]),\n",
    "            # Dropout (niech neuron zostanie usunięty z prawdopodobieństwem 0.25)\n",
    "            torch.nn.Dropout(0.25),\n",
    "            # Funkcja aktywacji ReLU\n",
    "            torch.nn.ReLU() \n",
    "        )\n",
    "        self.second_layer = torch.nn.Sequential(\n",
    "            # Warstwa konwolucyjna\n",
    "            torch.nn.Conv2d(\n",
    "                 in_channels=num_conv_channels[0],\n",
    "                 out_channels=num_conv_channels[1],\n",
    "                 kernel_size=kernel_size,\n",
    "                 padding=padding,\n",
    "                 stride=stride\n",
    "            ),\n",
    "            # BatchNorm2d\n",
    "            torch.nn.BatchNorm2d(num_features=num_conv_channels[1]),\n",
    "            # Dropout (niech neuron zostanie usunięty z prawdopodobieństwem 0.25)\n",
    "            torch.nn.Dropout(0.25),\n",
    "            # Funkcja aktywacji ReLU\n",
    "            torch.nn.ReLU() \n",
    "        )\n",
    "        self.third_layer = torch.nn.Sequential(\n",
    "            # Flatten\n",
    "            torch.nn.Flatten(),\n",
    "            # Linear\n",
    "            torch.nn.Linear(\n",
    "                 in_features=size2 * size2 * 32,\n",
    "                 out_features=output_layer_size\n",
    "            ),\n",
    "            # BatchNorm1d\n",
    "            torch.nn.BatchNorm1d(num_features=output_layer_size),\n",
    "            # Dropout\n",
    "            torch.nn.Dropout(0.25),\n",
    "            # Softmax\n",
    "            torch.nn.Softmax(dim=1)\n",
    "        )\n",
    "        # ---------------------------------------------------------------------\n",
    "\n",
    "    def forward(self, X):\n",
    "            \"\"\" \n",
    "            Definiuje przepływ danych w sieci. \\n\n",
    "            Argument: X - dane wejściowe, obrazki w postaci torch.tensor, shape=(num_samples, input_channels, sample_size, sample_size) \\n\n",
    "            Zwraca: X - odpowiedź sieci w postaci prawdopodobieństw, torch.tensor, shape=(sum_samples, num_classes)\n",
    "            \"\"\"\n",
    "            # ------------------- UZUPEŁNIJ KOD ----------------\n",
    "            X = self.first_layer(X)\n",
    "            X = self.second_layer(X)\n",
    "            X = self.third_layer(X)\n",
    "            # --------------------------------------------------\n",
    "            return X"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Spróbujmy utworzyć obiekt stworzonej przez nas klasy ConvNet i wykonać jakiś próbny *forward pass* na danych walidacyjnych, aby przekonać się, czy budowa naszej sieci jest poprawna (przynajmniej pod kątem składnowym i numerycznym, tj. czy zgadzają się wymiary tensorów przekazywanych pomiędzy warstwami). Uruchom więc kod z poniższej komórki. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-11-09T10:00:51.514440700Z",
     "start_time": "2023-11-09T10:00:51.482273900Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Przykładowe predykcje modelu na danych walidacyjnych: tensor([[0.3292, 0.0601, 0.0601, 0.0963, 0.0543, 0.0547, 0.1936, 0.0788, 0.0601,\n",
      "         0.0128],\n",
      "        [0.0335, 0.1033, 0.1496, 0.1033, 0.0629, 0.1114, 0.1033, 0.2113, 0.0182,\n",
      "         0.1033],\n",
      "        [0.0523, 0.0016, 0.8134, 0.0232, 0.0045, 0.0061, 0.0248, 0.0232, 0.0232,\n",
      "         0.0276]], dtype=torch.float64, grad_fn=<SliceBackward0>)\n"
     ]
    }
   ],
   "source": [
    "cnn = ConvNet(\n",
    "    input_channels=1,\n",
    "    sample_size=Xval.shape[2],\n",
    "    output_layer_size=num_classes,\n",
    "    kernel_size=3,\n",
    "    padding=0,\n",
    "    stride=1)\n",
    "cnn = cnn.double()\n",
    "pred = cnn(Xval)\n",
    "print(\"Przykładowe predykcje modelu na danych walidacyjnych: \"+str(pred[0:3]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Zbieramy odpowiedzi od każdego wyjściowego neuronu, a każda oznacza prawdopodobieństwo przynależności badanego obrazka do odpowiedniej klasy. Pamiętaj, że nie ma po co przywiązywać się do predykcji otrzymanych na tym etapie - sieć jeszcze nie została niczego nauczona! \n",
    "\n",
    "\n",
    "### Trening sieci neuronowej\n",
    "\n",
    "Napiszmy w takim razie funkcję `train_cnn()`, w której przeprowadzimy trening naszej konwolucyjnej sieci neuronowej. Podobnie, jak poprzednio, wykorzystajmy algorytm optymalizacji Adam (który, jak pamiętamy, potrzebuje odniesienia do parametrów, które ma optymalizować (argument `params` - przekażmy wynik metody `parameters()` na obiekcie naszej klasy ConvNet), stałej uczenia $\\alpha$ (argument `lr` - przekażmy na stałe wartość 0,005), a także stałej regularyzacji $\\lambda$ (argument `weight_decay` - przekażmy na stałe wartość 0,001), a jako funkcję kosztu wykorzystajmy CrossEntropyLoss.\n",
    "\n",
    "Niech zawartość naszej funkcji będzie podobna, jak na poprzednim ćwiczeniu:\n",
    "* Utwórz obiekt klasy ConvNet, a także obiekt zawierający odniesienie do właściwego algorytmu optymalizacji i funkcji kosztu.\n",
    "* Powtarzaj iteracyjnie:\n",
    "    * Przełącz sieć na tryb walidacji, wykonaj *forward pass* na danych walidacyjnych, oblicz wartość kosztu na tych danych i zapisz ją w odpowiedniej zmiennej (pamiętaj o odłączeniu ,,niepotrzebnych'' dla PyTorcha zmiennych metodą `detach()`).\n",
    "    * Przełącz sieć na tryb treningu, wykonaj *forward pass* na danych treningowych, oblicz wartość kosztu na tych danych i zapisz ją w odpowiedniej zmiennej, dokonaj propagacji wstecznej błędu, wykonaj jedną iterację algorytmu optymalizacji, po czym usuń z pamięci obliczone gradienty.\n",
    "    \n",
    "Wyświetlenie zmian kosztu wraz z kolejnymi iteracjami zostało już dla Ciebie napisane. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-11-09T10:47:37.556150100Z",
     "start_time": "2023-11-09T10:47:37.552144500Z"
    }
   },
   "outputs": [],
   "source": [
    "def train_cnn(Xtrain, ytrain, Xval, yval, num_classes, kernel_size=3, padding=0, stride=1, lambdA=0.001, if_plot=True):\n",
    "    \"\"\"\n",
    "    Wykonaj trening swojej sieci neuronowej zdefiniowanej w klasie NeuralNet \n",
    "    na zadanych danych wejściowych i z określoną stałą regularyzacji lambdA. \\n\n",
    "    Argumenty: \\n\n",
    "    - Xtrain - dane treningowe (torch tensor, shape = (num_samples * percentage_train, input_channels, sample_size, sample_size) ), \\n\n",
    "    - ytrain - etykiety do danych treningowych po one-hot-encodingu\n",
    "        (torch tensor, shape = (num_samples * percentage_train, num_classes) ), \\n\n",
    "    - Xval - dane testowe (torch tensor, shape = (num_samples * percentage_val, input_channels, sample_size, sample_size) ), \\n\n",
    "    - yval - etykiety do danych walidacyjnych po one-hot-encodingu\n",
    "        (torch tensor, shape = (num_samples * percentage_val, num_classes) ), \\n\n",
    "    - num_classes - ilość klas, tj. ile różnych wartości pojawia się w etykietach (int, skalar), \\n\n",
    "    - kernel_size - wielkość filtra użytego do konwolucji (int, skalar) (opcjonalnie, domyślnie 3), \\n\n",
    "    - padding - wielkość ,,ramki'' dodawanej do danych przed konwolucją (int, skalar) (opcjonalnie, domyślnie 0), \\n\n",
    "    - stride - co ile pikseli ma być robiona konwolucja (int, skalar) (opcjonalnie, domyślnie 1), \\n\n",
    "    - lambdA - stała regularyzacji (float, skalar) (opcjonalnie, domyślnie 0.001), \\n\n",
    "    - if_plot - Boolean, decyduje, czy po treningu wyświetlić krzywe uczenia (opcjonalnie, domyślnie True). \\n\n",
    "    Zwraca: cnn - wytrenowana sieć neuronowa, zdefiniowana w klasie ConvNet.\n",
    "    \"\"\"\n",
    "    cnn = ConvNet( \n",
    "        input_channels = Xtrain.shape[1], \n",
    "        sample_size = Xtrain.shape[2],\n",
    "        output_layer_size=num_classes,\n",
    "        kernel_size=kernel_size, \n",
    "        padding=padding, \n",
    "        stride=stride\n",
    "        ) \n",
    "    cnn = cnn.double() \n",
    "    loss_train_vec = [] \n",
    "    loss_val_vec = []  \n",
    "    # ---------------------------- UZUPEŁNIJ KOD ---------------------------------------\n",
    "    # Utwórz obiekt związany z funkcją kosztu - CrossEntropyLoss\n",
    "    criterion = torch.nn.CrossEntropyLoss()\n",
    "    # Utwórz obiekt związany z metodą optymalizacji - Adam\n",
    "    optimizer = torch.optim.Adam(params=cnn.parameters(), lr=0.005, weight_decay=lambdA)  \n",
    "    for i in range(1000):\n",
    "        if if_plot:\n",
    "            # Przełącz sieć w tryb walidacji\n",
    "            cnn.eval()\n",
    "            with torch.no_grad(): \n",
    "                # Wykonaj forward pass na danych walidacyjnych\n",
    "                pred = cnn(Xval) \n",
    "                # Oblicz koszt na tych danych\n",
    "                loss_val = criterion(pred, yval) \n",
    "                # Zapisz koszt w odpowiedniej zmiennej (loss_val_vec)\n",
    "                loss_val_vec.append(loss_val.detach().numpy())\n",
    "        # Przełącz sieć w tryb treningu\n",
    "        cnn.train()\n",
    "        # Wykonaj forward pass na danych treningowych\n",
    "        pred = cnn(Xtrain)\n",
    "        # Oblicz koszt na tych danych\n",
    "        loss_train = criterion(pred, ytrain)\n",
    "        # Wykonaj propagację wsteczną kosztu\n",
    "        loss_train.backward() \n",
    "        # Wykonaj 1 iterację algorytmu optymalizacji\n",
    "        optimizer.step()\n",
    "        # Wyzeruj gradienty\n",
    "        optimizer.zero_grad()\n",
    "        # Zapisz koszt do odpowiedniej zmiennej (loss_train_vec)\n",
    "        loss_train_vec.append(loss_train.detach().numpy())\n",
    "    # ------------------------------------------------------------------------\n",
    "    if if_plot:\n",
    "        print(\"  Zakończono trening sieci.\")\n",
    "        fig, ax = plt.subplots()\n",
    "        ax.plot(loss_train_vec, color='k')\n",
    "        ax.plot(loss_val_vec, color='r')\n",
    "        ax.set_title(\"Krzywe uczenia\")\n",
    "        ax.set_xlabel(\"Iteracja\")\n",
    "        ax.set_ylabel(\"Koszt\")\n",
    "        ax.legend([\"Koszt na danych treningowych\", \"Koszt na danych walidacyjnych\"])\n",
    "    return cnn"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Sprawdźmy, jak zmieniły się predykcje dokonane przez naszą sieć, kiedy czegoś ją nauczyliśmy: powinniśmy widzieć większe zróżnicowanie wyników."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-11-09T10:49:01.235352700Z",
     "start_time": "2023-11-09T10:47:38.515175600Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Przykładowe predykcje modelu na danych walidacyjnych (po treningu): tensor([[7.0026e-05, 2.5370e-05, 9.7278e-06, 6.5587e-04, 2.0071e-06, 6.5587e-04,\n",
      "         9.9726e-01, 6.5587e-04, 6.5587e-04, 1.0557e-05],\n",
      "        [3.8457e-02, 1.5287e-03, 4.6501e-02, 2.0064e-03, 1.7867e-03, 1.4336e-01,\n",
      "         7.1592e-01, 1.9494e-03, 1.9851e-03, 4.6501e-02],\n",
      "        [5.5424e-05, 5.2290e-05, 1.1020e-03, 7.6063e-05, 1.1020e-03, 9.9638e-01,\n",
      "         6.9000e-05, 4.3177e-05, 1.1020e-03, 1.3259e-05]], dtype=torch.float64,\n",
      "       grad_fn=<SliceBackward0>)\n"
     ]
    }
   ],
   "source": [
    "nn = train_cnn(\n",
    "    Xtrain=Xtrain, \n",
    "    ytrain=ytrain_ohe, \n",
    "    Xval=Xval, \n",
    "    yval=yval_ohe, \n",
    "    num_classes=num_classes,\n",
    "    if_plot=False)\n",
    "pred = nn(Xval)\n",
    "print(\"Przykładowe predykcje modelu na danych walidacyjnych (po treningu): \"+str(pred[0:3]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Predykcja\n",
    "\n",
    "Kolejnym krokiem jest napisanie funkcji, która analizuje prawdopodobieństwa zwracane przez sieć neuronową i zwraca konkretne numery klas, do których powinny należeć analizowane obrazki - przypomnijmy, że z pomocą `torch.argmax()` należy znaleźć indeks klasy, której sieć przyporządkowała najwyższe prawdopodobieństwo. Uzupełnij więc kod funkcji `pred_cnn()`, która wykona taką operację. <font size=\"2\">Nie zapominaj o argumencie `dim`.</font>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-11-09T10:02:01.750001700Z",
     "start_time": "2023-11-09T10:02:01.745001500Z"
    }
   },
   "outputs": [],
   "source": [
    "def pred_cnn(X, cnn):\n",
    "    \"\"\"\n",
    "    Dokonuje ostatecznej predykcji sieci neuronowej (obiektu NeuralNet) - wskazania klasy - dla danych wejściowych X. \\n\n",
    "    Argumenty: \\n\n",
    "    - X - dane wejściowe (torch tensor, shape = (num_samples, num_features) ), \\n\n",
    "    - nn - model sieci neuronowej, obiekt naszej klasy NeuralNet\n",
    "    Zwraca: pred - numer klasy wg klasyfikatora właściwy dla X (numpy array, shape = (num_samples,) ).\n",
    "    \"\"\"\n",
    "    # --------- UZUPEŁNIJ KOD -------------\n",
    "    pred = torch.argmax(cnn(X), dim=1)\n",
    "    # -------------------------------------\n",
    "    return pred.detach().numpy()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Zobaczmy, jak wyglądają nasze predykcje dla danych walidacyjnych, kiedy jednoznacznie wskazujemy, do której klasy przypisać daną próbkę (a nie operujemy na prawdopodobieństwach):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-11-09T10:02:01.789314800Z",
     "start_time": "2023-11-09T10:02:01.751000800Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Przykładowe predykcje dla danych walidacyjnych: [0 2 1]\n"
     ]
    }
   ],
   "source": [
    "pred = pred_cnn(Xval, cnn)\n",
    "print(\"Przykładowe predykcje dla danych walidacyjnych: \"+str(pred[0:3]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Dobór hiperparametrów z wykorzystaniem biblioteki Optuna\n",
    "\n",
    "Przy budowi sieci konwolucyjnych mamy do czynienia z dużą ilością hiperparametrów - wystarczy przypomnieć *kernel_size*, *padding* czy *stride*. Znalezienie idealnego zestawu hiperparametrów ręcznie (tak, jak robiliśmy to podczas poprzedniego ćwiczenia) może być problematyczne. Użyjemy zatem biblioteki o nazwie Optuna, która pomaga nam w optymalizacji wielu hiperparametrów naraz.\n",
    "\n",
    "Zgodnie z tutorialem [TUTAJ](https://optuna.readthedocs.io/en/stable/tutorial/20_recipes/002_multi_objective.html), musimy najpierw napisać funkcję `objective`, która ma określać to, co chcemy optymalizować --- musi wiedzieć, jakie parametry ma dostosowywać, a także znać miarę, według której można ocenić, czy ,,zbliżamy się'' do celu czy też nie. W naszym przypadku, poszukujemy takiego zestawu hiperparametrów *kernel_size*, *padding* czy *stride*, przy których nasza sieć osiąga możliwie najwyższą dokładność na danych walidacyjnych.\n",
    "\n",
    "Uzupełniony kod funkcji `objective` powinien zawierać więc następujące elementy:\n",
    "* Utworzenie obiektów `trial.suggest_int`, definiujących zakres wartości różnych hiperparametrów, które chcemy przebadać (w naszym przypadku, wszystkie szukane wartości są liczbami całkowitymi).\n",
    "* Przeprowadze *forward pass* na danych walidacyjnych:\n",
    "    * utworzenie obiektu klasy ConvNet i wytrenowanie sieci z pewnym (wybranym przez Optunę) zestawem hiperparametrów,\n",
    "    * dokonanie predykcji (funkcja `pred_cnn`) na danych walidacyjnych,\n",
    "* Obliczenie i zwrócenie dokładności predykcji (przypomnij sobie z poprzednich ćwiczeń trick z `np.where`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-11-09T10:02:01.790314800Z",
     "start_time": "2023-11-09T10:02:01.766969100Z"
    }
   },
   "outputs": [],
   "source": [
    "def objective(trial, Xtrain, ytrain, Xval, yval, num_classes): \n",
    "    \"\"\"\n",
    "    Funkcja określająca, co ma być optymalizowane przez Optunę\n",
    "    Argumenty:\n",
    "    - trial - wewnętrzny argument Optuny\n",
    "    - Xtrain - dane treningowe (torch tensor, shape = (num_samples * percentage_train, input_channels, sample_size, sample_size) ), \\n\n",
    "    - ytrain - etykiety do danych treningowych po one-hot-encodingu\n",
    "        (torch tensor, shape = (num_samples * percentage_train, num_classes) ), \\n\n",
    "    - Xval - dane testowe (torch tensor, shape = (num_samples * percentage_val, input_channels, sample_size, sample_size) ), \\n\n",
    "    - yval - etykiety do danych walidacyjnych po one-hot-encodingu\n",
    "        (torch tensor, shape = (num_samples * percentage_val, num_classes) ), \\n\n",
    "    - num_classes - ilość klas, tj. ile różnych wartości pojawia się w etykietach (int, skalar). \\n\n",
    "    Zwraca: accuracy - dokładność sieci na danych walidacyjnych przy badanych hiperparametrach (skalar, float)\n",
    "    \"\"\"\n",
    "    # ------------------------- UZUPEŁNIJ KOD ------------------------------\n",
    "    # Określ wartości hiperparametru kernel_size, które chcesz przebadać (od 1 do 3, int, bez skali logarytmicznej)\n",
    "    kernel_sizes = trial.suggest_int(\"kernel_size\", 1, 3, log=False)\n",
    "    # Określ wartości hiperparametru padding, które chcesz przebadać (od 1 do 3, int, bez skali logarytmicznej)\n",
    "    paddings = trial.suggest_int(\"padding\", 0, 3, log=False)\n",
    "    # Określ wartości hiperparametru stride, które chcesz przebadać (od 1 do 3, int, bez skali logarytmicznej)\n",
    "    strides = trial.suggest_int(\"stride\", 1, 3, log=False)\n",
    "    # Wytrenuj sieć klasy ConvNet z badanymi hiperparametrami\n",
    "    cnn = train_cnn(\n",
    "          Xtrain=Xtrain, \n",
    "          ytrain=ytrain, \n",
    "          Xval=Xval, \n",
    "          yval=yval, \n",
    "          num_classes=num_classes,\n",
    "          kernel_size=kernel_sizes,\n",
    "          padding=paddings,\n",
    "          stride=strides,\n",
    "          if_plot=False\n",
    "          )\n",
    "    # Dokonaj predykcji na danych walidacyjnych\n",
    "    pred = pred_cnn(Xval, cnn)\n",
    "    # Oblicz dokładność klasyfikacji\n",
    "    accuracy = np.mean(pred==np.where(yval==1)[1]) * 100\n",
    "    # -----------------------------------------------------------------------\n",
    "    return accuracy"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Kolejnym krokiem, po napisaniu funkcji `objective`, jest utworzenie obiektu `study`, który będzie przechowywał wyniki testowania różnych kombinacji wartości hiperparametrów (i dzięki któremu wybierzemy ten optymalny zestaw).\n",
    "* Korzystając z metody `optuna.create_study` (i wskazując w argumencie `direction`, że chcemy maksymalizować optymalizowaną funkcję), utwórz obiekt o nazwie `study`.\n",
    "* Wywołaj na tym obiekcie metodę `optimize` - musisz jej przekazać zdefiniowany wcześniej `objective`, wówczas `study` będzie wiedzieć, co ma optymalizować i w jaki sposób. UWAGA! Musisz zastosować pewien trick opisany [TUTAJ](https://optuna.readthedocs.io/en/stable/faq.html#how-to-define-objective-functions-that-have-own-arguments), aby do funkcji `objective` przekazać własne argumenty $Xtrain$, $ytrain$, $Xval$, $yval$  oraz *num_classes* - proponuję zastosować podejście z lambdą. Jako argument musisz też przekazać ilość prób (losowań zestawu hiperparametrów), które podejmie Optuna (argument `n_trials`) - proponuję w ramach ćwiczeń podać wartość 5, aby czas obliczeń nie był znacząco wydłużony, natomiast w rzeczywistych projektach radzę używać wyższych wartości."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-11-09T10:10:40.289264400Z",
     "start_time": "2023-11-09T10:02:01.776825300Z"
    }
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "[I 2023-11-09 11:02:01,777] A new study created in memory with name: no-name-063d1151-574e-4e34-88c2-177097ba621f\n",
      "[I 2023-11-09 11:04:31,742] Trial 0 finished with value: 83.28690807799443 and parameters: {'kernel_size': 2, 'padding': 1, 'stride': 1}. Best is trial 0 with value: 83.28690807799443.\n",
      "[I 2023-11-09 11:05:18,235] Trial 1 finished with value: 79.10863509749304 and parameters: {'kernel_size': 2, 'padding': 2, 'stride': 2}. Best is trial 0 with value: 83.28690807799443.\n",
      "[I 2023-11-09 11:09:57,503] Trial 2 finished with value: 81.61559888579387 and parameters: {'kernel_size': 3, 'padding': 3, 'stride': 1}. Best is trial 0 with value: 83.28690807799443.\n",
      "[I 2023-11-09 11:10:30,423] Trial 3 finished with value: 38.440111420612816 and parameters: {'kernel_size': 2, 'padding': 3, 'stride': 3}. Best is trial 0 with value: 83.28690807799443.\n",
      "[I 2023-11-09 11:10:40,281] Trial 4 finished with value: 61.28133704735376 and parameters: {'kernel_size': 2, 'padding': 0, 'stride': 3}. Best is trial 0 with value: 83.28690807799443.\n"
     ]
    }
   ],
   "source": [
    "# ------------------------ Dobór hiperparametrów ------------------------\n",
    "# ---------------------------- UZUPEŁNIJ KOD ----------------------------\n",
    "# Utwórz obiekt o nazwie study (użyj optuna.create_study, nie zapominaj o argumencie direction)\n",
    "study = optuna.create_study(direction=\"maximize\")\n",
    "# Optymalizuj hiperparametry kernel_size, padding i stride - wykonaj optimize() na obiektcie study\n",
    "# (funkcję objective przekaż w postaci wyrażenia lambda)\n",
    "study.optimize(lambda trial: objective(\n",
    "    trial,\n",
    "    Xtrain=Xtrain, \n",
    "    ytrain=ytrain_ohe, \n",
    "    Xval=Xval, \n",
    "    yval=yval_ohe, \n",
    "    num_classes=num_classes), \n",
    "    n_trials=5)\n",
    "# ----------------------------------------------------------------------"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Jeśli optymalizacja przebiegła pomyślnie, zobaczmy, jaki zestaw hiperparametrów okazał się najlepszy! Obiekt `study` przechowuje najlepsze wartości w słowniku `best_params` - wystarczy wyszukać po nazwie nadanej hiperparametrowi podczas tworzenia `objective`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-11-09T10:10:40.295780600Z",
     "start_time": "2023-11-09T10:10:40.289264400Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Najwyższa dokładność podczas optymalizacji: 83.28690807799443\n",
      "Najlepszy kernel_size: 2\n",
      "Najlepszy padding: 1\n",
      "Najlepszy stride: 1\n"
     ]
    }
   ],
   "source": [
    "# Wyświetl rezultat optymalizacji\n",
    "print(\"Najwyższa dokładność podczas optymalizacji: \" + str(study.best_value))\n",
    "# ------------------------- UZUPEŁNIJ KOD -------------------------------\n",
    "optimal_kernel_size = study.best_params[\"kernel_size\"]\n",
    "print(\"Najlepszy kernel_size: \" + str(optimal_kernel_size))\n",
    "optimal_padding = study.best_params[\"padding\"]\n",
    "print(\"Najlepszy padding: \" + str(optimal_padding))\n",
    "optimal_stride = study.best_params[\"stride\"]\n",
    "print(\"Najlepszy stride: \" + str(optimal_stride))\n",
    "# -----------------------------------------------------------------------"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Mając wybrane wartości hiperparametrów, czas uruchomić właściwy trening naszej konwolucyjnej sieci neuronowej! Uruchom po prostu poniższy kod."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-11-09T10:16:20.308965900Z",
     "start_time": "2023-11-09T10:14:07.332366700Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "  Zakończono trening sieci.\n"
     ]
    },
    {
     "data": {
      "text/plain": "<Figure size 640x480 with 1 Axes>",
      "image/png": "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"
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# ---------------- Trening sieci --------------\n",
    "cnn = train_cnn(\n",
    "    Xtrain=Xtrain, \n",
    "    ytrain=ytrain_ohe, \n",
    "    Xval=Xval, \n",
    "    yval=yval_ohe, \n",
    "    num_classes=num_classes,\n",
    "    kernel_size=optimal_kernel_size,\n",
    "    padding=optimal_padding,\n",
    "    stride=optimal_stride)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Jak zwykle, sprawdź, czy na wykresie krzywych uczenia nie obserwujesz znaczącego *overfittingu* (czy krzywa dla zestawu walidacyjnego nie rośnie przy dalszym spadku krzywej dla zestawu treningowego). Jeśli wszystko jest w porządku, sprawdźmy dokładność naszego modelu także na danych testowych z zestawu MNIST!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-11-09T10:16:47.870221400Z",
     "start_time": "2023-11-09T10:16:47.790554800Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Dokładność modelu na danych treningowych: 84.78664192949907%\n",
      "Dokładność modelu na danych walidacyjnych: 81.61559888579387%\n",
      "Dokładność modelu na danych testowych: 86.38888888888889%\n"
     ]
    }
   ],
   "source": [
    "# ----------------- Predykcja i sprawdzenie działania -------------------\n",
    "pred = pred_cnn(Xtrain, cnn)\n",
    "accuracy = np.mean(pred==ytrain)\n",
    "print(\"Dokładność modelu na danych treningowych: \"+str(accuracy*100)+'%')\n",
    "pred = pred_cnn(Xval, cnn)\n",
    "accuracy = np.mean(pred==yval)\n",
    "print(\"Dokładność modelu na danych walidacyjnych: \"+str(accuracy*100)+'%')\n",
    "pred = pred_cnn(Xtest, cnn)\n",
    "accuracy = np.mean(pred==ytest)\n",
    "print(\"Dokładność modelu na danych testowych: \"+str(accuracy*100)+'%')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4.2 Wykorzystanie gotowej architektury - AlexNet\n",
    "\n",
    "Badacze tematyką klasyfikacji obrazów zajmują się od lat. Istnieje wiele gotowych architektur konwolucyjnych sieci neuronowych, które zostały wykrenowane do oceny, co znajduje się na przekazany jej obrazku. Jedną z nich jest AlexNet, wytrenowana na dużym zbiorze zdjęć ImageNet, która rozróżnia 1000 klas obiektów na zdjęciach. AlexNet składa się z pięciu warstw konwolucyjnych, trzech wastw *max pooling*, oraz trzech wastw *fully-connected* (czyli liniowych) na końcu, wewnątrz używa funkcji aktywacji ReLU, a jedynie na warstwie wyjściowej - funkcji Softmax. Tak prezentuje się jej architektura:\n",
    "\n",
    "<div align=\"center\">\n",
    "\n",
    "<img src='https://i.imgur.com/PWXzmkw.jpg'/>\n",
    "\n",
    "<font size=\"1\">Grafika: hackmd.io / Alex Krizhevsky, Ilya Sutskever, and Geoffrey Hinton, 2012 </font>\n",
    "</div>\n",
    "\n",
    "Jej implementację (wraz z wagami) można pobrać z pomocą PyTorcha. Możemy ją zaimportować do naszego projektu, pobrać etykiety klas używanych przez ImageNet (z repozytorium twórców ImageNet), a następnie dokonać klasyfikacji dowolnego zdjęcia! Musimy jedynie pamiętać, aby odpowiednio zdjęcie przekształcić: musi ono mieć wymiary 3x224x224 (oczywiście jako zdjęcie RGB, stąd 3 kanały), a także być wstępnie znormalizowane. Poniższy fragment kodu, tworzony w oparciu o tutorial [TUTAJ](https://pytorch.org/hub/pytorch_vision_alexnet/) realizuje właśnie wspomniane wyżej zadania:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-11-09T10:13:02.154149600Z",
     "start_time": "2023-11-09T10:13:00.773706500Z"
    }
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Using cache found in C:\\Users\\Krzysiu/.cache\\torch\\hub\\pytorch_vision_v0.10.0\n",
      "C:\\Users\\Krzysiu\\anaconda3\\envs\\ai_3_8\\lib\\site-packages\\torchvision\\models\\_utils.py:208: UserWarning: The parameter 'pretrained' is deprecated since 0.13 and may be removed in the future, please use 'weights' instead.\n",
      "  warnings.warn(\n",
      "C:\\Users\\Krzysiu\\anaconda3\\envs\\ai_3_8\\lib\\site-packages\\torchvision\\models\\_utils.py:223: UserWarning: Arguments other than a weight enum or `None` for 'weights' are deprecated since 0.13 and may be removed in the future. The current behavior is equivalent to passing `weights=AlexNet_Weights.IMAGENET1K_V1`. You can also use `weights=AlexNet_Weights.DEFAULT` to get the most up-to-date weights.\n",
      "  warnings.warn(msg)\n"
     ]
    }
   ],
   "source": [
    "# ---------------------- Klasyfikacja obrazów z AlexNet -----------------------------\n",
    "# Import niezbędnych bibliotek\n",
    "# ! python -m pip install torch==2.0.1\n",
    "# ! python -m pip install numpy==1.22.3\n",
    "# ! python -m pip install matplotlib==3.4.2\n",
    "# ! python -m pip install wget==3.2\n",
    "# ! python -m pip install PIL\n",
    "# ! python -m pip install torchvision==0.15.2\n",
    "\n",
    "import torch\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "import os\n",
    "import wget\n",
    "from PIL import Image\n",
    "from torchvision import transforms\n",
    "\n",
    "# Importuj AlexNet - w pełni wytrenowany model\n",
    "alexnet = torch.hub.load('pytorch/vision:v0.10.0', 'alexnet', pretrained=True)\n",
    "alexnet.eval()\n",
    "# Pobierz nazwy klas, jakie posiada ImageNet\n",
    "if not os.path.exists(\"utils/imagenet_classes.txt\"):\n",
    "    wget.download(\"https://raw.githubusercontent.com/pytorch/hub/master/imagenet_classes.txt\", out=\"utils/imagenet_classes.txt\")\n",
    "with open(\"utils/imagenet_classes.txt\", \"r\") as f:\n",
    "    categories = [s.strip() for s in f.readlines()]\n",
    "    \n",
    "# Importuj przykładowe zdjęcie psa\n",
    "if not os.path.exists(\"utils/dog.jpg\"): \n",
    "    wget.download(\"https://github.com/pytorch/hub/raw/master/images/dog.jpg\", out=\"utils/dog.jpg\")\n",
    "# Przekształć zdjęcie, by AlexNet mógł je przetworzyć\n",
    "input_image = Image.open(\"utils/dog.jpg\")\n",
    "preprocess = transforms.Compose([\n",
    "    transforms.Resize(256),\n",
    "    transforms.CenterCrop(224),\n",
    "    transforms.ToTensor(),\n",
    "    transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]) ])\n",
    "input_tensor = preprocess(input_image)\n",
    "input_batch = input_tensor.unsqueeze(0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Czas na Ciebie! Dokonaj klasyfikacji pobranego zdjęcia za pomocą AlexNet. Wykonaj *forward pass* na zdjęciu zapisanym w zmiennej `input_batch`, wywołując `alexnet` jak każdy inny model PyTorcha, wyszukaj klasę z najwyżej ocenionym przez AlexNet prawdopodobieństwem (wykorzystaj znów `torch.argmax`) i w pobranym słowniku etykiet `categories` wyszukaj nazwę odpowiedniej klasy. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2023-11-09T10:13:02.248837800Z",
     "start_time": "2023-11-09T10:13:02.154149600Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Predykcja: Samoyed (0.7244771 pewności)\n"
     ]
    }
   ],
   "source": [
    "# ------------------------------ UZUPEŁNIJ KOD --------------------------------\n",
    "# Dokonaj klasyfikacji zdjęcia\n",
    "with torch.no_grad():\n",
    "    output = alexnet(input_batch)\n",
    "probabilities = torch.nn.functional.softmax(output[0], dim=0)\n",
    "pred_class = torch.argmax(probabilities, dim=0)\n",
    "# Odczytaj nazwę klasy\n",
    "pred_category = categories[pred_class]\n",
    "# -----------------------------------------------------------------------------\n",
    "print(\"\\nPredykcja: \" + pred_category + \" (\" + str(probabilities[pred_class].numpy()) + \" pewności)\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Możesz oczywiście samodzielnie poeksperymentować, podmieniając zdjęcia, których klasyfikacji ma dokonać AlexNet.\n",
    "\n",
    "\n",
    "## 5. Pytania kontrolne\n",
    "1. Opisz bardzo krótko, na czym polega zasada działania konwolucyjnych sieci neuronowych.\n",
    "2. Na co wpływa wartość hiperparametru: *kernel_size* / *padding* / *stride* ?\n",
    "3. Z jakich warstw zazwyczaj składa się konwolucyjna sieć neuronowa?"
   ]
  },
  {
   "cell_type": "markdown",
   "source": [
    "1. **Konwolucyjne sieci neuronowe** to sieci, których działanie opiera się na konwolucji. W skrócie, sygnał dostarczony do sieci neuronowej (np. zdjęcie) analizowany jest fragment po fragmencie poprzez wykonanie konwolucji (wymnożenia i zsumowania) tegoż fragmentu z pewnym **filtrem** (ang. *kernel*). Zadaniem filtra jest (poprzez konwolucję) rozpoznanie w analizowanym sygnale pewnych cech (np. krawędzi), a na późniejszych etapie nawet pewnych obiektów.\n",
    "2. - **kernel_size** - wielkość filtra; im większy filtr tym uwzględniają większe obszary; lecz więcej obliczeń jest,\n",
    "   - **padding** - określa, jak „szeroka” ma być dodana (na dowolnej warstwie) do obrazu ramka z zer, co ma przeciwdziałać nadmiernemu zmiejszaniu się wymiarów obrazu wraz z kolejnymi konwolucjami, a także umożliwić dokładniejszą analizę brzegów obrazu,\n",
    "   - **stride** - określa, za ile pikseli filtr wykona następną konwolucję; większy stride powoduje przyspieszenie obliczeń bo o więcej przeskakujemy.\n",
    "3. - **warstwa konwolucyjna** - przeprowadzającą blok po bloku operację konwolucji, wykrywając kolejne cechy\n",
    "   - **warstwa pooling** - redukuje wyhmiary przekazywanych dalej danych\n",
    "   - **warstwa aktywacyjna (ReLU)** - wprowadzająca nieliniowość\n",
    "   - mogą się pojawić **warstwy dropout czy batchnorm**\n",
    "   - **flatten layer** - spłaszcza przekształcony obraz do 1D wektora.\n",
    "   - **kilka warstw liniowych (fully connected layer)** - przetwarzające dane z poprzednich warstw w celu klasyfikacji/regresji \n",
    "   - **warstwa wyjściowa** - z funkcją aktywacji dokonuje ostateczną klasyfikację/regresję."
   ],
   "metadata": {
    "collapsed": false
   }
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "vscode0",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.11"
  },
  "orig_nbformat": 4
 },
 "nbformat": 4,
 "nbformat_minor": 2
}