Paikkain on lähinnä Kotka-lomakepohjille tallennettujen museonäytteiden käsittelyyn tarkoitettu apuohjelma. Se lukee syöttötiedostoja (esim. Kotka-mallisia Excel-tiedostoja)  ja lisää taulukkoon koordinaatteja & standardisoi paikannimiä.  Uusin versio voi myös laajentaa henkilönimiä (Kahanpää, J. → Kahanpää, Jere). Lisäämisen logiikka on esitelty alla.

Uutisia

2023-01-18: Paikkain 2.0 julkaistu. Uutena omaisuutena havaitsijan nimien laajennus ja siihen liittyvä datatiedosto erillisenä Drop Target-tiedostona. HUOM: .ini ja .bat -tiedostoja on nyt kutakin toimintatapaa kohden, eli yhteensä 4 kpl: jokainen niistä sisältä tiedostojärjestelmäpolun paikkaimen asennushakemistoon. Jos asennuspaikka on jokin muu kuin Z:/paikkain/ , kaikkia neljää on muokattava.

Käyttö

Sanastoa

• syöttötiedosto = Kotkaan tarkoitettua dataa Excel-muodossa. Tiedosto, joka halutaan georeferoida
• geodata(tiedosto) = Tiedosto, jossa georeferointidata ja -ohjeet paikkaimen ymmärtämässä muodossa.
• sarake = column = pystyrivi

Yksinkertaisin käyttö: tiputa Windowsissa Kotka-Exceli (tai useampi) paikkain_droptarget.bat -kuvakkeen päälle.

Jos haluat katsoa tai muuttaa ohjelman asetuksia (esim. sitä, mistä tiedostosta georeferointidata luetaan tai mikä välilehti käsitellään): katso tiedosto paikkain.ini

INI-tiedostosta voi säätää ohjelman käytöstä. Yleisimmät muutettavat option ovat:

