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 farle al meglio, dovrete aver dimostrato di aver fatto almeno alcune tra le seguenti attività:

  • Analisi

  • Pulizia

  • Integrazione

  • Arricchimento

    • georeferenziazione

    • semantico

  • Ricerca

    • Base

    • Avanzata

    • Calcolo similarità

    • Ranking

  • Predizione

  • Presentazione

    • demo per pubblico non tecnico

VEDI DESCRIZIONE COMPLETA ATTIVITA’ NEL TEMPLATE DEL PROGETTO

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 trovate 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 spaventatevi se i requisiti sembrano troppo formali: li ho 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 es 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 è un mestiere tedioso - ottenere i risultati desiderati è spesso un lungo processo costituito da innumerevoli prove e altrettanti fallimenti. 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 mi consegnerete (per es. C:\Users\Paolo\excel.xls)

VIETATO IL DISORDINE!

DETESTO quando mi si consegnano cartelle a caso, perchè poi devo andare a scartabellarmi 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 che meno ne sa di informatica. Se riesce ad installare lui/lei senza suggerimenti, allora forse ci riuscirò anch’io.