Hyönteistietokannan ohjelmointi
Matti Virtala, 2013
1. Johdanto
2. HTML-sivun tekeminen
2.1 Havaintojen haku
2.2. Havaintorivin muotoilu
2.3. Osoiterivin parametrien käyttö
3. Hakutuloksen tallentaminen
4. Ohjelmaesimerkkejä
4.1 Tarkistettavat havainnot
4.2 Karttojen tulostaminen
4.3 Diagrammien piirtäminen
5. Edistynyt UI-ohjelmointi
5.1 LajiSelain
6. Paikallisten tiedostojen käyttäminen
6.1 Node.js
1. Johdanto
Hyönteistietokanta tarjoaa monia tapoja talletettujen tietojen lataamiseksi käyttäjän omalle koneelle. Ehkä helpoin vaihtoehto on käyttää hakulomaketta ja ladata hakutulos omalle koneelleen csv-tiedostona. Tietokanta tarjoaa talletettuihin tietoihin myös ohjelmallisen rajapinnan, jonka avulla on mahdollista tehdä omia ohjelmia tietojen selaamiseen. Tässä dokumentissa selostetaan, miten käyttäjä voi omien ohjelmiensa avulla tulostaa tietoja html-sivulle esim. listauksina, taulukkoina ja karttoina.
2. HTML-sivun tekeminen
Html-sivun ohjelmoinnissa käytetään yleensä JavaScriptiä. Usein pelkkä JavaScript riittää, mutta apuna voidaan käyttää myös erilaisia JavaScript-kirjastoja, joista jQuery on yksi suosituimmista. Tietojen esitysmuotona on yleensä JSON, ja hyönteistietokanta tarjoaakin JSON-rajapinnan tietojen hakemiseen.
Tässä kappaleessa käytämme esimerkkinä html-sivua, joka listaa uusimmat tietokantaan talletetut harvinaiset havainnot. Varsinainen HavaintoListaus.html-sivu on itsessään hyvin yksinkertainen:
Havaintojen haku suoritetaan jQuery-kirjaston valmiiden funktioiden avulla. Yksittäinen havaintorivin sisältö muodostetaan tiedoston HavainnonTulostus.js avulla, ja lopulliset havaintorivit tulostetaan koodin Havaintolistaus.js avulla ja sijoitetaan sivulle 'havlista' elementtiin. Sivun ulkoasu määritellään tiedostossa Havaintolistaus.css.
Seuraavassa selostetaan sivun toimintaa hieman tarkemmin.
2.1. Havaintojen haku
Hyönteistietokannan tarjoama rajapinta havaintojen hakemiseen on kuvattu dokumentissa EntDatabase_Remote_API.html. Rajapinnan monipuolisin komento on search. select-parametrin arvoksi annetaan lista niistä havainnon kentistä, jotka halutaan mukaan hakutulokseen. Käytössä ovat seuraavat kentät:
obsID
storingDate
family
genus
species
speciesFreq
uhex
region
county
locality
coordinates
startDay
startMonth
endDay
endMonth
year
habitat
method
observer
det
detYear
detMethod
note
reliability
checked
Muilla parametreilla määritellään varsinaiset hakuehdot. Alla olevassa taulukossa on listattu käytettävissä olevat hakuparametrit:
| field | example |
|---|---|
| obsID | obsID=1234-5678-9012-3456 |
| storingDate | storingDate=2003* storingDate=2003-05* |
| order | order=col |
| family | family=Carabidae |
| genus | genus=Amara |
| species | species=aulica |
| region | region=Oba |
| county | county=Oulu |
| locality | locality=Hietasaari |
| coordinates | coordinates=721:342 |
| startDay | startDay=1 |
| startMonth | startMonth=6 |
| endDay | endDay=31 |
| endMonth | endMonth=6 |
| startYear | startYear=2012 |
| endYear | endYear=2012 |
| habitat | habitat=niitty habitat=*niitty |
| method | method=ansakuopilla method=ansa* |
| observer | observer=M. Virtala observer=*Virtala |
| det | det=*Virtala |
| detYear | detYear=2012 |
| detMethod | detMethod=lab. määritys |
| reliability | reliability=0 |
| checked | checked=Tarkistettava* |
| speciesFreq | speciesFreq=60 |
| uhex | uhex='NT' |
Lisäksi voidaan käyttää parametria userCondition, jonka avulla voi määritellä monimutkaisempia hakuehtoja.
Tässä esimerkkisovelluksessa haluamme listata kaikki edellisen viikon aikana tehdyt, pistearvoltaan yli 60 p. olevat perhoshavainnot.
1.
Muuttujan order arvoksi asetetaan order=lep.
2.
select-parametrissa otamme mukaan kaikki havainnon kentät.
3.
userCondition-parametrille on määritelty valmiiksi joitakin hakua helpottavia arvoja, jotka ovat seuraavat:
userCondition=today // tänään tehdyt havainnot
userCondition=yesterday // eilen tehdyt havainnot
userCondition=yesterday+ // eilen ja tänään tehdyt havainnot
userCondition=week // viime viikon havainnot
Varsinainen hakukomento on seuraavanlainen:
Haku suoritetaan jQueryn getJSON-metodin avulla. Tuloksena saadut havainnot ovat taulukossa data. Tuloksena voi olla jokin seuraavista vaihtoehdoista:
1. Hakutulos on tyhjä. Tällöin data.length == 0.
2. Haussa tapahtui jokin virhe. Virheilmoitus löytyy tällöin data-taulukon ensimmäisen alkion error-muuttujasta data[0].error.
3. hakutuloksena on yksi tai useampia havaintoja. Tällöin ohjelma käy läpi taulukon data havainnot ja poimii niistä halutut kentät.
Ohjelmakoodi on seuraavanlainen:
Havaintorivit kootaan taulukoksi, joka sijoitetaan html-sivun 'havlista'-elementtiin. Tässä vaiheessa on hyödyllistä katsoa, miltä tuloksena saatu sivu näyttää:
Yksittäinen havaintorivi tehdään getTableRow() metodin avulla.
2.2. Havaintorivin muotoilu
Metodin getTableRow() argumentteina ovat havainnon tietokentät. Metodissa poimitaan kentät halutussa järjestyksessä ja muodostetaan niistä taulukkorivi <tr>...</tr>.
Tiedosto HavainnonTulostus.js sisältää lisäksi funktiot getExxCount(), getDevStage(), getAccuracy(), getJavascriptCoordinates(), karttapaikka() ja showInfo(), joita on käytetty apuna havaintorivin muodostamisessa.
2.3. Osoiterivin parametrien käyttö
Kun hakusivu on talletettu omalle koneelle, sivuun voi viitata selaimen osoiterivillä esim. seuraavasti:
file:///C:/HavaintoListaus/HavaintoListaus.html
Edellä
olevassa esimerkissä haku kohdistettiin perhosiin asettamalla JavaScript-koodissa arvo order=lep. Tämän voi korvata ilmoittamalla haluttu hyönteislahko suoraan selaimen osoiterivillä seuraavasti:
file:///C:/HavaintoListaus/HavaintoListaus.html?order=lep
Tällöin samaa hakusivua voi käyttää myös muiden hyönteislahkojen havaintojen hakuun. Tämän voi tehdä seuraavanlaisen JavaScript-koodin avulla:
3. Hakutuloksen tallentaminen
Hakutuloksena saatuja havaintoja ei voi suoraan tallentaa tiedostoksi, koska se ei ole selaimelle sallittua. Yksinkertaisin tapa kiertää tämä rajoitus on kopioida sivu leikepäydälle ja tallettaa sen sisältö sitä kautta
tiedostoksi.
Esimerkiksi Hyönteistietokannan API-dokumentaation
GetCounts.html-sivu käyttää seuraavanlaista JavaScript-koodia:
Tuloksena on sivu, joka sisältää maakiitäjäisistä tehtyjen havaintojen lukumäärät vuodesta 1990 alkaen:
Näitä lukuja ei siis voi suoraan ohjeman avulla tallettaa, mutta ne voi kopioida sivulta leikepöydälle ja tallettaa sitä kautta haluamaansa tiedostoon.
4. Ohjelmaesimerkkejä
4.1. Tarkistettavat havainnot
Kappaleen 2 esimerkkilistausta voidaan helposti muokata omia tarpeita vastaavaksi. Hakuehtoja voi muuttaa ja havainnot voi tulostaa sivulle eri tavalla. Jos haluaa listata esimerkiksi vuoden 2013 tarkistettavat perhoshavainnot, sen voi tehdä seuraavanlaisen hakuehdon avulla:
Havaintolistaus on nyt seuraavanlainen:
4.2. Karttojen tulostaminen
Levinneisyyskarttojen tekemistä on selostettu dokumentissa Levinneisyyskartat.html.
4.3. Diagrammien piirtäminen
Diagrammien piirtämistä on selostettu tarkemmin dokumentissa Diagrammit.html.
5. Edistynyt UI-ohjelmointi
Edellä esitellyt sovellukset perustuvat yksinkertaisiin html-sivuihin, joihin sisältöä on lisätty JavaScript-koodin avulla.
Html-sivujen tekemiseen on mahdollista käyttää myös erityisiä UI-kirjastoja. Esimerkiksi jQuery UI-kirjasto sisältää useita hyödyllisiä html-komponentteja. Ehkä kaikkein monipuolisin UI-kirjasto on kuitenkin Sencha Ext JS. Seuraavassa kappaleessa esitellään Ext JS-sovellus, joka käyttää hyväkseen sekä Hyönteistietokannan että Kuvapankin ohjelmallisia rajapintoja.
5.1. LajiSelain
LajiSelaimen avulla voi selata tiettyyn hyönteislahkoon kuuluvien lajien levinneisyystietoja, havaintoja ja Kuvapankin kuvia:
Sovelluksen pääsivu LajiSelain.html on äärimmäisen yksinkertainen:
Kaikki sivun komponentit ja niiden toiminta määritellään JavaScriptin avulla tiedostossa speciesbrowser.js. Ext JS-sovelluksen tekeminen vaatii hieman perehtymistä järjestelmän toimintaan, mutta monipuoliset UI-komponentit palkitsevat kyllä käyttäjän vaivannäön. Esimerkkinä LajiSelain-sovelluksen toiminnasta on alla koodi, joka suoritetaan, kun lahko-valintalaatikosta valitaan esim. 'Heteroptera':
Yllä valitun lahkon heimot haetaan Hyönteistietokannan JSON-rajapinnan kautta määrittelemällä FamilyData-tietomallille proxy, jonka osoite on
http://hyonteiset.luomus.fi/insects/json?op=getFamilies&order=Heteroptera&orderBy=family
Heimojen nimet lisätään sitten sivun vasemman reunan puurakenteeseen.
Kun puurakenteesta valitaan tietty laji, Hyönteistietokannasta haetaan lajin levinneisyyspisteet ja havainnot, joiden avulla tehdään levinneisyyskartta ja havaintotaulukko. Valitun lajin kuvat saadaan Kuvapankin JSON-rajapinnan kautta getSpeciesImages() toiminnon avulla seuraavasti:
LajiSelain-sovelluksen toimintaa ei
tässä selosteta tarkemmin, mutta toivon mukaan sitä voi käyttää esimerkkinä siitä, miten Hyönteistietokannan JSON-rajapinnan avulla voidaan tehdä edistyneitä Ext JS-sovelluksia.
6. Paikallisten tiedostojen käyttäminen
Koska turvallisuussyistä selain ei voi suoraan lukea tai kirjoittaa käyttäjän koneen paikallisia tiedostoja, jouduimme kappaleessa 3 kopioimaan hakutuloksen tiedostoon leikepöydän kautta. Esittelemme seuraavassa Node.js-ohjelman, jonka avulla voidaan sekä lukea että kirjoittaa koneen paikallisia tiedostoja.
6.1. Node.js
Viime aikoihin asti JavaScript-kieltä on käytetty lähinnä selaimessa, mutta nykyään sitä on mahdollista käyttää myös www-palvelimien ohjelmoinnissa. Node.js on hyvin suosittu JavaScriptiä käyttävä alusta www-palvelimen toteuttamiseen. Se perustuu Chrome-selaimen V8 virtuaalikoneeseen, joka on erittäin nopea. Node.js on erityisen kiinnostava siksi, että, että sen avulla on mahdollista käyttää myös koneen paikallisia resursseja.
Node.js-ohjelman voi ladata osoitteesta http://nodejs.org/download/. Kun Node.js on asennettu, voimme suorittaa halutun JavaScript-tiedoston, esim. myscript.js, yksinkertaisesti tietokoneen komentoriviltä seuraavasti:
C:\Node\MyApps>node myscript.js
Koska Node.js pystyy lukemaan ja kirjoittamaan paikallisia tiedostoja, voimme sen avulla hakea Hyönteistietokannasta tietoja ja tallettaa ne suoraan omalle koneellemme. Seuraavassa on Node.js-skripti getdata.js, joka hakee tietokannasta samat maakiitäjäistiedot kuin kappaleessa 3 ja tallettaa ne tiedostoon counts.csv:
Tiedoston counts.csv voi nyt helposti avata esim. Exceliin:
Tiedostojen käsittelyn lisäksi Node.js:ään on laadittu suuri joukko eri tarkoituksiin tehtyjä lisämoduleja (ks. https://npmjs.org/ or https://nodejsmodules.org/). Seuraavat linkit tarjoavat lisätietoa Node.js-ohjelmoinnista:
http://nodejs.org/api/
http://howtonode.org/
http://nodetoolbox.com/
http://www.nodecloud.org/
https://hacks.mozilla.org/category/node-js/
http://stackoverflow.com/questions/tagged/node.js
http://www.scoop.it/t/nodejs-code