Come fare un progetto

Introduzione

Questa guida spiega come creare un progetto completo in Jupyter, in particolare

come scrivere un report col formato Markdown
come assicurarsi che il progetto prodotto sia eseguibile su computer di altri persone
ambienti virtuali
installazione librerie

Challenge

Questo sito prevede delle challenge. Per affrontarle al meglio, potreste svolgere alcune tra le seguenti attività:

VEDI DESCRIZIONE COMPLETA NEL TEMPLATE DEL PROGETTO

Analisi
Pulizia
Integrazione
Arricchimento
- georeferenziazione
- semantico
Ricerca
- Base
- Avanzata
- Calcolo similarità
- Ranking
Predizione
Presentazione
- demo per pubblico non tecnico

Che fare

1 - Scarica lo zip con il template (naviga files online )

Una volta szippato il template, troverai una cartella chiamata NAME-SURNAME-ID, dentro contiene questi file:

NAME-SURNAME-ID
    img
        example.png
    project.ipynb
    markdown.ipynb
    demo.ipynb
    requirements.txt

2 - Rinomina la cartella con i tuoi dati

3 - lancia Jupyter dalla cartella appena rinominata

4 - edita il file project.ipynb , seguendo attentamente le indicazioni nei requisiti tecnici che seguono

Requisiti tecnici

Dimensione dati

Per questioni di praticità, ti conviene usare file di dati con dimensione fino a 50 mb. Se sono più grandi, tagliali.

Testo Markdown

Ti conviene scrivere report in Jupyter stesso, usando la sintassi Markdown descritta nel notebook markdown.ipynb che trovi nello zip del progetto. Quindi tipicamente non serve scrivere altri documenti Word o Latex in parallelo ! L’unica eccezione sono i fogli di calcolo, vedere sezione tabelle in Markdown

Codice Python

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.

Tutto il codice nel notebook del progetto dovrebbe poter essere rieseguibile senza errori su computer altrui. A tal fine:

Il progetto deve essere fatto in Python 3
la versione esatta di tutte le librerie utilizzate deve essere scritta nel file requirements.txt (vedere sotto)

File `requirements.txt`

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.

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.

Versioni dei pacchetti

Per capire che versione avete installata di un dato pacchetto (i.e. pandas), eseguite questo comando:

python3 -m pip show pandas

Se avete installato il pacchetto, dovreste ottenere un output simile a questo:

Name: pandas
Version: 0.23.4
Summary: Powerful data structures for data analysis, time series, and statistics
Home-page: http://pandas.pydata.org
Author: None
Author-email: None
License: BSD
Location: /home/da/.local/lib/python3.5/site-packages
Requires: pytz, python-dateutil, numpy
Required-by: traittypes, pollster, geopandas, fuzzymatcher, bqplot

Chi volesse usare il progetto ed essere sicuro che il tutto funzioni, dovrebbe:

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
installere tutte le librerie specificate in requirements.txt con il comando :
```
python3 -m pip install -r requirements.txt
```
aprire il file project.ipynb in Jupyter e tenterà di rieseguire il codice con il comando Kernel->Restart & run All.

Se tutto è predisposto correttamente, in teoria tutte le celle nel notebook si dovrebbero eseguire senza problemi di sorta.

Interfacce grafiche

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.

Fare attenzione a

mischiare unità di misura diverse
celle vuote
sostituzioni regex sbagliate
usare scale giuste nel grafico (magari serve la logaritmica ?)
problemi di encoding
- 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.
nomi di file
- Windows non distingue tra nomi di file con caratteri maiuscoli e minuscoli
- 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
- evitate nomi di file con spazi, usate invece il trattino -
- Attenti a usare link con percorsi assoluti a file fuori dalla cartella che consegnerete (per es. C:\Users\Paolo\excel.xls)

VIETATO IL DISORDINE!

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.