project-howto.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Come fare un progetto\n",
    "\n",
    "\n",
    "## Introduzione\n",
    "\n",
    "Questa guida spiega come creare un progetto completo in Jupyter, in particolare\n",
    "\n",
    "* come scrivere un report col formato Markdown\n",
    "* come assicurarsi che il progetto prodotto sia eseguibile su computer di altri persone\n",
    "* ambienti virtuali\n",
    "* installazione librerie\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Challenge\n",
    "\n",
    "Questo sito prevede [delle challenge](https://it.softpython.org/#project-challenges). Per affrontarle al meglio, potreste svolgere alcune tra le seguenti attività: \n",
    "\n",
    "[VEDI DESCRIZIONE COMPLETA NEL TEMPLATE DEL PROGETTO](project/project.ipynb#Analisi)\n",
    "\n",
    "- Analisi\n",
    "- Pulizia\n",
    "- Integrazione\n",
    "- Arricchimento\n",
    "    - georeferenziazione\n",
    "    - semantico\n",
    "- Ricerca\n",
    "    - Base\n",
    "    - Avanzata\n",
    "    - Calcolo similarità\n",
    "    - Ranking\n",
    "- Predizione\n",
    "- Presentazione\n",
    "    - demo per pubblico non tecnico"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Che fare\n",
    "\n",
    "1 - Scarica lo [zip con il template](_static/generated/project-template.zip) (naviga [files online](https://github.com/DavidLeoni/softpython-it/tree/master/project)  )\n",
    "\n",
    "Una volta szippato il template, troverai una cartella chiamata `NAME-SURNAME-ID`, dentro contiene questi file: \n",
    "\n",
    "```\n",
    "NAME-SURNAME-ID\n",
    "    img\n",
    "        example.png\n",
    "    project.ipynb \n",
    "    markdown.ipynb\n",
    "    demo.ipynb\n",
    "    requirements.txt\n",
    "```\n",
    "\n",
    "2 - Rinomina la cartella con i tuoi dati\n",
    "\n",
    "3 - lancia Jupyter dalla cartella appena rinominata\n",
    "\n",
    "4 - edita il file `project.ipynb` , **seguendo attentamente le indicazioni** [nei requisiti tecnici che seguono](#Requisiti-tecnici)\n",
    " "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "## Requisiti tecnici\n",
    "\n",
    "### Dimensione dati\n",
    "\n",
    "Per questioni di praticità, ti conviene usare file di dati con dimensione fino a 50 mb. Se sono più grandi, tagliali.\n",
    "\n",
    "### Testo Markdown\n",
    "\n",
    "Ti conviene scrivere  report in Jupyter stesso, usando la sintassi Markdown descritta nel notebook [markdown.ipynb](project/markdown.ipynb) che trovi nello zip del progetto.\n",
    "Quindi tipicamente non serve scrivere altri documenti Word o Latex in parallelo ! \n",
    "L'unica eccezione sono i fogli di calcolo, vedere [sezione tabelle in Markdown](project/markdown.ipynb#Tabelle)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Codice Python\n",
    "\n",
    "<div class=\"alert alert-warning\">\n",
    "\n",
    "**NOTA: non spaventarti se i requisiti sembrano troppo formali: li abbiamo scritti per limitare i problemi tecnici, se poi insorgono comunque pazienza!** L'idea è anche farvi capire cosa succede quando si riesegue codice su computer diversi dal proprio.\n",
    "</div>\n",
    "\n",
    "\n",
    "Tutto il codice nel notebook del progetto dovrebbe poter essere rieseguibile senza errori su computer altrui. A tal fine:\n",
    "\n",
    "* Il progetto deve essere fatto in Python **3**\n",
    "* la versione esatta di tutte le librerie utilizzate deve essere scritta nel file `requirements.txt` (vedere sotto)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### File `requirements.txt`\n",
    "\n",
    "Tipicamente ogni progetto necessita di alcune librerie per funzionare. Invece di installarle una ad una con `pip`, si può comodamente elencarle in un file chiamato `requirements.txt`, e poi dire a `pip` di installarle tutte in un colpo solo.\n",
    "\n",
    "Per capire come compilare il file , guardate il `requirements.txt` di esempio fornito nello zip, in cui sono indicate tutte le librerie usate per i vari tutorial finora, assieme alla versione utilizzata. Se avete bisogno di usare altre librerie e / o cambiare le versioni, editate pure il file a piacere. \n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Versioni dei pacchetti\n",
    "\n",
    "Per capire che versione avete installata di un dato pacchetto (i.e. `pandas`), eseguite questo comando:\n",
    "\n",
    "```bash\n",
    "python3 -m pip show pandas\n",
    "```\n",
    "\n",
    "Se avete installato il pacchetto, dovreste ottenere un output simile a questo: \n",
    "\n",
    "```\n",
    "Name: pandas                                                                                                                                                                                                                             \n",
    "Version: 0.23.4                                                                                                                                                                                                                          \n",
    "Summary: Powerful data structures for data analysis, time series, and statistics                                                                                                                                                         \n",
    "Home-page: http://pandas.pydata.org                                                                                                                                                                                                      \n",
    "Author: None                                                                                                                                                                                                                             \n",
    "Author-email: None                                                                                                                                                                                                                       \n",
    "License: BSD                                                                                                                                                                                                                             \n",
    "Location: /home/da/.local/lib/python3.5/site-packages                                                                                                                                                                                    \n",
    "Requires: pytz, python-dateutil, numpy                                                                                                                                                                                                   \n",
    "Required-by: traittypes, pollster, geopandas, fuzzymatcher, bqplot \n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Chi volesse usare il progetto ed essere sicuro che il tutto funzioni, dovrebbe: \n",
    "\n",
    "- creare sul suo computer un ambiente virtuale nella cartella del progetto e attivarlo. Gli ambienti virtuali servono a isolare le librerie usate da un progetto dal resto del sistema - ai fini del corso non è necessario che tu li crei, ma se vuoi usare python in vari progetti consiglio caldamente di leggere [Ambienti virtuali](installation.ipynb#Fare-progetti-Python-con-gli-ambienti-virtuali)\n",
    "- installere tutte le librerie specificate in `requirements.txt` con il comando :\n",
    "    ```\n",
    "     python3 -m pip install -r requirements.txt\n",
    "    ```\n",
    "- aprire il file `project.ipynb` in Jupyter e tenterà di rieseguire il codice con il comando `Kernel->Restart & run All`. \n",
    "\n",
    "Se tutto è predisposto correttamente, in teoria tutte le celle nel notebook si dovrebbero eseguire senza problemi di sorta. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Interfacce grafiche\n",
    "\n",
    "Se volete implementare dei widget grafici in Jupyter, tenete conto che sviluppare interfacce grafiche per il web richiede parecchie attenzioni - ottenere i risultati desiderati è spesso un lungo processo costituito da innumerevoli prove. Inoltre, i widget di Jupyter al 2018 sono ancora da considerarsi software sperimentale, che spesso non è documentato a sufficienza. Vi conviene non puntare ad avere componenti perfettamente allineati e immagini ottimamente dimensionate, piuttosto programmate in modo corretto le reazioni dei vari componenti."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Fare attenzione a\n",
    "\n",
    "- mischiare unità di misura diverse\n",
    "- celle vuote\n",
    "- sostituzioni regex sbagliate\n",
    "- usare scale giuste nel grafico (magari serve la logaritmica ?) \n",
    "- problemi di encoding\n",
    "    - se salvate file in windows e chi utilizza il progetto ha Linux / Mac, ci potrebbero essere sorprese ! Accertatevi di avere usato encoding uniforme ovunque, sia in lettura che in scrittura.\n",
    "- nomi di file\n",
    "    - Windows non distingue tra nomi di file con caratteri maiuscoli e minuscoli\n",
    "    - esempio: se referenziate in Jupyter un file come `ciao.jpg` e il file su disco si chiama `Ciao.JPG`, il file verrà letto in Windows, ma non in Linux/Mac. Per evitare problemi, mettete sempre i nomi dei file in minuscolo, estensione inclusa come `ciao.jpg`\n",
    "    - evitate nomi di file con spazi, usate invece il trattino `-`\n",
    "    - Attenti a usare link con percorsi assoluti a file fuori dalla cartella che consegnerete (per es. `C:\\Users\\Paolo\\excel.xls`)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-warning\">\n",
    "\n",
    "**VIETATO IL DISORDINE!**\n",
    "\n",
    "Se consegnate cartelle a caso farete arrabbiare chi vi dovrà valutare, perchè dovrà scartabellarsi i file in cerca di roba da eseguire sperando di interpretare le vostre intenzioni. Quindi prima di consegnare a chichessia, date un occhio che sia tutto in ordine e possibilmente fate provare lo zip al componente del vostro gruppo più a digiuno di informatica: se riesce ad installare senza suggerimenti, allora forse ci riuscirà anche il vostro esaminatore.\n",
    "</div>"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Edit Metadata",
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.7.10"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": false,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}