• geodata_sheetname: välilehden (Sheet) nimi, jota ohjelma katsoo. Oletusarvona Specimens.
• geodata_filename: tiedosto, josta georeferointi luetaan
• output_format: tulostiedoston muoto ja käsittelytapa. Vaihtoehdot
  • fast-xlsx. Kirjoittaa uuden xls-tiedoston rivi kerrallaan. Kopioi vain tiedot, ei muotoiluja! Oletusarvo.
  • xlsx. Tekee kopion alkuperäisestä tiedostosta ja muokkaa sitä. Säilyttää alkuperäiset muotoilut, mutta on hyvin hidas, jos tiedoston koko on merkittävä (>300 riviä)
  • (csv. Nopea, mutta importointi Exceliin tai suoraan Kotkaan on altis virheille.  Nykyversiolla on ongelmia, jos kentissä on rivinvaihtoja tai "-merkkejä. )

Ohjelma tallentaa omat toimintatietonsa tiedostoon paikkain.log sen asennushakemistossa. Sieltä voi katsoa ja kopioida mahdolliset virheilmoitukset, jos ohjelman ikkuna tuli suljettua.

UKK/FAQ

• Ohjelma ei tunnista sarakkeita oikein (tiedostoon tulee sama sarake kahdesti): tarkasta, että Kotka-tiedostossa on oikeasti samat sarakkeiden nimet kuin geodata-tiedostossa. Yleisin virhelähde tässä on se, että vanhoissa Kotka-pohjissa on sarakenimiä, joiden lopussa on En (esim. MYLocalityEn)

• Virheilmoitus "Empty values on first row not allowed. Every column should have a name. Check column 1": Tiedostossa on sarakkeita, joiden ylimmässä solussa ei ole sarakkeen nimeä.

• Virheilmoitus "File ... exists. Will not overwrite. Exiting.": Tiedosto, johon tulkittua dataa kirjoitetaan, on jo olemassa. Poista edellinen tiedosto tai anna sille uusi nimi, jos haluat säästää sen.

Muuta

Jos haluat käyttää käyttää useampaa asetustiedostoa eri tilanteita varten: tee uusi INI-tiedosto ja uusi BAT-tiedosto kopioimalla & muokkaamalla. Avaa BAT-tiedosto (se on raakatekstiä) ja vaihda siellä oleva INI-tiedoston nimi haluamaasi.

Miten Paikkain toimii

Paikkain lukee ensin geodatatiedoston. Geodatassa on kolme osaa.  Tämä on helpoin ymmärtää katsomalla olemassa olevaa geodata-tiedostoa.

• Vasemman puolen sarakkeen (columns A..., vakiopohjassa keltaisella): hakuehtoja. Hakee täsmälleen samaa tekstiä, mutta isoja ja pieniä kirjaimia erottelematta. Tyhjä solu hakuehtoja vaatii, että vastaava solu käsiteltävässä datassa on tyhjä. Tähtimerkki  tarkoittaa, että kentälle ei aseteta ehtoja.
  • Esimerkki: ehdot bioprovince: * municipality: Lohja, locality: <tyhjä solu> etsivät rivejä, joilla kuntana on Lohja, mutta locality-kenttä on tyhjä. Maakuntana saa olla mitä tahansa.
• OIkean puolen sarakkeet: kirjoitettavaa dataa.  Jos 2. rivillä lukee "replace", tämä data korvaa alkuperäisen datan. Jos käsittelytapa on "append", uusi tieto lisätään entisen jatkoksi soluun.
• Otsikkorivit:
  1. rivillä on sarakkeiden nimiä. Ne kertovat, mihin syöttötiedoston sarakkeeseen sääntöä sovelletaan tai mihin tulos kirjoitetaan.
  2. rivillä on avainsanoja, jotka kertovat, mitä kyseinen sarake tekee: millainen hakuehto se on ("equal" on tällä hetkellä ainoa hakuehto), tai millä tavalla sen sisältö kirjoitetan lopputulokseen (replace, append, no_output).
  3. rivi on varattu mahdollista tulevaisuuden käyttöä varten. Geodata alkaa 4. riviltä.

Seuraavaksi ohjelma käy läpi sille annetut Kotka-tiedostot. Tiedostosta tehdään kopio (kopion nimessä on osana .georeferenced). Ohjelma soveltaa georeferointisääntöjä kopioon.

Oletusasetuksilla Paikkain kopioi ne tiedot, jotka se korvaa, soluun MYGathering[0][MYCoordinateNotes] (vaihdettavissa INI-tiedostosta).

Oletusasetuksilla Paikkain merkitsee punaisella ne solut, joiden sisältöä se muokkasi

Ohjelman etsi-lisää -logiikka

• Jos rivillä on jo koordinaatit, ei tehdä mitään. (TODO: lisää näissä tunnettu kunta tms.)
• Jos ei löydy vastaavaa paikkatietoa, ei tehdä mitään.
• Jos löytyy useampia vastaavia paikkatietoja, ei tehdä mitään
• Jos löytyy tasan yksi vastaava paikkatieto, korvataan/lisätään syöttörivin paikkatiedot ja koordinaatit paikkatietotaulukon vastaavan rivin oikean puoliskon tiedoilla.

Asennus

Paikkain ei ole ihan helppo asentaa: se on Python-skripti ja vaatii tämän ohjelmointikielen asennuksen koneelle sekä joitain lisäpaketteja.

1. Asenna koneellesi uusin version Python-kielestä. Se löytyy Helsingin yliopiston ohjelmistonjakelusta, eli Windowsissa palkin HY-logo, sen alla Software center. Jakelussa on koko joukko erilaisia Python-versioita. Jos koneellasi ei ole ennestään Pythonia, valitse versio Python 3.7.3 (64-bit). Versionumero voi olla isompi tulevaisuudessa.  Jos sarjanumero ei ole 373, muuta vastaavasti numeroa alla olevissa ohjeissa.
2. hae Paikkain: kopioi itsellesi sopivaan alihakemistoon (oletusarvona Z:\paikkain) kaikki tiedostot tästä Google Drive-hakemistosta.
3. Editoi tiedostoa paikkain_droptarget.bat ja vaihda sinne oikean Python-version nimi/numero ja .py ja .ini-tiedostojen osoite. Tähän käy esim. Notepad-ohjelma.
4. Asenna pari lisäkirjastoia Python-kieleen:
   1. openpyxl - kirjasto: komentoriviltä (Command Prompt) komento C:\Python373\Scripts\pip3 install openpyxl.
   2. tomllib/tomli -kirjasto (tulee vakioasennuksen mukana Python-versiossa 3.11+): C:\Python373\Scripts\pip3 install tomli.
5. Editoi paikkain.ini -tiedostoa ja katso, että asetukset siellä ovat haluamasi. Erityisesti georeferoinnin lähdetiedoston nimi tulee tätä kautta!
6. Editoi  paikkain_droptarget.bat -tiedostoa ja katso, että hakemistopolut ovat siellä oikein. Muokkaista ei tarvita, jos paikkain on asennettu hakemustoon Z:\paikkain.
7. Kokeile, toimiiko ohjelma: tipauta asennushakemistosta löytyvä tiedosto testiaineisto.xlsx Paikkaimen ikonin (paikkain_droptarget.bat) päälle.
8. Luo työpöydällesi linkki tiedostoon paikkain_droptarget.bat. Alt-nappi + raahaus luo linkin. Jatkossa voit tipauttaa Kotka-tiedostot tämän ikonin päälle geoferointia varten.
9. Jos käytät myös henkilönimien täydennystä, tee saman muokkaukset tiedostoihin paikkain_fullnames.ini ja paikkain_fullnames_droptarget.bat

Oletusasetuksilla Paikkain käyttää geodatatiedostoa ./paikka-aineistot/paikkain_src_Finland_sl-jk025.xlsx, joka kuuluu asennuspakettiin. Geodatatiedoston voi vaihtaa asetustiedostosta (paikkain.ini).

Kehitystyö/Development

Kotkan kehitystyö tapahtuu osoitteessa https://github.com/Psilopa/paikkain. Tool source and dev versions are availabl on GitHub.

TODO

• Option to ignore characters: ads to .ini file "characters_to_ignore_in_match: ,;.:   "
• Option to ignore accents: (easier said than done?)

Version history

• v2.9: Major development version.
  • Moved to TOML config files, directory structure reworked.
  • Rewrote the main sheet classes & main script to cleanly seprate input from output: v0.x development versions operated in-place on a single file: v0 to early v2 code included many assumptions about how the input and output files relate to each other (same format etc). Now they should be independent: you can read CSV and write Excel.