-
Notifications
You must be signed in to change notification settings - Fork 4
/
addon.tex
375 lines (297 loc) · 17.3 KB
/
addon.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
\chapter{Knjižnica in gradniki za Orange}
V okviru diplomske naloge smo razvili tri ločene komponente za programerje in
končne uporabnike programa Orange. Prva komponenta je
dostopna kot samostojni paket
\verb|simple_wbd|\fnurl{https://pypi.python.org/pypi/simple_wbd/0.5.1}.
Druga in tretja komponenta pa sta združeni v paketu
\verb|orange3-datasets|\fnurl{https://pypi.python.org/pypi/Orange3-Datasets/0.1.3}.
V nalogi razvita programska knjižnica \verb|simple_wbd|
omogoča enostaven dostop do programskega vmesnika indikatorjev in podnebnih
podatkov Svetovne banke. Knjižnico smo implementirali z uporabo čim manjšega
števila odvisnosti in je
% TODO ali je python z veliko
namenjena splošni uporabi v programih napisanih v jeziku Python. Poudarka pri zasnovi knjižnice
\verb|simple_wbd| sta predvsem enostavnost razširitve in zanesljivost. Ta cilja
dosežemo z mehanizmom za vključevanje lastne kode v komponente knjižnice
in mehanizmi za popravljanje ali odstranjevanje okvarjenih podatkov.
Drugi sestavni del je razširitev knjižnice \verb|simple_wbd| s
funkcionalnostmi potrebnimi za lažje delo v programu Orange. To predvsem
zavzema pretvorbo pridobljenih podatkov v podatkovno tabelo Orange in tabelo
numpy. Ta sklop je namenjen skriptnemu delu s programom Orange
\cite{orange_scripting} in je dostopen
kot modul \verb|api_wrapper| v programskem jeziku Python znotraj paketa \verb|orangecontrib.wbd|.
Tretji sestavni del na"se re"sitve je grafični vmesnik za uporabo \verb|api_wrapper| modula.
Namen grafičnega vmesnika je omogočiti dostop do podatkov
programskega vmesnika Svetovne banke znotraj programa Orange za namen obdelave,
analize in iskanja zakonitosti v podatkih s pomo"cjo vizualizacij in ostalih grafi"cnih gradnikov,
ki jih Orange ponuja.
\section{Knjižnica simple\_wbd}
Knjižnica \verb|simple_wbd| programerjem olajša dostop do podatkov
programskega vmesnika Svetovne banke. Glavni namen knjižnice je
združevanje večjega števila zahtev po podatkih in enostavna predstavitev
prejetih rezultatov. Te rezultate je nato iz več dimenzij možno pretvoriti v
dvo-dimenzionalno polje, primerno za uporabo v programu Orange. Glavna
razreda te knjižnice sta \verb|IndicatorAPI| in \verb|ClimateAPI|. Prvi
omogoča pridobivanje podatkov iz programskega vmesnika indikatorjev, drugi pa
s programskega vmesnika podnebnih meritev.
Čeprav za dostop do programskega vmesnika Svetovne banke že obstajajo
rešitve, kot sta knjižnici
\verb|wbdata|\fnurl{https://pypi.python.org/pypi/wbdata/0.2.7} in
\verb|wbpy|\fnurl{https://pypi.python.org/pypi/wbpy/2.0.1}, smo se odločili
za lastno implementacijo podobne knjižnice. Glavni razlog za to je, da
obstoječe rešitve poskušajo čim bolj natančno predstaviti programski
vmesnik Svetovne banke, ne pa olajšati dostop do čim večje količine
podatkov.
Za potrebe te knjižnice smo razvili lastno rešitev za predpomnjenje poizvedb,
saj so se bolj splošne rešitve, kot na primer
\verb|vcrpy|\fnurl{https://pypi.python.org/pypi/vcrpy/1.10.0} in
\verb|requests-cache|\fnurl{https://pypi.python.org/pypi/requests-cache/0.4.12},
izkazale za prepočasne, ko delamo z večjimi količinami podatkov. Naša
rešitev za predpomnjenje izkorišča dejstvo, da je vsaka poizvedba določena le
z naslovom URL in da so vsi odgovori oblike JSON. Za vsak URL naredimo novo
datoteko v sistemskem začasnem imeniku, v kateri hranimo serializirane JSON
podatke. Ker se podatki na programskem vmesniku Svetovne banke redko
posodabljajo, smo za čas veljavnosti začasnih datotek izbrali en teden.
% NOTE: serailizacija je baje uredu beseda:
% http://eprints.fri.uni-lj.si/2711/1/63100205-VALENTIN_KRAGELJ-\
% Pregled_in_analiza_tehnologij_za_serializacijo_objektov.pdf
\subsection{Razred IndicatorAPI}
\label{razered_indicator_api}
\verb|IndicatorAPI| je razred namenjen pridobivanju podatkov indikatorjev
razvoja držav. Ker ima programski vmesnik Svetovne banke omejitev koliko
podatkov lahko prenesemo z eno poizvedbo in nam dovoli tvoriti poizvedbe le za
en indikator hkrati smo napisali razred, ki v ozadju tvori in izvede
poizvedbe za vse strani vseh zahtevanih indikatorjev. Po
prvi poizvedbi za en indikator se na"sa re"sitev sprehodi čez število preostalih strani
% (primer \ref{basic_response})
, ki so na voljo, in pridobljene podatke več
strani združi in predstavi kot rezultat ene same poizvedbe. Ta postopek ponovi
za vse zahtevane indikatorje in njihove rezultate vrne v obliki slovarja, ki
ima za ključ kodo indikatorja posamezne zahteve.
Poleg tega, da skrbi za prenos vseh strani podatkov, tudi beleži število
izvedenih in število potrebnih poizvedb za celoten prenos. Ta števila se
lahko uporablja za prikaz napredka prenosa podatkov.
Za namene uporabe v razredu \verb|IndicatorAPI| smo v knjižnici \verb|simple_wbd|
razvili mehanizme za odpravo nekaterih napak omenjenih v poglavju
\ref{api_gotchas}.
Pri manjkajočih vrednostih držav v poizvedbah za podatke indikatorjev
poskušamo določiti pravilne vrednosti. To naredimo s pomočjo dveh
slovarjev: prvi slika kode držav v imena, drugi pa imena držav v kode. V
primeru manjkajoče vrednosti kode ali imena, poskušamo to prebrati iz enega
od naštetih slovarjev. Če nam ne uspe ugotoviti manjkajočih vrednosti,
trenutni vnos odstranimo iz rezultata poizvedbe.
Drugi tip napak, ki ga lahko delno popravimo, so napačne vrednosti v polju
\verb|date| v poizvedbah za podatke indikatorjev. Ker lahko v temu polju
pričakujemo poljubno besedilo, dela naš pretvornik za polje \verb|date| v
datum, tako da poskuša v datum pretvoriti čim daljšo predpono besedila. Naprimer,
v besedilu ``2005Q1 - 2006Q2'' je najdalj"sa predpona, ki "se ozna"cuje veljaven datum opisan
v dokumentaciji polja {\tt date},
predpona ``2005Q1``.
Če nam ne uspe besedila pretvoriti v veljaven datum, trenutni vnos odstranimo
iz rezultata poizvedbe.
\ \\
Glavne metode ki jih ponuja razred IndicatorAPI so:
\begin{description}
\item [\tt get\_indicators] za pridobivanje seznama indikatorjev s kodami, imeni
in opisi,
\item [\tt get\_countries] za pridobivanje seznama držav z metapodatki,
\item [\tt get\_dataset] za pridobivanje instance razreda \verb|IndicatorDataset|,
ki vsebuje podatke indikatorjev.
\end{description}
Ena izmed lastnosti razreda \verb|IndicatorAPI| je, da mu lahko ob
inicializaciji podamo razred v katerem želimo prejeti rezultat poizvedbe. Ta
razred mora dedovati od osnovnega razreda \verb|IndicatorDataset|. Na ta
način lahko enostavno razširimo funkcionalnost \verb|simple_wbd| knjižnice.
V primeru \ref{indicator_api_extend} vidimo en način za razširitev razreda
\verb|IndicatorDataset|, tako da uporabniku razreda \verb|MyIndicatorAPI| ni
potrebno izrecno podati razreda {\tt MyIndicatorDataset} v konstruktor.
\begin{snippet}
\begin{center}
\begin{lstlisting}
class MyIndicatorDataset(simple_wbd.IndicatorDataset):
def as_numpy(self):
raise NotImplemented()
def as_orange_table(self):
raise NotImplemented()
class MyIndicatorAPI(simple_wbd.IndicatorAPI):
def __init__(self):
super().__init__(MyIndicatorDataset)
\end{lstlisting}
\end{center}
\caption[some]{Primer razširitve osnovnega razreda rezultatov poizvedb.}
\label{indicator_api_extend}
\end{snippet}
\subsubsection{Razred IndicatorDataset}
\label{razred_indicatordatasets}
Razred \verb|IndicatorDataset| je osnovni razred v katerem dobimo zahtevane
podatke indikatorjev. Ta razred vsebuje vse potrebne metode in podatke za
predstavitev rezultatov programskega vmesnika na dva načina: kot slovar
rezultatov poizvedb za posamezen indikator in dvo dimenzionalen seznam.
Posamezna vrednost v teh podatkih je določena z državo, časovno komponento in
kodo indikatorja.
Podatke lahko predstavimo kot dvodimenzionalno polje v dveh oblikah: kot
časovne vrste ali kot podatki držav. Obliko predstavitve izberemo s
parametrom \verb|time_series| metode \verb|as_list|. Za predstavitev obeh oblik
je prva vrstica polja uporabljena kot naslovna vrstica, ki opisuje podatke v
stolpcih.
Ko uporabljamo obliko časovnih vrst, so elementi prve vrstice kartezični
produkt kod indikatorjev in držav. V prvem stolpcu polja pa imamo časovno
komponento podatkov. Na ta način so vsi ostali elementi polja določeni s
časovno komponento, državo in kodo indikatorja.
Ko dostopamo do dvodimezionalnega polja, ki predstavlja podatke držav, pa je v
prvi vrstici kartezični produkt kod indikatorjev in časovne komponente. Prvi
stolpec v tej predstavitvi vsebuje imena držav. Za razliko od predstavitve v
obliki časovnih vrst, v to polje vstavimo "se dodatne stolpce, ki vsebujejo
metapodatke dr"zav iz primera \ref{country_response}: regija \verb|region|,
administrativna regija \verb|adminregion|, višina dohodka \verb|incomeLevel|,
vrsta posojil \verb|lendingType|, geografska širina \verb|latitude|,
geografska dolžina \verb|longitude|. Tudi tukaj so vsi ostali elementi določeni s
časovno komponento, državo in kodo indikatorja.
\subsection{Razred ClimateAPI}
Razred \verb|ClimateAPI| olajša dostop do podnebnih podatkov programskega
vmesnika Svetovne banke. Ta programski vmesnik dovoli poizvedbe po podatkih le
ene vrste meritev za eno vrsto meritvenega obdobja in eno državo. Naš razred
naredi kartezični produkt med vsemi zahtevanimi vrstami meritev, vrstami
meritvenih obdobij in državami. Nato iz tega zgradi in izvede vse poizvedbe
in predstavi podatke kot enotni odgovor. V razredu \verb|ClimateAPI| hranimo
tudi število vseh potrebnih poizvedb in število že izvedenih poizvedb, kar
lahko uporabimo za prikaz napredka prenosa podatkov.
\subsubsection{Razred ClimateDataset}
Razred \verb|ClimateDataset| je osnovni razred v katerem dobimo zahtevane
podatke podnebnih meritev. Vsebuje vse potrebne metode in podatke za
predstavitev rezultatov programskega vmesnika na dva glavna načina: kot
gnezden slovar in dvodimenzionalen seznam. Posamezna vrednost v teh podatkih
je določena z državo, vrsto podatkov in časovno komponento. Poleg omenjenih
načinov predstavitve podatkov lahko dostopamo tudi do neobdelanih podatkov
prejetih iz programskega vmesnika za vsako poizvedbo posebej.
Časovno komponento rezultata sestavljata vrsta meritvenega obdobja in
začetek obdobja meritve. Sestavljeno časovno komponento uporabljamo, da se
izognemo dvoumnim primerom vrednosti začetka obdobja za letni in desetletni
interval meritev. Primera takih dveh časovnih obdobij sta
\verb|'decade - 1990'| in \verb|'year - 1990'|.
Do podatkov predstavljenih z gnezdenim slovarjem lahko dostopamo preko funkcije
\verb|as_dict|. V tej funkciji združimo podatke poizvedb programskega
vmesnika v gnezden slovar s štirimi nivoji gnezdenja: država, vrsta meritev,
vrsta meritvenega obdobja in obdobje meritve. Zadnji nivo gnezdenja vsebuje
vrednosti podnebnih meritev.
Pri predstavitvi podatkov kot dvodimenzionalno polje moramo dve od treh
komponent podatkov (država \verb|'country'|, vrsta podatkov \verb|'type'|,
in časovna komponenta \verb|'interval'|)
združiti in ju skupaj prikazati v vrsticah ali stolpcih. Za razliko od razreda
\verb|IndicatorDataset|, ki podpira le dve obliki prikaza, lahko v razredu
\verb|ClimateDataset| sami določimo katere komponente bodo v stolpcih in
katere v vrsticah. Primer \ref{list_configurations} prikazuje različne mo"znosti izborov komponent.
Spremenljivki \verb|list1| ind \verb|list2| iz
prejšnjega primera prikazujeta privzeto konfiguracijo, kjer imamo v stolpcih
kartezični produkt vrst meritev in vrst meritvenih obdobij, v vrsticah pa
podatke države. Spremenljivka \verb|list4| prikazuje konfiguracijo za
predstavitev v obliki časovnih vrst.
\begin{snippet}
\begin{center}
\begin{lstlisting}
import simple_wbd
api = simple_wbd.ClimateAPI()
climate_dataset = api.get_instrumental(['svn', 'usa', 'aus'])
list1 = ds.as_list()
list2 = ds.as_list(columns=['type', 'interval']) # default value
list3 = ds.as_list(columns=['type'])
list4 = ds.as_list(columns=['type', 'country'])
list5 = ds.as_list(columns=['country'])
\end{lstlisting}
\end{center}
\cprotect
\caption{Prikaz nekaj možnih oblik dvodimezionalnega polja vrednosti.}
\label{list_configurations}
\end{snippet}
\section{Modul api\_wrapper}
Znotraj paketa \verb|orangecontrib.wbd| smo razvili modul \verb|api_wrapper| v
katerem smo razširili razreda \verb|IndicatorDataset| in \verb|ClimateDataset|
na način, ki je prikazan v primeru \ref{indicator_api_extend}. Naša
razširitev obema razredoma doda metodi za pretvorbo podatkov v podatkovno
tabelo Orange in tabelo numpy.
\subsection{Razširitev razreda IndicatorDataset}
Glavne funkcionalnosti, za uporabo programskega vmesnika indikatorjev, so
vključene v naši razširitvi razreda \verb|IndicatorDataset|. To je na prvem
mestu metoda \verb|as_numpy_array|, ki rezultat metode \verb|as_list|
opisane v poglavju \ref{razred_indicatordatasets}, spremeni v polje numpy in odstrani vse
stolpce, ki ne vsebujejo niti ene veljavne vrednosti. Druga metoda pa je
\verb|to_orange_table|, ki podatke dobljene iz metode \verb|as_numpy_array|,
pretvori v podatkovno tabelo Orange. To tabelo lahko oblikuje kot časovno
vrsto ali pa kot seznam držav. %, kot je opisano v poglavju \ref{razred_indicatordatasets}.
Obliko tabele Orange, ki jo želimo izbrati,
določimo s parametrom \verb|time_series|. % TODO: (angl.\ Orange data table).
Ta metoda tudi poskrbi za pravilno nastavljeno domeno\footnote{Domena
``Domain'' je razred v orodju Orange, ki določa tipe in imena značilk in
ciljnih razredov.} podatkov.
\subsection{Razširitev razreda ClimateDataset}
\label{razsiritev_razreda_climatedataset}
Prav tako kot razširitev razreda \verb|IndicatorDatasets|, tudi ta razširitev
doda metodi \verb|as_numpy_array| in \verb|to_orange_table|. Prav tako kot v
razširitvi razreda \verb|IndicatorDatasets|, lahko tudi tukaj s parametrom
\verb|time_series| izberemo obliko tabele Orange. Pri vrednosti parametra
\verb|time_series = False| se nastavi privzeta oblika tabele, prikazana kot
\verb|list1|, sicer pa kot \verb|list3|, iz primera \ref{list_configurations}.
S tem parametrom pa izgubimo možnost poljubne oblike tabele Orange.
\section{Grafični vmesnik}
Programski raz"siritvi \verb|Orange3-DataSets| za
grafični vmesnik programa Orange smo sedaj dodali novo skupino gradnikov imenovano
``Data Sets'' (slika \ref{data_sets_group}). V okviru te naloge smo za skupino
``Data Sets'' izdelali dva ločena gradnika. Prvi gradnik se imenuje ``WB
Climate'' (slika \ref{co2_temp_climate}) in nam preko grafičnega vmesnika
omogoča dostop do podnebnih podatkov Svetovne banke, drugi gradnik pa se
imenuje ``WB Indicators'' (slika \ref{co2_temp_indicator}) in nam
preko grafičnega vmesnika omogoča dostop do podatkov indikatorjev razvoja.
Oba grafična vmesnika sta narejena skladno z vodili grafičnih vmesnikov
programa Orange. To smo dosegli tako, da smo za večino elementov grafičnega
vmesnika uporabili predpripravljene gradnike v paketu \verb|Orange.gui|. Pri
gradnji vmesnikov smo bili pozorni na odzivnost grafičnega vmesnika.
Počasne operacije branja podatkov z interneta smo zato prestavili v ločeno nit.
\begin{figure}
\begin{center}
\includegraphics[width=4cm]{pic/data_sets_group.png}
\end{center}
\caption{Skupina gradnikov Data Sets, ki smo jih razvili v pri"cujo"ci nalogi.}
\label{data_sets_group}
\end{figure}
\subsection{Gradnik WB Indicators}
\verb|WB Indicators| je gradnik programa Orange za dostop do podatkov
programskega vmesnika indikatorjev. Omogoča nam enostavno izbiro
enega ali več indikatorjev in ene ali več držav, za katere želimo dobiti
podatke izbranih indikatorjev. Za lažje iskanje indikatorjev smo v grafičnem
vmesniku dodali dve možnosti presejanja seznama indikatorjev. Pri prvem situ
si lahko izberemo prikaz vseh indikatorjev, pogosto uporabljenih
indikatorjev\footnote{Seznam je na voljo na strani
\url{http://data.worldbank.org/indicator?tab=all}}
ali pa izpostavljenih indikatorjev\footnote{Seznam je na voljo na strani
\url{http://data.worldbank.org/indicator?tab=featured}}. Drugo sito pa je
tekstovno presejanje po poljih: koda {\tt id}, ime {\tt name}, teme {\tt topics} in
viri {\tt sources}.
% TODO: preveri ta stavek
V grafičnem vmesniku si lahko tudi izberemo eno izmed oblik izhodnih podatkov
kot časovne vrste \angl{Time Series} ali podatke držav \angl{Countries},
kot smo ju opisali v razdelku \ref{razred_indicatordatasets}.
Implementirali pa smo tudi prikaz napredka prenosa podatkov s števili vseh in
že izvedenih poizvedb, omenjenih v razdelku \ref{razered_indicator_api}.
\begin{figure}
\begin{center}
\includegraphics[width=13.75cm]{pic/co2_temp_indicator_selection.png}
\end{center}
\caption{Gradnik WB Indicators.}
\label{co2_temp_indicator}
\end{figure}
\subsection{Gradnik WB Climate}
Gradnik za izbiro podnebnih podatkov podatkovnega vmesnika Svetovne banke nam
ponuja možnosti izbire držav, vrste podatkov in vrste meritvenega obdobja.
Prav tako kot v gradniku WB Indicators, lahko tudi tukaj izberemo obliko izhodnih
podatkov. Možni izbiri oblike izhodnih podatkov sta časovne vrste in podatki
držav, kot smo opisali v poglavju \ref{razsiritev_razreda_climatedataset}.
Kot dodatno možnost pa imamo v tem grafičnem vmesniku tudi zastavico, ki
določa ali bomo za države izpisovali imena ali pa kode. Tudi temu grafičnemu
vmesniku smo dodali prikaz napredka prenosa podatkov.
\begin{figure}
\begin{center}
\includegraphics[width=13.75cm]{pic/co2_temp_climate_selection.png}
\end{center}
\caption{Gradnik WB Climate.}
\label{co2_temp_climate}
\end{figure}