Suunnitteludokumentti

Transkriptio

1 Suunnitteludokumentti Populous Helsinki Ohjelmistotuotantoprojekti HELSINGIN YLIOPISTO Tietojenkäsittelytieteen laitos

2 Kurssi Ohjelmistotuotantoprojekti (6 ov) Projektiryhmä Heli Borg Markus Heinonen Ville Luolajan-Mikkola Olli Orajärvi Asiakas Petteri Hintsanen Johtoryhmä Juha Taina Turjo Tuohiniemi Kotisivu Versiohistoria Versio Päiväys Tehdyt muutokset Ensimmäinen versio Toinen versio FTR-versio Lopullinen versio

3 Sisältö i 1 Johdanto Tuotteen tausta ja tarkoitus Dokumentin rakenne Terminologia Järjestelmän yleiskuvaus Toteutus- ja toimintaympäristö Ohjelmointikielet Rajaukset Ohjelmointikäytännöt C Java Arkkitehtuurikuvaus Komponenttien väliset suhteet Suorittava kerros Kontrollikerros Käyttöliittymäkerros Luokkien väliset suhteet Luokkakaavio Verkkokommunikaatio Palvelupyynnöt Viestien koodaus Ydin-komponentti Rajapinta Enumeraattorit ICore-rajapinta IStatusCallback-rajapinta Core-luokka CoreFactory-luokka Parameters-luokka Log-luokka

4 ii Globaalit määrittelyt Pedigree-komponentti Rajapinta Enumeraattorit IPedigree-rajapinta Pedigree-luokka PedigreeFactory-luokka FamilyTree-luokka RecombTree-luokka Segment-luokka Individual-luokka Marker-komponentti Rajapinta Enumeraattorit IMarker-rajapinta Marker-luokka MarkerFactory-luokka Tekstikäyttöliittymä-komponentti Rajapinta CursesUI-luokka Palvelinkomponentti Rajapinta Server-luokka ServerStub-luokka ServerJob-luokka ServerClient-luokka Asiakaskomponentti Rajapinta ClientFrame-luokka JobControl-luokka Job-luokka ServerInfo-luokka Hakemistorakenne

5 3.10 Tiedostoformaatit pedigree chrom param server.conf Käyttöliittymä Komentorivikäyttöliittymä Ncurses Graafinen käyttöliittymä (Java Swing) Käyttötapaus 1: Sokeritaudin periytymisen tutkiminen Käyttötapaus 2: Aineistoa artikkelia varten Käyttötapaus 3: Sokeritautigeenitutkimuksen uusiminen Käyttötapaus 4: Geeniparametrien toimivuuden testaus Käyttötapaus 5: Väärät tutkimustiedot Käyttötapaus 6: Ämmänsaaren väestön kehittyminen Käyttötapaus 7: Siirtolaisten vaikutus Ämmänsaaren geeniperimään iii

6 1 Johdanto 1 Tämä suunnitteludokumentti kuvaa toteutettavan Populous -populaatiosimulaatorin teknisen toteutuksen näkökulmasta. Suunnitteludokumentti toimii järjestelmätoteutuksen ohjeena ja siinä kuvataan yksityiskohtaisesti järjestelmän arkkitehtuuri, komponentit, tietosisältö sekä toteutettavat käyttöliittymät. Suunnitteludokumentin perustana käytetään Populous-projektin määrittelydokumenttia Tuotteen tausta ja tarkoitus Populous on syksyn 2004 aikana Helsingin yliopiston Tietojenkäsittelytieteen laitoksella Ohjelmistotuotantoprojekti -kurssin puitteissa toteutettava projekti. Projektissa tuotetaan populaation kehityksen simulointiin käytettävän ohjelmiston osa. Projektin pohjana on HIIT -perustutkimusyksikössä käytössä oleva populaatiosimulaattori. Nykyisen populaatiosimulaattorin toiminnassa ilmenneet ongelmat ovat lähtökohtana Populous-projektille. Simulaattori on tehty väitöskirjatyön pohjalta ja muokattu moneen kertaan. Nyt tämän ohjelmistotuotantoprojektin avulla halutaan selkeyttää käytössä olevaa ohjelmaa. Nykyisellään tuote koostuu neljästä erillisestä osasta: genped, chrom, simco ja markertool, sekä skripteistä, joilla niiden toiminta on yhdistetty. Tässä projektissa korvataan käytössä olevan ohjelmiston kaksi ensimmäistä osaa tavoitteena prosessin suoraviivaistaminen. Lisäksi laaditaan käyttöliittymä ohjelmiston käytön helpottamiseksi. Erilaisten geenikartoitusmenetelmien ja genomin rakenteen selvittämiseen tarkoitettujen menetelmien testaamisessa simuloidut aineistot ovat välttämättömiä. Simulointiprosessin lähtökohtana on tyypillisesti yksi populaatioisolaatti. Populaatio koostuu pienestä joukosta yksilöitä, joista populaatio kasvaa annettuun loppukokoon saakka. Simulaatio jäljittelee perusjoukon geenien periytymistä jälkeläisille ja sukupolvelta toiselle laajenemisprosessin kuluessa. 1.2 Dokumentin rakenne Luvussa kaksi kuvataan projektin yhteydessä toteutettavaa järjestelmää yleisesti. Yleiskuvaukseen sisältyy järjestelmän toteutus- ja toimintaympäristön selvittäminen, käytettävien ohjelmointikielten määritteleminen ja toteutettavan ohjelman rajaus. Luku kolme kuvaa toteutettavan järjestelmän arkkitehtuurin. Se sisältää yksityiskohtaisen kuvauksen kustakin järjestelmän komponentista ja niiden välisistä suhteista. Ensimmäinen aliluku käsittelee kamponenttien välisiä suhteita ja toinen luokkien välisiä suhteita. Aliluvut kuvaavat ydin, pedigree, marker, käyttöliittymä, palvelin ja asiakaskomponenttien rajapintoja ja luokkia. Luvussa 4 kuvataan projektin yhteydessä toteutettavat käyttöliittymät, joita on kolme: komentorivikäyttöliittymä, tekstipohjainen Ncurses -käyttöliittymä ja Javan Swing -pakkausta käyttäen toteutettava graafinen käyttöliittymä.

7 2 1.3 Terminologia Dokumentissa käytetyt termit ja lyhenteet: Alipopulaatio: Populaatio voi jakautua useisiin populaatioisolaatteihin. Alipopulaatioiden välillä pariutumistodennäköisyys on pienempi kuin alipopulaation sisällä. Emäspari: Kromosomeissa sijaitsevat toisiaan vastaavat dna:n rakenneosat. (engl. basepair). Genomi: Perimä eli eliön tai solun sisältämä perinnöllinen informaatio. HIIT -perustutkimusyksikkö: Tietojenkäsittelytieteen laitoksen yhteydessä toimiva Helsingin yliopiston ja Teknillisen korkeakoulun yhteisen Helsinki Institute for Information Technology -tutkimuslaitoksen (HIIT) perustutkimusyksikkö (BRU).Yksikön keskeisiä tutkimusalueita ovat data-analyysi, adaptiivinen laskenta ja laskennallinen neurotiede. Iterointi: Iteroidaan, eli ajetaan koko simulaatiotyö samoilla parametreilla useita kertoja. Alatapaus Marker-iterointi. Loppupopulaatio: Populaatiosimulaation lopussa olevan viimeisen sukupolven edustajat muodostavat loppupopulaation. Marker-iterointi: Iteroidaan simulaatiotyötä, mutta otetaan Pedigree- tiedostot valmiina, jolloin iteroidaan ainoastaan Simcoa ja Markertoolia, ts. sukupuu pysyy staattisena. Markkeri: Kromosomissa paikka, jossa esiintyy yksilöiden välistä vaihtelua. Markertool: Valmis itsenäinen binääri, joka ottaa otoksen markereita kromosomitiedosta käyttäen myös Simcon tulostetta apunaan. Erikoistapauksessa (vanhemmat mukaan otokseen -optio) tarvitaan syötteenä lisäksi viimeisen sukupolven sukupuu ja toiseksi viimeisen sukupolven kromosomitiedosto. Ncurses: Yleisesti käytössä oleva kirjasto tekstitilaisen terminaali-ikkunan sisällön ja toimintojen määrittelyyn. Tässä projektissa NCURSES:lla on tarkoitus toteuttaa yksinkertainen ikkunamainen käyttöliittymä, jolla voidaan suorittaa rinnakkaista ajoa lukuunottamatta samat käyttötapaukset kuin Javalla toteutettava käyttöliittymä. Pedigree: Ohjelman komponentti, jonka vastuulla on sukupuun ja sen yksilöiden genotyyppien generointi (rekombinoimalla), sekä sukupolven kromosomit. Perustajajäsen: Populaation ensimmäisen sukupolven edustaja, jonka perimästä simulaatio lähtee liikkeelle. Populaatio: Joukko saman lajin yksilöitä, jotka elävät samalla alueella. Populaatioisolaatti: Eristäytynyt populaatio, jossa ei geenivaihtoa ulkopuolelta.

8 Siirtolainen: Muualta populaatioon tuleva yksilö, jonka geeniperimä poikkeaa ko. populaatioisolaatin perimästä. Simco: Valmis itsenäinen binääri, joka generoi halutun määrän SNP- tai STR-markereita (kohtia geenissä, joita voidaan tarkastetella erojen varalta). Toimii itsenäisesti. SNP -mutaatio: Lajin sisäinen, nukleotidisekvenssin tietyssä kohdassa esiintyvä vaihtelu. Muutokset tapahtuvat ainoastaan yhdessä emäsparissa.(engl. SNP = Single Nucleotide Polymorphism). STR-markkerit: Lyhyellä peräkkäisellä kromosomijaksolla toistuvat markkerit. Vaihtelu muodostuu jakson toistojen lukumäärästä. (engl. STR = Short Tandem Repeat). Tekijäinvaihto: Kromosomien risteäminen jakautumisen yhteydessä. (engl. cross-over). Tree: Pelkkä sukupuu ilman perintöainesta. 3 2 Järjestelmän yleiskuvaus Tässä luvussa kuvataan toteutettava järjestelmää. Järjestelmän liittyminen nykyisin käytössä oleviin järjestelmän osiin on esitetty kuvassa 1. Ohjelma muodostuu sisäisestä osasta, sekä siihen liittyvistä käyttöliittymistä ja se käyttää simcoa ja markertoolia ulkoisina ohjelmina. Sisäinen osa vastaa sukupuu- ja geeniaineiston käsittelystä yhdessä ulkoisten komponenttien kanssa. Ohjelmaa voi käyttää kolmella eri tavalla. Komentorivikäyttöliittymällä yhdellä komennolla voidaan ajaa koko simulaatio läpi. Tekstipohjainen curses käyttöliittymä, joka pohjautuu tekstikenttiin ja valintalistoihin, tarjoaa komentoriviä helpomman mahdollisuuden ajaa ohjelmaa tekstipohjaisessa ympäristössä. Asiakasohjelman tarkoituksena on ohjata ja hallita yhdessä tai useammassa palvelimessa ajettavia simulaatioita ja koota tulokset asiakasohjelman koneelle. Asiakasohjelmassa on graafinen käyttöliittymä. Kaikki käyttöliittymät toteutetaan englanninkielisinä. 2.1 Toteutus- ja toimintaympäristö Koska järjestelmä suunnitellaan nimenomaan Tietojenkäsittelytieteen laitoksella toimivan HIIT-perustutkimusyksikön käyttöön, se suunnitellaan toimimaan laitoksen Linuxkäyttöympäristössä. Asiakkaan ja palvelimen välinen kommunikaatio tehdään TCP/IP:llä. Palvelimeen on asetettava IP-osoitteet, joista tulevien asiakkaiden sallitaan ottaa yhteys ja suorittaa töitä, ja samoin asiakaskomponenttiin on määriteltävä käytettävien palvelimien IP-osoitteet ja portit. Palvelimelle lähetetään palvelupyyntö, jonka se välittää palvelinkoneen ytimelle.

9 4 Kuva 1: Toteutettava järjestelmä. Asiakas kyselee prosessin edistymistä tietyin väliajoin ja päivittää saadun tiedon käyttöliittymäänsä. 2.2 Ohjelmointikielet Populous ohjelmoidaan Tietojenkäsittelytieteen laitoksen Linux-ympäristössä pääasiassa C++- kielellä käyttäen sen standardikirjastoja. Poikkeuksen tähän tekevät asiakasohjelma, joka kirjoitetaan Java versiolla ja tekstikäyttöliittymä, joka toteutetaan C-kielisellä NCurses- kirjastolla. 2.3 Rajaukset Uuden populous -komponentin tulosteen on oltava markertoolin ymmärtämässä muodossa, jotta näitä voidaan käyttää yhdessä. Toisaalta myös markertoolin tulosteen on sovelluttava uuden ohjelman syötteeksi. Tällä mahdollistetaan simulaation jatkaminen ottamalla tuloksesta uusi otos seuraavan ajon perustajajäseniksi.

10 5 2.4 Ohjelmointikäytännöt Yhteisesti sovituilla ohjelmakoodin tyylisäännöillä ja ohjelmointikäytännöillä pyritään ehkäisemään tavallisimpien virheiden syntymistä ja parantamaan koodin luettavuutta. Yhteiset kaikkia ohjelmiston osia koskevat tyylisäännöt on lueteltu tässä luvussa, eri ohjelmointikieliä koskevat erityissäännöt omissa aliluvuissaan. Sisennys Sisennyksessä käytetään sarkain-merkkiä. Sarkaimen kokoa välilyönteinä ei kiinnitetä, mutta ulkoasun on oltava siisti ja yhdenmukainen neljän merkin sarkainkoolla C++ Luokkien nimeäminen Luokkien nimessä jokainen sana alkaa isolla kirjaimella, loput kirjaimet ovat pieniä, esim. CoreFactory. Lisäksi rajapintaluokkien eteen lisätään iso kirjain I, esim. ICore. Metodien nimeäminen Metodit nimetään kuten luokat. Paikallisten muuttujien nimeäminen Kaikki muuttujan nimessä olevat sanat kirjoitetaan pienellä ja ne erotetaan toisistaan merkillä _. Luokan kenttien nimeäminen Julkiset luokan kentät nimetään kuten paikalliset muuttujat. Privaattien kenttien nimeen lisätään alkuun merkki _. Lähdekooditiedostot Luokan esittely tehdään otsikkotiedostossa, jonka nimen alkuosa on sama kuin luokan nimi, mutta pienillä kirjaimilla. Tiedoston pääte on.h, esim. corefactory.h. Luokan toteutustiedosto nimetään samalla tavalla, mutta tiedoston pääte on.cpp. Yleiset luokkiin kuulumattomien lähdekooditiedostojen nimet kirjoitetaan pienillä kirjaimilla ja pääte on joko.h tai cpp. Luokan määrittelyjärjestys Luokkaa määritellessä ensimmäisenä määritellään sen julkiset ominaisuudet, ensin metodit, sitten kentät ja lopuksi konstruktorit ja destruktori. Tämän jälkeen määritellään suojatut ja privaatit metodit, näissä samoin ensin metodit ja sitten kentät. Luokan pakolliset ominaisuudet Kaikkien luokkiin on sisällytettävä vähintäänkin oletuskonstruktori, kopiokonstruktori, virtuaalinen destruktori ja sijoitusoperaatio; rajapintaluokkiin riittää virtuaalisen destruktorin määrittely ja toteutus. Mikäli jokin ominaisuus halutaan estää, voidaan se toteuttaa privaattina.

11 Metodien const-määreet Kaikissa mahdollisissa metodien ja näiden parametrien määrityksissä käytetään const-määrettä aina kun se vain on mahdollista. Mikäli parametriin ei metodin sisällä tehdä muutoksia, se määritellään const-tyyppiseksi; samoin mikäli metodi ei muuta olion kenttien arvoja, se määritellään const-tyyppiseksi. Otsikkotiedostojen käyttö Jokaiseen tiedostoon sisällytetään ainoastaan ne otsikkotiedostot, joita siinä käytetään. Samoin kaikki siinä käytetyt otsikkotiedostot on sisällytettävä, esim. sisällytyksen delegoimista toiseen otsikkotiedostoon ei tehdä. Ohjelmistoon itseensä kuuluvat otsikkotiedostot sisällytetään ensin, vasta näiden jälkeen standardikirjastoon kuuluvat. Standardikirjaston käyttö Ohjelmiston toteutuksessa käytetään C++:n standardikirjastoa, jonka kaikki luokat ovat std-nimiavaruudessa. Kaikkiin luokkien nimiin kirjoitetaan näkyviin sen täydellinen nimi, eli esim. merkkijono on std::string. Nimiavaruus Populous Kaikki luokat ja metodit toteutetaan nimiavaruuden Populous alle main-metodia lukuunottamatta Java Ohjelmiston Javalla toteutettavissa osissa käytetään Sunin julkaisemaa Code Conventions for the Java Programmin Language -dokumentin mukaista tyyliä niiltä osin kuin ne eivät ole ristiriidassa tämän projektin yleisten ohjelmointikäytäntöjen kanssa.. Ohjeet löytyvät osoitteesta 3 Arkkitehtuurikuvaus Tässä kappaleessa kuvataan toteutettavan järjestelmän arkkitehtuuri. Järjestelmän komponentit ja niiden väliset suhteet on selvitetään omissa aliluvuissaan. Arkkitehtuurikaavio on esitetty kuvassa Komponenttien väliset suhteet Ohjelmisto on jaettu hyvin itsenäisiin komponentteihin, joiden väliset rajapinnat ovat mahdollisimman yksinkertaisia. Komponenttien välinen liikenne on minimoitu. Komponenttien kutsu- ja käyttöjärjestys on määrätty ja kukin komponentti on yhteydessä hierarkiassa ylempänä olevaan komponenttiin ainoastaan callback-rajapinnan kautta, jolloin ohjelmiston suoritus etenee puumaisesti.

12 7 Kuva 2: Toteutettavan järjestelmän arkkitehtuuri. Ohjelmisto voidaan jakaa kolmeen kerrokseen: suorittava kerros (Pedigree, Marker), kontrollikerros (Ydin) ja käyttöliittymäkerros (Tekstikäyttöliittymä, Asiakas-Palvelin). Aliluvuissa on kuvattu kunkin kerroksen tehtävä Suorittava kerros Suorittavassa kerroksessa olevat komponentit Pedigree ja Marker tekevät varsinaisen simulaation eri osavaiheet. Pedigree-komponentti luo sukupuun ja siihen mahdollisesti liitettävät kromosomitiedot, ja Marker luo niiden ja Marker-komponentin sisällä luotujen markkerien pohjalta simulaation lopullisen tuloksen. Marker-komponentti tarvitsee aina syötteekseen Pedigree-komponentin tuloksen, eli näitä komponentteja ei voida yhden simulaation aikana ajaa rinnakkain. Kerroksen komponentit saavat suorittamiseen tarvittavat tiedot parametrinaan. Komponentit tiedottavat työn etenemisestä niitä kutsunutta Ydin-komponenttia callback-rajapinnan kautta.

13 Kontrollikerros Kontrollikerros hallinnoi yhden työn suorituksen. Se ajaa suorittavan kerroksen komponentit järjestyksessä Pedigree, Marker, välittää tietoa työn etenemisestä ydintä kutsuneelle komponentille callback-rajapinnan kautta, ja työn päätyttyä huolehtii, että ylimääräiset työn ohessa luodut väliaikaistiedostot tuhotaan. Ydin saa parametrinaan kaikki työn suorittamiseen tarvittavat arvot, ja tiedon siitä minkä tyyppistä työtä ollaan suorittamassa: generoidaan ainoastaan sukupuu halutuin sukupolvin ilman kromosomeja (#1), generoidaa sukupuut ja siihen kromosomit (#2), suoritetaan simulaatio kokonaisuudessaan (#3) tai suoritetaan ainoastaan Marker parametrina annetulla sukupuulla ja kromosomidatalla, mahdollisesti iteroiden (#4). Yksinkertaisimmassa tapauksessa #1 suoritetaan ainoastaan Pedigree, ja tästäkin ainoastaan ensimmäinen puoli. Tuloksena saadaan pelkkä sukupuu ilman kromosomitietoja. Tapaus #2:ssa suoritetaan Pedigree kokonaisuudessaan. Tulokseksi saadaan sukupuu ja kromosomitiedot. Yleisimmässä tapauksessa #3 suoritetaan sekä Pedigree että Marker kertaalleen alusta loppuun. Tulokseksi saadaan markertool-ohjelman tuloste. Välituloksien säilytys määritellään parametreissa. Tapaus #4:ssä suoritetaan ainoastaan Marker-komponentti. Tällöin Pedigree-komponentin generoimat sukupuu- ja kromosomitiedostot annetaan parametrina, jolloin Pedigree-vaihe voidaan ohittaa. Myös iterointi on mahdolista, jolloin Marker suoritetaan samoilla parametreilla haluttu määrä kertoja, säilyttäen jokaisen ajokerran tulokset omassa tiedostossaan Käyttöliittymäkerros Ohjelmaan rakennetaan kolme käyttöliittymää: teksti-, komentorivi- sekä Javapohjainen Swing-käyttöliittymä. Komentorivikäyttöliittymä ei ole interaktiivinen ja on tarkoitettu ohjelman tehokkaaseen laajentamiseen ja käyttöön. Swing-käyttöliittymä on pääasiallinen käyttöliittymä, ja se mahdollistaa etäkäytön. Tekstikäyttöliittymä rakennetaan toissijaiseksi käyttöliittymäksi. Tekstikäyttöliittymästä tulee minimalistinen ja minimalistisen interaktiivinen. Ohjelmasta pystytään ainoastaan terminoimaan käynnissä oleva työ sekä päivittämään sen statustietoa näytölle, mutta ei muuta, ts. käyttöliittymä on lukkiutunut suorituksen aikana. Ajo terminoidaan control-c:llä, jolle rakennetaan erityinen käsittelijä, joka keskeyttää työn suorituksen siististi. Ohjelma ei siis tällöin kaadu tai sammu suoraan. Palvelinkomponenttia varten luodaan oma prosessi lyhyen vasteajan takaamiseksi. Palvelinprosessissa palvelin ottaa vastaan uusia yhteydenottopyyntöjä asiakkailta, ylläpitää töiden ja asiakkaiden listaa, ja käynnistää uusien töiden ajoja tarpeen mukaan. Palvelinja ydinprosessin välinen kommunikaatio tapahtuu putkilla, joilla ydin-prosessin päässä palvelinkomponenttiin kuuluva olio välittää palvelimelta tulleet viestit ytimen palvelupyynnöiksi ja ytimeltä tulevat tilatiedot palvelinprosessille. Ytimelle prosessiraja ei näy,

14 vaan sen kannalta rajapinta on sama kuin ytimen ja esim. tekstikäyttöliittymän rajapinta. Asiakkaan ja palvelimen välinen kommunikaatio tehdään TCP/IP-protokollaa käyttäen. Palvelimeen on asetettava IP-osoitteet, joista tulevien asiakkaiden sallitaan ottaa yhteys ja suorittaa töitä, ja samoin asiakaskomponenttiin on määriteltävä käytettävien palvelimien IP-osoitteet ja portit. Asiakas on komponenteista aina aktiivinen osapuoli, eikä palvelin lähetä asiakkaalle mitään ilman asiakkaan tekemää palvelupyyntöä Luokkien väliset suhteet Tässä luvussa kuvataan luokkien välisiä suhteita. Luokkakaaviossa esitetään kaikki toteutettavan järjestelmän luokat. Lisäksi kuvataan luokkien välistä verkkokommunikaatiota ja palvelupyyntöjä sekä viestien koodausta tarkemmin Luokkakaavio Koko järjestelmän luokkakaavio on esitetty kuvassa 3. Luokkakaaviossa ovat ainoastaan järjestelmän luokat, eli siitä puuttuvat globaalit main- ja sig_handler-funktiot ja globaali muuttuja process_state. Nämä kuuluvat loogisesti Ydin-komponenttiin, ja main-funktio voi kutsua joko Core-, CursesUI- tai Server-luokkaa Verkkokommunikaatio Asiakkaan ja palvelimen välinen yhteys toteutetaan TCP/IP-protokollaa käyttäen. Tässä luvussa listataan palvelimen asiakkailleen tarjoamat palvelut sekä kuvataan niiden suorittamiseen käytettävä protokolla. Asiakasohjelmaan määritellään käytettävien palvelimien IP-osoitteet ja portit. Samaa palvelinta voi yhtä aikaa käyttää useampikin asiakas, mutta töitä suoritetaan rinnakkain vain korkeintaan palvelimessa määritelty määrä. Suoritusta odottavat työt palvelin asettaa jonoon, josta niitä haetaan suoritettavaksi saapumisjärjestyksessä. Kaikissa palvelupyynnöissä lähettää asiakas palvelimelle viestin, johon palvelin vastaa välittömästi. Palvelupyyntöjen kuvaukset ovat muodossa, jossa ensimmäisenä on palvelun nimi, sen jälkeen palvelimelle lähetettävät parametrit ja kaksoispisteen jälkeen palvelimelta saadut tulokset Palvelupyynnöt QUEUELEN : <int> Tällä palvelupyynnöllä asiakas voi selvittää palvelimen kuormitusasteen. Palautettu arvo on jonossa tai suorituksessa olevien töiden lukumäärä. Mikäli jonossa ei ole paikkoja vapaana eikä enempiä töitä voide heti käynnistää suoritettavaksi, on paluuarvo -1.

15 10 Kuva 3: Toteutettavan järjestelmän luokkakaavio START <parametrit> : <ID> Työ luodaan tällä palvelupyynnöllä. Paluuarvona asiakas saa avaimen, jolla se voi viitata myöhemmissä palvelupyynnöissä oikeaan työhön. Työ käynnistetään heti kun palvelimella vapautuu paikka. Virhetilanteessa paluuarvo on negatiivinen. QUEUEPOS <ID> : <int> Mikäli parametrina annettu työ on ajossa, annetaan paluuarvona 0. Jos se on vielä jonossa odottamassa ajoa, annetaan työn sijainti jonossa. Mikäli työtä ei löydy, palautetaan -1. READY <ID> : <int> Tällä palvelupyynnöllä asiakkaan on aika ajoin tarkistettava työn edistyminen. Jos työtä ei olla vielä aloitettu, on paluuarvona 0. Valmiin työn kohdalla paluuarvo on 100, ja mikäli työn suoritus on vielä kesken, on paluuarvo jokin kokonaisluku välillä Virhetilanteessa paluuarvo on -1. Onnistuneen suorituksen aikana palautettava arvo ei ole koskaan pienempi kuin aikaisemmalla kerralla

16 saatu arvo. Paluuarvoa voidaan siten käyttää käyttöliittymässä suoraan prosenttiarvona työn suorituksen etenemisestä. RESULTS <ID> : <tulokset> Kun palvelupyyntö READY on palauttanut arvon 100, voidaan tällä palvelupyynnöllä hakea työn tulokset. Kun tulokset on toimitettu, poistetaan tulokset palvelimelta. Samoin asiakkaan ja palvelimen välisen yhteyden katkeaminen poistaa mahdolliset tulokset. KILL <ID> : <boolean> Työn voi keskeyttää tai perua tällä palvelupyynnöllä. Jos työtä ei ole vielä suoritettu, se joko keskeytetään ja kaikki sen väliaikaistiedot tuhotaan tai se poistetaan jonosta. Valmistuneen työn kohdalla tulokset poistetaan. STATUS : <tietoa> Palauttaa yleistä tilatietoa työn vaiheesta, käytetään ainoastaan virheiden etsimiseen. Palautettu arvo on kuvaava merkkijono, jonka varsinaista muotoa ei määritellä Viestien koodaus Palvelupyyntöjen viestit koodataan seuraavan määritelmän mukaan. Määritelmässä käytetyt symbolit on merkattu <> väliin. Jokaisen symbolin määritelmässä ::= oikealla puolella oleva arvo on symbolin sisältö, vaihtoehtoiset sisällöt on eritelty merkillä. Samantyyppisen symbolin moninkertaa merkitään merkillä *, jolloin sitä edeltävää symbolia voi mielivaltainen määrä. Jokainen symboli voidaan lukea auki siten, että kaikki sen määritelmässä olevat symbolit korvataan niiden määritelmällä, ja toistaen sama kaikille symboleille kunnes jäljellä on vain vakioita tai selkokielinen selitys sisällöstä. #-merkin jälkeen oleva teksti on vapaamuotoinen tekstiselitys, jolla tarkennetaan symbolin merkitystä ja luonnetta. Merkkivakiot on merkitty yksinkertaisten lainausmerkkien väliin ja ovat tyypiltään <char>. <request> ::= <req_queuelen> <req_start> <req_queuepos> <req_ready> <req_results> <req_kill> <req_status> <req_queuelen> ::= L <req_start> ::= S <params> <req_queuepos> ::= P <id> <req_ready> ::= R <id> <req_results> ::= G <id> <req_kill> ::= K <id> <req_status> ::= D <id> <reply> ::= <rep_queuelen> <rep_start> <rep_queuepos> <rep_ready> <rep_results> <req_kill> <req_status>

17 12 <rep_queuelen> ::= L <int32> <rep_start> ::= S <id> <rep_queuepos> ::= P <int32> <rep_ready> ::= R <int32> <rep_results> ::= G <results> <rep_kill> ::= K <boolean> <rep_status> ::= D <data> <params> ::= <data> # data sisältää parametrilistan parametritiedoston muodossa (kts ) <results> ::= <ldata> # data sisältää tiedostot koodattuna samoin kuin parametritiedostossa (kts ) <data> ::= <length> <char>* <length> ::= <uint32> <id> ::= <uint32> <int32> ::= 32-bittinen etumerkillinen kokonaisluku, big-endian-muodossa <uint32> ::= 32-bittinen etumerkitön kokonaisluku, big-endian-muodossa <char> ::= 8-bittinen merkki ASCII-merkistössä <boolean> ::= 8 bittiä; = true, = false Esimerkiksi palvelupyynnön READY ensimmäinen viesti olisi merkki R ja 32- bittinen etumerkitön kokonaisluku, jonka arvo on työn ID; yhteensä 40 bittiä. (Luetaan määritelmästä: <request> -> <req_ready> -> char- R <id> -> char- R <uint32> -> char- R 32-bittinen etumerkitön kokonaisluku, big-endian-muodossa.) Vastaava paluuviesti olisi merkki R ja 32-bittinen etumerkillinen kokonaisluku, jonka arvo on työn edistymistä kuvaava luku; samoin 40 bittiä. 3.3 Ydin-komponentti Ydin on koko ohjelman toimintaa koordinoiva ja ohjaava komponentti. Ydin saa viestejä joko suoraan käyttäjältä (komentorivikäyttöliittymä), tekstipohjaiselta käyttöliittymältä tai Palvelin-komponentilta, jota asiakasohjelma käyttää verkon yli.

18 13 Kuva 4: Ydin-komponentin luokat. Ydin toimii välikerroksena käyttäjän ja simulaation suorittavien komponenttien välissä. Ydin ohjaa Pedigree- ja Marker-komponentin käyttöä, sekä välittää tietoa käyttäjälle käyttöliittymän kautta ja poistaa väliaikaisia tiedostoja ja ylläpitää tiedon välitystä. Ydin-komponenttiin on myös sisällytetty globaalit luokat Parameters ja Log, sekä kaikki

19 mahdolliset globaalit funktiot ja muuttujat. Perusteena tälle on, että Ydin-komponentin katsotaan olevan keskeisin osa sovellusta. Ytimen luokat ja näiden väliset suhteet on esitetty kuvassa Rajapinta Ydin tarjoaa palveluita tekstikäyttöliittymälle ja palvelimelle. Ydin sisältää simulaation ajojen hallinnan, koordinoinnin, lokin, virhetilanteiden hallinnan ja delegoinnin ohjelman sisällä sekä tulosten ja tulosteiden ohjaamisen käyttäjälle. Ytimen on tarkoitus piilottaa mahdollisimman paljon populaatiosimulaatioteknisistä asioista ja tarjota keskitetysti esim. parametrien parseroinnin, validoinnin (Parameters-luokka) ja simulaatiokomponenttien kutsun (Core-luokka). Tyypillisessä simulaatiokäyttötapauksessa käyttäjä antaa käyttöliittymän kautta halutut parametrit. Käyttöliittymä syöttää parametrit Parameters-olioon, joka annetaan ytimelle. Parameters-luokka parsii syötteet ja tarkistaa niiden arvoalueet ja eheyden. Ydin määrittää parametrien pohjalta simulaatiotyön. Tämän takia ydin tarjoaa käyttöliittymille hyvin pelkistetyn rajapinnan, joka koostuu pääasiassa parametrien vastaanottamisesta. Näin käyttöliittymät voidaan erottaa simulaatiosta ja sen toteutuksesta mahdollisimman tehokkaasti. int RunSimulation(TSimType type, Parameters params) Luovutetaan parametrijoukko ytimelle suoritusta varten. Parametri type määrittelee minkä tyyppinen simulaatio halutaan suorittaa. Määritellään rajapinnassa ICore. int main(int argc, char *argv[]) Ohjelmiston globaali pääfunktio. Tätä kutsutaan ensimmäiseksi kun ohjelma käynnistetään komentoriviltä. Tunnistaa parametreista halutaanko ohjelmaa ajaa palvelimena, tekstikäyttöliittymänä vai suoraan suorittaa simulaatio, ja käynnistää sen mukaisen komponentin, josta ohjelman suoritus varsinaisesti alkaa. void Update(TStatus status) Callback-metodi, jolla Pedigree- ja Marker-komponentit lähettävät tietoa edistymisestään. Määritellään rajapinnassa IStatusCallback Enumeraattorit TStatus Kuvaa simulaatiotyön tilaa. Mahdolliset arvot ovat: INIT = työtä ei vielä aloitettu, TREE = sukupuu luotu, PEDIGREE = kromosomit luotu sukupuuhun, MARKER = markkerit luotu, READY = työ valmis

20 15 Koodi Selitys -1 Määrittelemätön virhe -2 Tiedoston lukuvirhe (käyttöoikeus) -3 Tiedoston lukuvirhe (muu) -4 Tiedoston kirjoitusvirhe (käyttöoikeus) -5 Tiedoston kirjoitusvirhe (muu) Taulukko 1: ICore::RunSimulation()-virhekoodit TProcessState Kuvaa prosessin tilaa. Mahdolliset arvot ovat: INIT = alkutila, FORK = prosessin haarautuminen käynnissä, SERVER = palvelinprosessi, NCURSES = tekstikäyttöliittymä, CORE = prosessi suorittaa simulaatiota TSimType Kuvaa simulaation tyyppiä. Mahdolliset arvot ovat: FULL = täysi ajo alusta loppuun, TREE = luodaan pelkkä sukupuu Pedigree-komponentissa, PEDIGREE = ajetaan vain Pedigree-komponentti, PROCESS = suoritetaan pelkkä Marker-komponentti valmiille sukupuulle ICore-rajapinta ICore on ydinkomponentin kutsurajapinta. Metodit public int RunSimulation(TSimType type, Parameters &params) Metodilla käynnistetään simulaation suoritus. Onnistuneen suorituksen yhteydessä paluuarvo on 0, virhetilanteessa negatiivinen. Virhekoodit on lueteltu taulukossa IStatusCallback-rajapinta IStatusCallback luo rajapinnan, jolla välitetään tietoa työn edistymisestä kutsuneelle taholle. Metodit public virtual void Update(TStatus status) Callback-metodilla, jolla kontrolli voidaan siirtää hetkeksi työn suorituksesta hierarkiassa ylemmälle kerrokselle. Parametri status on enumeraattorityyppiä TStatus.

21 Core-luokka Core on Ydin-komponentin pääluokka. Core hoitaa töiden koordinoinnin ja jakaa annettujen parametrien mukaan tehtävät Pedigree- ja Marker- komponenteille. Metodit public int RunSimulation(TSimType type, Parameters &params) Ajaa simulaation. Saa syötteenään valmiin ja tarkistetun Parameters- olion. Parametri type on enumeraattorityyppiä TSimType ja määrittelee simulaation tyypin. antaen CoreFactory-luokka CoreFactory on tehdasolio, jolla luodaan ICore-tyyppisiä olioita. Metodit public static ICore* Construct() Luo ICore-tyyppisen olion. Varsinaisen toteuttavan luokan valinta tehdään metodin sisällä. Virhetilanteessa palautetun osoittimen arvo on Parameters-luokka Parameters-luokka kapseloi ohjelman parametrit. Se luodaan ja täytetään käyttöliittymätasolla ja annetaan ytimelle simulaation suoritusta varten. Komentoriviltä käytettäessä käyttöliittymätaso on ydin itse, jolloin se kontruoidaan siellä. Se ei varsinaisesti kuulu Ydin-komponenttiin, vaan kulkee suorituksen mukana komponentista toiseen. Parameters-olion voi konstruoida joko käyttämällä kontruktoria, joka saa syötteenään char-merkkijonotaulukossa kaikki parametrit (komentoriviltä ja palvelimesta) tai attribuutit voi täyttää itse (tekstikäyttöliittymä). Luonnin jälkeen tulee kutsua Check-metodia, joka tarkistaa parametri-olion parametrit. Parameters-oliossa kaikilla kentillä on asetettuna arvo, jota käytetään. Oletusarvoja käytettäessä on Parameters-oliota luovan metodin tehtävä asettaa nämä arvot oikein. Metodit public int Check(TSimType type) Tarkistaa parametrina saamansa tyypin perusteella siihen liittyvien parametrien arvojen oikeellisuuden ja funktionaalisen eheyden. Metodin paluuarvo on onnistuneella suorituksella 0 ja virhetilanteessa negatiivinen. Virhekoodit on listattu taulukossa 2.

22 17 Koodi Selitys -1 Määrittelemätön virhe -2 Arvoaluevirhe jossakin parametrissa -3 Kaikkia vaadittuja parametreja ei asetettu -4 Ristiriita parametreissa Taulukko 2: Parameters::Check()-virhekoodit Metodin parametri type on enumeraattorityyppiä TSimType. public Parameters(char **argv) Konstruktori, jonka paramtrina saa ohjelmiston komentoriviparametrit ilman ensimmäistä, ohjelman ajotiedoston sisältävää kenttää. Konstruktori pyrkii löytämään merkkijonoista kaikki mahdolliset määritellyt parametrit ja asettamaan arvonsa sen mukaisesti. Virhetilanteissa osa arvoista jää asettamatta, ja oliota luovan onkin kutsuttava Check-metodia vielä tämän jälkeen varmistaakseen luonnin onnistumisen ja että kaikki tarvittavat parametrit oli määritelty. Attribuutit Parameters-luokan attribuutit on listattu taulukossa 3. Parametrit tarkistetaan Check-metdissa simulaatiomoodin mukaan. Moodit: 1 = TREE 2 = PEDIGREE 3 = FULL 4 = MARKER Kustakin parametrista on mainittu, tarkistetaanko se tietyssä moodissa. Vain yhden moodin parametrit tarkistetaan, muista ei välitetä Log-luokka Log on ohjelmiston lokitiedostoon kirjoittamiseen tarkoitettu luokka. Jokaisella lokirivillä on rivin tyyppi, jotka ovat vakavimmasta vähiten vakavaan Critical, Error, Info ja Debug, sekä vapaamuotoinen, mutta yksirivinen tekstiselitys. Lokitiedosto kirjoitetaan hakemistoon, josta ohjelmisto on suoritettu. Log on Singleton-tyyppinen olio, josta luodaan tasan yksi ilmentymä prosessia kohti. Metodit public static Log& GetInstance(bool debug = false) Palauttaa Log-olion. Luo tarvittaessa uuden Log-olion. Debug-tilan voi asettaa päälle ainoastaan ensimmäisellä kutsukerralla, eikä sitä voi kesken ohjelman suorituksen asettaa pois päältä.

23 18 Tyyppi Muuttuja (1,2,3,4 = Sallittu arvoalue Tarkistushuomioita pakollinen) bool savetrees bool savepedigrees string loadpedigree (4) Tarkistetaan, että tiedosto on olemassa. bool debug int founders (123) 2-n int lastgensize (123) 2-n int generations (123) 1-n int iterations 1-n Vakio-arvo 1. bool pedigreeonce Ei vaikutusta, jos iterations 1 vector<int> savegenerations 1-generations int subpops 1-n Vakio-arvo 1. Tulee antaa kaikki 3 subpop- parametria. vector<int> subpopsizes 2-founders Määrä täsmättävä edelliseen. double[][] subpopmigrations , sum=1.0 Sekä korkeus että leveys oltava subpops. Joka rivin summa 1.0. Ei korjata taulukkoa, jos siinä virheitä. double diseasemutfreq (34) double minminorallelefreq (34) double prevalence (34) double penetrance (34) int markers (34) 1-n int sampletype (34) 1-4 bool markermap string markermapfile Huomoidaan vain jos edellinen true. bool report string reportfile Huomioidaan vain jos edellinen true. string simcofile string chromfile bool parentsinresult string treefile string parpedigreefile bool allowsiblings Huomioimatta jos ei parents ei asetettu. int samplesize (34) 0-n int effectivepopsize 2-n (34) int chromlength (34) 2-n double recombrate (34) double snprate (34) Ei STR ja SNP:tä yhtäaikaa. Jos ovat molemmat -> virhe, ei korjata. string strfile Tarkistetaan olemassaolo. Taulukko 3: Parameters muuttujat

24 19 public void LogCritical(string msg) Lisää lokitiedostoon parametrina saadun viestin kriittinen-statuksella. public void LogError(string msg) Lisää lokitiedostoon parametrina saadun viestin virhe-statuksella. public void LogInfo(string msg) Lisää lokitiedostoon parametrina saadun viestin info-statuksella. public void LogDebug(string msg) Lisää lokitiedostoon parametrina saadun viestin debug-statuksella. Rivi lisätään vain mikäli attribuutti debug on asetettu arvoon true. Attribuutit private Log instance Sisäinen olio, jonka kaikki luokkaa käyttävät jakavat. Tuhotaan vasta ohjelman suorituksen päättyessä. private bool debug Määrittelee kirjoitetaanko debug-rivit tiedostoon. private string logfile Lokitiedosto, johon lokirivit kirjoitetaan Globaalit määrittelyt Globaalit funktiot ja muuttujat eivät kuulu mihinkään luokkaan, vaan näkyvät kaikille niitä käyttäville sellaisenaan. Funktiot int main(char* args[]) Main-metodi. Metodi ajetaan ensimmäisenä kun ohjelma käynnistetään komentoriviltä. Metodissa tehdään yksinkertaistettu parametrien tarkistus, jonka pohjalta se joko käynnistää palvelimen (parametri start-server), käynnistää tekstikäyttöliittymän (ei parametreja) tai aloittaa simulaation suorituksen (kaikissa muissa tapauksissa). Lopullinen simulaation parametrien tarkistus tehdään Parameters-luokan sisäisessä metodissa Check. Parametrien konstruointiin tarjotaan Parameters-luokan konstruktoria. void sig_handler(int sig) Signaalinkäsittelijä, jossa määritellään mitä tehdään kun prosessi saa UNIX- signaalin. Käyttäytyminen riippuu suurelta osin globaalista muuttujasta process_state.

25 20 Muuttujat TProcessState process_state Muuttujalla määritellään missä tilassa ja minkä tyyppinen senhetkinen prosessi on. Tällä kontrolloidaan lähinnä signaalinkäsittelijän toimintaa, koska esim. palvelimen, käynnissä olevan työn ja tekstikäyttöliittymän yhteydessä samakin signaali pitää voida tulkita eri tavalla. Muuttuja on enumeraattori-tyyppiä TProcessState. 3.4 Pedigree-komponentti Kuva 5: Pedigree-komponentin luokat. Pedigree korvaa ja yhdistää vanhan järjestelmän genpedin ja chromin. Pedigree tuottaa halutut sukupuutiedostot (iteration_pedigree_generation) ja kromosomitiedostot sukupolvittain (iteration_chrom_generation). Vakiona mitään pedigree-komponentin tulosteita ei säilytetä simulaation ajon jälkeen, eli sitten kun markertool on käynyt ne läpi. Tulosteiden poistoa ei toteuteta Pedigreehen vaan

26 21 Koodi Selitys -1 Määrittelemätön virhe -2 Tiedoston lukuvirhe (käyttöoikeus) -3 Tiedoston lukuvirhe (muu) -4 Tiedoston kirjoitusvirhe (käyttöoikeus) -5 Tiedoston lukuvirhe (muu) Taulukko 4: IPedigree::GeneratePedigree()-virhekoodit se tapahtuu muualla. Option takana on mahdollisuus tallettaa käytetyt sukupuu- ja kromosomitiedostot, sekä mahdollisuus generoida ja säilyttää ylimääräisiä sukupolvitiedostoja. Pedigree-komponentin luokat ja näiden väliset suhteet on esitetty kuvassa Rajapinta Pedigree-komponentin rajapinta tarjoaa yhden metodin sukupuun ja kromosomien luomista varten. Se mitä kullakin suorituskerralla luodaan määräytyy parametreista. int GeneratePedigree(TPedigreeType type, Parameters& params) Generoidaan parametreissä määritellyt asiat. Ensimmäisellä parametrilla voidaan jättää kromosomit generoimatta. TPedigreeType on enumeraattori, joka kertoo suorituksen tyypin Enumeraattorit TPedigreeType Kuvaa Pedigree-komponentin suorituksen tyypin. Mahdolliset arvot ovat: FULL = täysi ajo, TREE = vain sukupuu IPedigree-rajapinta IPedigree on Pedigree-luokan rajapinta ytimelle. Metodit virtual int GeneratePedigree(TPedigreeType, Parameters&) Core-luokalle näkyvä rajapintametodi. Toteutus aliluokassa. Palauttaa onnistuessaan arvon 0, virhetilanteessa negatiivisen arvon. Virhekoodit on listattu taulukossa 4.

27 Pedigree-luokka Pedigree luo sukupuut ja vastaa niiden tallennuksesta. Metodit public int GeneratePedigree(TPedigreeType, Parameters&) GeneratePedigree on implementaatio rajapintaluokan metodille. Metodi ottaa parametriksi TPedigreeType-enumin ja Parameters-luokan, jotka kertovat missä moodissa ohjelmaa ajetaan ja sisältävät tarvittavat parametrit ajoa varten. Metodi luo luokan sisäiset oliot, FamilyTree ja RecombTree, joissa tapahtuu varsinainen sukupuun ja kromosomien prosessointi. Töiden välillä metodi palauttaa tilatietoa IStatusCallbackluokan Update(...)-metodin kautta. Attribuutit private FamilyTree thefamilytree Pelkkä sukupuu private RecombTree therecombtree Rekombinaatiot sisältävä luokka PedigreeFactory-luokka PedigreeFactory on staattinen tehdasluokka, joka luo instanssin Pedigree- luokasta ja palauttaa osoittimen siihen. Metodit public static IPedigree* Construct() Metodi luo Pedigree-instanssin ja palauttaa sen osoittimen kutsujalle FamilyTree-luokka FamilyTree on sukupuun sisältävä luokka. Kaikki sukupuun prosessointi, tallennus ja tulostus tapahtuu tässä luokassa. Metodit public int Create(Parameters&) Luo parametreissa määritellyn kaltaisen sukupuun.

28 23 public int WriteToDisk() Kirjoittaa sukupuun sisällön tiedostoon sukupolvi kerrallaan. public int WriteToScreen() Tulostaa sukupuun tiedot ruudulle. Attribuutit private vector<individual> treedata Tietorakenne sukupuuta varten RecombTree-luokka RecombTree on luokka, joka sisältää tiedot kromosomeista ja rekombinaatioista. Metodit public int Create(FamilyTree&, Parameters&) Luo kromosomidatan sukupuun ja parametrien perusteella. public int WriteToDisk() Kirjoittaa kromosomidatan tiedostoon. public int WriteToScreen() Tulostaa kromosomidatan ruudulle. Attribuutit private vector<segment> recombdata Tietorakenne rekombinaatiotietoa varten Segment-luokka Segment on säiliöluokka kromosomidatalle. Luokka on RecombTree-luokan apuluokka. Attribuutit Attribuutit kiinnitetään toteutusvaiheessa.

29 Individual-luokka Individual on säiliöluokka yksilötiedolle. Luokka on FamilyTree-luokan apuluokka. Attribuutit Attribuutit kiinnitetään toteutusvaiheessa. 3.5 Marker-komponentti Kuva 6: Marker-komponentin luokat. Marker on yhteinen rajapintakomponentti markertoolille ja simcolle. Marker toimii em. ohjelmien ajurina, joka virtaviivaistaa niiden käyttöä ytimelle ja mahdollistaa ohjelman laajennettavuuden. Marker-komponentin luokat ja näiden väliset suhteet on esitetty kuvassa Rajapinta Marker-komponentin rajapinta sisältää yhden metodin, jonka kautta käytetään simco- ja markertool-komponentteja. Yksityiskohdat sisältyvät parametreihin.

30 25 Koodi Selitys -1 Määrittelemätön virhe -2 Tiedoston lukuvirhe (käyttöoikeus) -3 Tiedoston lukuvirhe (muu) -4 Tiedoston kirjoitusvirhe (käyttöoikeus) -5 Tiedoston lukuvirhe (muu) Taulukko 5: IMarker::Process()-virhekoodit int Process(TMarkerType type, Parameters params&) Ajetaan Simco ja Markertool halutuin parametrein Enumeraattorit TMarkerType Kuvaa Marker-komponentin suorituksen tyypin. Mahdolliset arvot ovat: MARKER_NORMAL = normaali ajo, MARKER_WPAR = vanhemmat mukana otoksessa IMarker-rajapinta IMarker on Marker-luokan rajapinta ytimelle. Metodit public int Process(TMarkerType type, Parameters &params) Core-luokalle näkyvä rajapintametodi. Toteutus aliluokassa. Onnistuessaan metodi palauttaa arvon 0, virhetilanteessa negatiivisen arvon. Virhekoodit on lueteltu taulukossa Marker-luokka Marker-luokka toimii rajapintana Ytimen ja Simcon sekä Markertoolin välillä. Metodit public int Process(TMarkerType type, Parameters &params) Luokan ainoa metodi. TMarkerType-enumeraattori määrittelee ajotavan, Parametersluokka sisältää parametrit simcolle ja markertoolille. Ensin ajetaan Simco ja sen jälkeen Markertool, molemmat ajetaan aina. Metodi käynnistää ulkoiset ohjelmat uuteen prosessiin ja jää odottamaan lopetussignaalia. Parametrit on validoitu jo ennen

31 ulkoisten ohjelmien ajamista, mutta jos virhetilanne kuitenkin syntyy, palautetaan negatiivinen arvo. Onnistuessaan metodi palauttaa arvon 0. Töiden välillä metodi palauttaa tilatietoa IStatusCallback-luokan Update(...)- metodin kautta MarkerFactory-luokka MarkerFactory on staattinen tehdasluokka, joka luo instanssin Marker- luokasta ja palauttaa osoittimen siihen. Metodit public static IMarker* Construct() Metodi luo Marker-instanssin ja palauttaa sen osoittimen kutsujalle. 3.6 Tekstikäyttöliittymä-komponentti Kuva 7: Tekstikäyttöliittymäkomponentin luokat. Tekstikäyttöliittymä pohjautuu ncurses-kirjastoon. Käyttäjä määrittelee parametrit, joiden perusteella komponentti kutsuu ydintä. Ydin tarjoaa tietoa simulaation etenemisestä, joka näytetään käyttäjälle. Lopputuloksia ei visualisoida, ainoastaan talletetaan annettuun tai vakiohakemistoon. Tekstikäyttöliittymäkomponentin luokat on esitetty kuvassa Rajapinta void Update(TStatus status) Metodi, jonka avulla päivitetään ruudulle tilatietoa ohjelman edistymisestä aina jonkin osasuorituksen valmistuttua.

32 27 void StartUI() Käynnistää tekstikäyttöliittymän CursesUI-luokka CursesUI on luokka, joka vastaa kaikista tekstikäyttöliittymän toiminnoista. Käyttöliittymä rakennetaan käyttäen ncurses-kirjaston tarjoamia toimintoja. Simulaation käynnistyttyä tilatietoa päivitetään IStatusCallbackin Update(...)-metodin kautta. Koska käyttöliittymälle ei luoda omaa prosessia, simulaation aikana käyttäjälle ei tarjota muita toimintoja kuin simulaation keskeyttäminen. Metodit void Update(TStatus status) Ytimelle tarjottava metodi, jolla voidaan päivittää käyttöliittymää laskennan kuluessa tarjoamalla käyttöliittymälle kontrolli pieneksi hetkeksi. Määritellään rajapinnassa IStatusCallback. void StartUI() Käynnistää tekstikäyttöliittymän. Ydin kutsuu tätä metodia main-metodistaan, jos ohjelmisto käynnistetään ilman komentoriviparametreja. Attribuutit Kiinnitetään toteutusvaiheessa 3.7 Palvelinkomponentti Komentoriviltä käynnistettävä palvelin ottaa vastaan palvelupyyntöjä asetetusta portista. Lisäksi palvelimelle määritellään IP-osoitteet, joista palvelupyynnöt tulee sallia; muualta tulleet palvelupyynnöt hylätään. Palvelin pitää kirjaa asiakkaista ja suorittaa saatuja töitä ytimellä. Useampi kuin yksi asiakas voi olla yhtäaikaa yhteydessä palvelimeen, jolloin ruuhkautumisen välttämiseksi palvelimen on osattava tarvittaessa laittaa töitä jonoon odottamaan suoritusvuoroaan. Palvelimeen asetetaan kerrallaan suorituksessa olevien töiden suurin sallittu lukumäärä. Palvelin ei kommunikoi aktiivisesti asiakkaan suuntaan, vaan ainoastaan vastaa palvelupyyntöihin. Sen sijaan ytimen suuntaan palvelinkomponentti on aktiivinen osapuoli. Mikäli palvelin sammutetaan tai siellä tapahtuu muu kriittinen virhe, joka aiheuttaa sen sammuttamisen, suljetaan asiakkaan ja palvelimen välinen yhteys. Erillistä virheilmoitusta asiakkaalle ei lähetetä. Palvelinkomponentin luokat on esitetty kuvassa 8.

33 28 Kuva 8: Palvelinkomponentin luokat Rajapinta void StartServer() Ytimelle tarjottava metodi, joka käynnistää palvelimen. Portin voi asettaa asetustiedostossa, samoin hyväksyttävät verkko-osoitteet Server-luokka Server on palvelinkomponentin pääluokka. Luokassa hallitaan töiden suoritusta ja käsitellään asiakkaiden tekemät palvelupyynnöt. Luokassa on sisäiset tietovarastot töiden ja asiakkaiden tietoja varten. Metodit public void StartServer() Käynnistää palvelimen. Lukee asetuksensa palvelimen asetustiedostosta, siirtää prosessin tausta-ajoksi ja ryhtyy ottamaan vastaan palvelupyyntöjä asiakkailta. Metodin suoritus päättyy kun palvelin sammutetaan. private int LoadConfig() Lataa palvelimen asetukset asetustiedostosta. Palauttaa onnistuessaan arvon 0, virhetilanteissa -1. Attribuutit private int serverfd Putki, lähetetään viestejä ydinprosessille.

34 29 private int stubfd Putki, jolla vastaanotetaan viestejä ydinprosessilta ServerStub-luokka ServerStub on apuluokka, jonka kautta palvelinkomponentti kommunikoi ytimen kanssa. Ydin suoritetaan aina omassa prosessissaan, jolloin palvelimen ja ytimen välinen kommunikaatio hoidetaan putken avulla. ServerStub-luokka peittää ytimeltä tämän ja tarjoaa suoran oliorajapinnan. Luokka toteuttaa Ydinkomponentin rajapinnan IStatusCallback. Metodit void Update(TStatus status) Ytimelle tarjottava metodi, jolla työn tilasta voidaan lähettää välitietoa palvelimelle ja sitä kautta asiakkaalle. Saatu tilatieto lähetetään eteenpäin putkea pitkin palvelimelle, jonka jälkeen ohjelman kontrolli palaa metodin kutsujalle. Attribuutit private int serverfd Putki, vastaanotetaan viestejä palvelinprosessilta private int stubfd Putki, jolla lähetetään viestejä palvelinprosessille ServerJob-luokka ServerJob-luokka kuvaa yhden työn tilan. Metodit public TStatus GetStatus() Palauttaa työn tilan. public void SetStatus(TStatus status) Asettaan työn tilan. Attribuutit private TStatus status Työn senhetkinen tila. Alkuarvo INIT.

35 ServerClient-luokka ServerClient-luokka kuvaa asiakkaan. Jokaista asiakasta kohden luodaan yksi luokan ilmentymä, johon tallennetaan asiakkaan pistoke. Metodit public int GetSockFD() Palauttaa asiakkaan pistokkeen kahvan. public void SetSockFD(int sockfd) Asettaa asiakkaan pistokkeen kahvan. Attribuutit private int sockfd Asiakkaan pistokkeen kahva. 3.8 Asiakaskomponentti Kuva 9: Asiakaskomponentin luokat.

36 Asiakasohjelma käyttää verkon yli mahdollisesti toisessa koneessa käynnissä olevaa Populouspalvelinta. Kommunikaatio tapahtuu TCP/IP-protokollaa käyttäen. (kts ). Syöttötiedot asetetaan asiakasohjelmassa, joka välittää palvelupyynnöllä työn suoritettavaksi jollekin palvelimelle. Työn tilasta näytetään tietoa, ja sen valmistuttua asiakaskomponentti hakee tulokset ja tallentaa ne käyttäjän valitsemaan paikkaan. Asiakaskomponentilla voi luoda useampia yhtäaikaa käynnissä olevia töitä, joita asiakaskomponentti osaa tarvittaessa jakaa useammille palvelimille rinnakkain suoritettaviksi. Myös samalle palvelimelle voi lähettää useampia töitä vaikka aikaisemmat eivät olisikaan vielä valmistuneet. Yhteyden palvelimeen katketessa keskeytyvät myös siellä suorituksessa olevat työt. Yksittäistä palvelimelle lähetettyä työtä ei voida jatkaa, mutta asiakkaan hoitamaa iteroitua suoritusta voidaan jatkaa aloittamalla keskeytyneen iteraation alusta uudestaan, aikaisempien iteraatioiden tulokset ovat säilyneet. Asiakaskomponentin luokat on esitetty kuvassa Rajapinta Asiakas kommunikoi muun ohjelmiston kanssa ainoastaan pistokkeilla TCP/IP-yhteyden yli, eikä tarjoa mitään palvelupyyntörajapintaa ClientFrame-luokka ClientFrame-luokka on asiakaskomponentin käyttöliittymäpuolen pääluokka, jossa määritellään asiakasohjelmiston ulkoasu ja käyttäytyminen. Metodit Java Swingin luokasta javax.swing.jframe perittyjen käyttöliittymän piirtämiseen ja hallintaan liittyvien metodien lisäksi toteutettavat metodit kiinnitetään toteutusvaiheessa. Attribuutit Kiinnitetään toteutusvaiheessa JobControl-luokka JobControl-luokka hallinnoi simulaatiotöiden suoritusta. Käyttöliittymältä saatu työ otetaan ensin paikalliseen jonoon, josta se edelleen lähetetään palvelimelle suoritettavaksi. Palvelimilla suorituksia olevia töitä seurataan ja niiden edistymisestä pidetään kirjaa. Metodit public Job[] GetJobs()

37 Palauttaa kaikki tiedossa olevat työt. Lista voi pitää sisällään niin jonossa suoritusta odottavia, suorituksessa olevia kuin valmiitakin töitä. public Job StartJob(Parameters param) Lisää annettujen parametrien mukaisen työn suoritusjonoon, josta se aikanaan suoritetaan. Parameters-luokka on vastaava kuin luvussa määritelty, mutta Javalla toteutettuna. Palauttaa luodun työn ilmentymän, tai null mikäli luominen ei onnistunut. public void RemoveJob(Job job) Poistaa halutun työn. Tarvittaessa keskeyttää työn suorituksen palvelimelta. Ei poista työn mahdollisesti tuottamia tulostiedostoja, ja voidaan näinollen käyttää myös valmiin työn kuittaamiseen ja listalta poistamiseen. Attribuutit 32 List jobs Tietovarasto, johon kaikki työt tallennetaan Job-luokka Job-luokka kuvaa yhden simulaatiotyön. Luokan olio on itsenäinen säie, joka on itsenäisesti yhteydessä sopivaan palvelimeen ja hoitaa työn välityksen palvelimelle, seurannan ja tulosten hakemisen. Luokka on synkronoitu. Metodit public Job(Parameters param, ServerInfo server) Luo työn, mutta ei käynnistä sitä vielä. Käynnistäminen tehdään säikeiden tapaan kutsumalla java.lang.thread-luokassa määriteltyä start()-metodia. public void setserver(serverinfo server) Asettaa työlle palvelimen, jossa se on määrä suorittaa. public void run() Pyrkii lähettämään työn suoritettavaksi valitulle palvelimelle. Varautuu siihen, että palvelinta ei mahdollisesti ole määritelty tai että sitä voidaan vaihtaa ennen kuin työ on saatu jollekin palvelimelle suoritukseen. Työn suorituksen ajan kysyy aika-ajoin tilatietoa palvelimelta, ja työn valmistuttua hakee tulokset ja tallentaa ne levylle käyttäjän määrittelemään hakemistoon. public int getstate() Palauttaa työn edistymisprosentin.

38 33 public Parameters getparameters() Palauttaa Parameters-olion, joka annettiin työtä käynnistettäessä. Attribuutit private ServerInfo server Palvelin, jolla työ ajetaan. private int id private int state Työn suorituksen edistymisprosentti, arvo väliltä private Parameters param Sisältää Parameters-olion, jolla työ aloitettiin ServerInfo-luokka Jokaiselle tunnetulle palvelimelle luodaan ServerInfo-luokan olio, johon tallennetaan palvelimeen liittyvät tiedot. Luokka on synkronoitu Metodit public ServerInfo(String address, int port) Konstruktori, jolla asetetaan palvelimen osoite ja portti. public String getaddress() Palauttaa palvelimen osoitteen. public int getport() Palauttaa palvelimen portti. Attribuutit private String address Palvelimen osoite. private int port Palvelimen portti.

39 Hakemistorakenne Ohjelman hakemistorakenne eroaa hieman palvelinkäytössä. Tällöin ohjelma tallentaa ajokerrat aina vakionimiseen hakemistoon. Kunkin työn eri hakemistoon. Asiakaspäässä tiedostot kootaan alla näkyvän kaavion mukaisesti. Tiedoston nimen alkuun liitetään järjestysluku, joka on aina yhtä suurempi kuin suurin samassa hakemistossa olevan tiedoston järjestysnumero. Kaikkiin tiedostoihin lisätään järjestysluku, ensimmäiseen tiedostoon numero 1. Palvelinkäytössä luodaan jokaiselle työlle oma hakemistonsa, johon kaikki kyseiseen työhön liittyvät tiedostot tallennetaan. Työn ajohakemiston nimi on sama kuin työn järjestysluku. Tiedostojen nimeäminen tehdään samalla periaatteella kuin asiakaspäässäkin. Ohjelman tiedosto- ja hakemistorakenne on seuraava: results-hakemisto ajohakemisto Kullekin ajolle eli ajokerralle luodaan oma hakemisto, johon sijoitetaan sen ajon tulostiedostot. Käyttäjä voi nimetä hakemiston. Muutoin käytetään vakionimeämistä, jossa hakemiston nimeksi tulee YYYY-MM-DD_ID, eli päiväys, jota seuraa ajokerran numero. iteration_pedigree_generation Sukupuu talletetaan tiedostoon sukupolvi kerrallaan. Esim. 20 sukupolvisen sukupuun ajotiedosto (viimeinen sukupolvi) on 1_pedigree_20. Iteraationumero edeltää jokaista tulostettavaa tiedostoa. Numerointi alkaa ykkösestä. iteration_chrom_generation Kromosomitiedosto talletetaan myös sukupolvi kerrallaan. iteration_alleles[_p] Markertoolin tulostiedosto. Loppuliite "_p"määrittelee, että tuloksessa on käytetty myös vanhempia. iteration_markermap Markertoolin markerikarttatiedosto. iteration_report Markertoolin raporttitiedosto. parameters-hakemisto Parameters-alihakemistoon tallennetaan parametritiedostot. Käyttäjä voi nimetä tiedostot itse, mutta ohjelmassa on myös vakionimeämiskäytäntö. Parametritiedostot ovat muotoa YYYY-MM-DD_ID.param, eli tiedostojen niminä käytetään päiväystä, jonka jälkeen on juokseva numero. data-hakemisto

40 STRfile Markertoolille syötteeksi annettavat STR-markeritiedostot talletataan tänne. bin-hakemisto Ohjelmiston staattiset osat, kuten ajettava tiedosto. README-tiedosto Ohjetiedosto. manual.pdf-tiedosto Ohjelman manuaali. server.conf-tiedosto Palvelimen asetustiedosto. server.pid-tiedosto Tiedosto luodaan automaattisesti palvelimen käynnistyksen yhteydessä. Tiedostoon tallennetaan käynnistetyn palvelimen PID, ja se poistetaan kun palvelin sammutetaan. Palvelinta ei voida käynnistää hakemistosta, jossa jo on server.pid-tiedosto, eli jos palvelin kaatuu tai se tapetaan SIGKILL-signaalilla, on tiedosto poistettava itse ennen palvelimen uudelleenkäynnistämistä. populous.log-tiedosto Palvelimen lokitiedosto. Palvelin ei tulosta standardiin tulostusvirtaan mitään, vaan kaikki virheilmoitukset ja debug-viestit kirjoitetaan tähän tiedostoon Tiedostoformaatit Tiedostot ovat ASCII-tekstitiedostoja, joissa käytetään UNIX-rivinvaihtoa. Kenttien erottimena käytetään pääasiassa välilyöntiä, ja kenttien arvot ovat tekstimuodossa merkkijonoina, eli esim. arvo 42 on kahden tavun merkkijono 42, ei binääriluku pedigree <person-id> <father-id> <mother-id> <sub-population-id> Sub-population-id:n vakioarvo on 0. Tiedosto on järjestetty person-id:n mukaan nousevaan järjestykseen chrom <person-id> <chromosome-starting-nucleotide> <founder-id> Tiedosto on järjestetty toisen kentän mukaan nousevaan järjestykseen. Parent- id:ssä pariton luku tarkoittaa äitiä, parillinen isää. Jokaisella henkilöllä on tässä tiedostossa kaksi riviä, eli kaksi erillistä person-id:tä.

41 param Parametritiedostossa parametrit ovat samassa muodossa kuin ohjelmaa komentoriviltä ajettaessakin. Kukin parametri on omalla rivillään, joka päättyy UNIX-tyyppiseen rivinvaihtomerkkiin. Parametrit on listattu luvussa 4.1 taulukoissa 6 ja 7. Lisäksi parametritiedostoon voidaan koodata kokonaisia tekstitiedostoja. Tekstitiedostojen koodaus alkaa merkkijonolla <:<:<START_FILE:tiedosto.pääte>:>:>, jossa "tiedosto.pääte"on halutun tiedoston nimi. Vastaavasti tiedosto päättyy riviin, joka on muotota <:<:<END_FILE:tiedosto.pääte>:>:> ja jossa "tiedosto.pääte"on sama kuin tiedoston alussa. Näin parametritiedostoon sisällytetyssä tiedostossa itsessään ei saa olla tämänmuotoista riviä. Näin liitettyyn tiedostoon voidaan viitata muista parametreista nimellä, joka sille on määritelty. Tiedostonimen arvokseen saavien parametrien kohdalla tarkistetaan ensin mahdollisen sisällytetyn tiedoston olemassaolo ja vasta sen jälkeen levyltä nykyisestä hakemistosta. puhtaaksi server.conf Palvelimen asetustiedosto on tekstitiedosto, jossa palvelimen asetukset määritellään. Jokaisella asetuksella on yksiselitteinen nimi ja arvo, jotka esitetään yhdellä rivillä muodossa <asetus>=<arvo>. Tiedoston rivinvaihto on UNIX-muodossa eikä ylimääräisiä välejä asetusriveillä sallita. Kommenttirivit alkavat merkillä # ja ne jätetään huomioimatta. port=<int> Portti, jota palvelin kuuntelee ja johon asiakkaat voivat tehdä yhteydenottopyyntöjä allowip=<ip>[,<ip>]* IP-osoitteet, joista tulevat yhteydenottopyynnöt otetaan vastaan. Muista osoitteista tulevat yhteydenottopyynnöt hylätään. 4 Käyttöliittymä Käyttöliittymiä suunnitellaan kolme erilaista: komentorivikäyttöliittymä, Ncurses -kirjastolla toteutettava tekstipohjainen käyttöliittymä ja Javan Swing -pakkauksella toteutettava graafinen käyttöliittymä. Ncurses -käyttöliittymä suunnitellaan siltä varalta, että ajan puutteen vuoksi graafista käyttöliittymää ei saada toimintaan. Kukin käyttöliittymätyyppi kuvataan tarkemmin omassa aliluvussaan. Käyttöliittymien avulla käyttäjä syöttää tai valitsee käyttöliittymän tarjoamasta valikosta populaatiosimulaation tarvitsemat parametrit. Järjestelmässä on mahdollisuus käyttää myös syöttötiedostoja, jolloin parametrit ladataan simulaattorin käyttöön käyttäjän valinnan mukaisesta tiedostosta.

42 Käyttöliittymien suunnittelussa otetaan huomioon erilaiset käyttötapaukset, joissa populaatiosimulaattoria käytetään ja niitä pyritään tukemaan mahdollisimman hyvin. Tällä tavoin virheellisten tietojen syöttäminen minimoidaan ja järjestelmän käyttöä helpotetaan. Käyttöliittymä toteutetaan siten, että se tarkistaa käyttäjän syöttämien parametrien arvoalueet ja antaa käyttäjälle virheilmoituksen mikäli ne eivät ole validit. Syöttötietojen oikeellisuus tarkistetaan sitä tarvitsevassa komponentissa, joka antaa virheilmoituksen, jos syöttötieto ei kelpaa. Lisäksi järjestelmä antaa käyttäjälle käyttöliittymän välityksellä informaatiota suoritettavana olevan simulaation edistymisestä Komentorivikäyttöliittymä Ohjelma tukee graafisen käyttöliittymän lisäksi komentorivitilaa, jossa voidaan komentoriviltä ajaa simulaatiota. Ohjelman käynnistetään palvelin ja tekstikäyttöliittymätilaan myös suoraan komentoriviltä. Komentorivin käyttö simulaatioiden ajoon on tarkoitettu vain vararatkaisuksi ja ohjelman tehokäyttöön. server.config:sta. populaatio simulaatio, vain sijaintitiedosto. esim. ei hyvin arvo 50- Duplikaatteja parametreja: Satunnaisgeneraattorin siemen (simco) on optio "t". Otoksen koko (simco) on sama kuin perustajajäsenten määrä. Parental generation size (markertool) on sama kuin toiseksi viimeisen sukupolven koko. Parental segments (markertool) on toiseksi viimeisen sukupolven kromosomitiedosto. Pedigree tree (markertool) on viimeisen sukupolven sukupuu. Kromosomipituus (markertool) on sama kuin Simcon kromosominpituus. Foundersize (markertool) on perustajien määrä. Popsize (markertool) on loppupopulaation koko.

43 38 Parametri (*=pakollinen) Arvo Selitys debug Debug-tila. start-server Käynnistää palvelintilan, jossa ohjelma lukee palvelinportit ja hyväksytyt verkko-osoitteet server.config:sta. stop-server Sammuttaa serverin. load-params file Lataa parametrit tiedostosta. Tiedostoa haetaan sekä pwd:stä että alihakemistosta parameters automaattisesti. save-params [tiedosto] Talletaan annetut parametrit. Voidaan määritellä tallennustiedosto. Vakiona parameters alihakemistoon vakionimellä. result-dir hakemisto Määritellään tulostehakemisto, vakiona results alihakemistoon vakionimellä. Tämä määrittelee myös ajon/simulaation tunnisteen/nimen. founders* int Perustajasukupolven koko yksilöinä. Kerrotaan sisäisesti kahdella, jotta saadaan populaatio kromosomeina. Lisäksi ekvivalentti simcon sample-size:n kanssa. Tyypillinen arvo last-generation* int Viimeisen sukupolven koko. Tyypillinen arvo 100K-200K. generations* int Sukupolvien määrä. Tyypillinen arvo iterations int Iteraatioiden määrä, vakiona ei iteraatioita. Tyypillinen arvo noin 100. pedigree-once Generoidaanko sukupuu ja kromosomit vain kerran. Käytetään iteraatioiden yhteydessä, jolloin iteroidaan ainoastaan markertoolia ja simcoa. simulation-mode full tree pedigree marker Full: normaali simulaatio, tree: pelkkä sukupuu, pedigree: sukupuu ja kromosomit, marker: vain simco ja markertool. save-trees Talletetaan sukupuut. Vakiona ajon sukupuu- ja kromosomi- save-pedigrees tiedostot poistetaan. Talletetaan kromosomitiedostot. Vakiona ajon sukupuu- ja kromosomitiedostot poistetaan. Talletetaan vain -sg:ssä määritellyt sukupolvet. load-pedigree tiedosto Ladataan kromosomitiedosto (chrom). Ei ajeta genpediä tai chromia. save-generations int-list Tallennetaan myös annetut (pilkuin erotelluin) sukupolvet. Taulukko 6: Parametrit osa 1

44 Parametri (*=pakollinen) Arvo Selitys sub-populations int Alipopulaatioiden määrä. Tyypillinen arvo sub-population-sizes int-list Alipopulaatioiden koot. Luvut erotellaan pilkuin. Esim. 2700,500,1200. sub-populationmigrations double-list Alipopulaatioiden siirtymistodennäköisyydet. Taulukko, jossa jokaisen alipopulaation jäsenen todennäköisyys siirtyä jokaiseen toiseen alipopulaatioon. Tällä voidaan myös poistaa siirtymiset asettamalla todennäköisyydet nollaksi. Arvoalue [0,1]. Esim. kolmella alipopulaatiolla: (0.8,0.1,0.1)(0.2,0.7,0.1)(0,0,1), tarkoittaen, että C:stä ei kukaan lähde ikinä pois, B:stä siirrytään 20% todennäköisyydellä A:han, 10% B:hen ja 70% jäädään B:hen. chrom-length* int Kromosomin pituus emäspareina. Tyypillinen arvo 10M- 100M. str-file tiedosto STR-markereiden sijaintitiedosto. snp-rate* double SNP-mutaatioiden todennäköisyys/ emäspari/sukupolvi. Arvoalue [0,1]. Tyypillinen arvo hyvin pieni, esim. 1e-8 (=0, ). Ohjelmalle on annettava joko strfile tai snprate, ei molempia. recomb-rate* double Rekombinaatiotodennäköisyys/ emäspari/sukupolvi. Arvoalue [0,1]. Tyypillinen arvo hyvin pieni, hyvin usein 1e-8 effective-pop-size* int Simcon efektiivinen populaation koko. Tyypillinen arvo 5-15K. disease-mut-freq* double Tautigeeniksi valittavan mutaation frekvenssi populaatiossa. Arvoalue [0,1]. Tyypillinen arvo min-minor-allele-freq* double Pienin sallittu tulokseen (otokseen) mukaan otettavien markkereiden mutaatiomuodon yleisyys. Arvoalue [0,1]. Tyypillinen arvo marker-map-file [tiedosto] Kirjoitetaan markermap tiedostoon, voidaan käyttää vakiotiedostonnimeä. markers* int SNP-markkereiden määrä. Tyypillinen arvo sample-type random affected case+healthy case+random Otostyyppi. Vakio-arvo random. sample-size* int Otoksen koko. Tyypillinen arvo prevalence* double Yleisyys. Arvoalue [0,1]. Tyypillinen arvo penetrance* double Ilmenevyys. Arvoalue [0,1]. Tyypillinen arvo report-file [tiedosto] Koosteraportti tiedostoon, voidaan käyttää vakiotiedostonnimeä. parents-in-result 39 Otetaan vanhemmat mukaan tulokseen, jolloin ajetaan kaksi viimeistä sukupolvea markertoolille. par-tree file Viimeisen sukupolven sukupuu. Vaatii parents ja marker - optiot. par-pedigree file Vanhempien kromosomit. Vaatii parents ja maker -optiot. allow-siblings Sisarukset mukaan tulokseen. Vaatii yllä olevan -prparametrin. Taulukko 7: Parametrit osa 2

45 40 Founderfile (markertool) on Simcon tulostiedosto. Segmentfile (markertool) on viimeisen sukupolven kromosomitiedosto. populous start-server Käynnistää palvelimen. populous load-params params param Lataa parametrit tiedostosta. populous simulation-mode tree founders 100 last- generation 2000 generations 10 result-dir MyDir Ajetaan vain sukupuun luonti annetuin parametrein. Sukupuu tallennetaan MyDirhakemistoon vakionimellä pedigree_10. populous simulation-mode pedigree founders 200 last- generation 3500 generations 15 result-dir OtherDir sub-populations 3 sub-population- sizes 50,50,100 sub-population-migratations (1,0,0)(0.1,0.8,0.1)(0.3,0.4,0.3) includegenerations 12,13 save-params MunParametrit Ajetaan vain sukupuun ja kromosomitiedostojen luonti. Talletataan sukupolvet 12,13 ja 15 (viimeinen) OtherDir-hakemistoon vakionimillä tree_12, pedigree_12 jne. Lisäksi generoidaan sukupuut käyttäen alipopulaatioita, tässä 3 alipopulaatiota. Alipopulaatiosta A ei siirrytä ikinä muihin alipopulaatioihin, B:stä siirrytään C:hen ja A:han 10% todennäköisyydellä ja C:stä siirrytään pois sekä B:hen että A:han 30% todennäköisyydellä. Talletataan vielä kaikki annetut parametrit parameters/munparametrithakemistoon. Ilman MunParametrit-määrettä olisi talletettu oletustiedostoon, joka tässä tapauksessa olisi ollut "OtherDir", koska resultdir on määritelty. Ilman sitä se olisi ollut muotoa YYYY-MM-DD_ID.param. populous load-pedigree pedigree_20 iterations 50 chrom-length snp-rate recomb-rate effective-pop-size diseasemut-freq 0.08 min-minor-allele-freq 0.12 markers 4000 sample-size 300 prevalence 0.05 penetrance 0.19 sample-type affected reportfile markermapfile parents-in-result allow-siblings Ei ajeta sukupuun generointia tai kromosomien periytymistä, vaan otetaan ne valmiiksi kahdesta tiedostosta. Ajetaan 50 iteraatiota, ja "chrompedigreeonce"on automaattisesti päällä, eli iteroidaan vain markertoolia ja simcoa. Raportti ja markkerikartta talletetaan vakiotiedostoihin (markermap ja report) ja vanhemmat otetaan mukaan otokseen, sekä sisarukset. populous save-params ajo3 founders 100 lastgeneration 2000 generations 20 iterations 100 chrom-pedigree-once save- pedigrees includegenerations 15,16 chrom-length snp-rate recomb-rate effective-pop-size disease-mut-freq 0.04 min-minor- allele-freq 0.12

46 markers 2000 sample-size 100 prevalence 0.05 penetrance 0.19 parentsin-results Tallennetaan annetut parametrit, iteroidaan 100 kertaa, mutta vain markertoolia ja simcoa, talletetaan sukupolvet 15, 16, 19, 20 (15 ja 16 annettu, 20 on viimeinen ja 19 tulee -parentsinresult:sta). Ei tallenna kromosomitiedostoja Ncurses Ohjelman tekstipohjainen käyttöliittymä luodaan ncurses-kirjastolla, joka on terminaalija näytönhallintapakkaus erityisesti tekstipohjaisten käyttöliittymien rakentamiseen UNIXympäristöissä. Tekstikäyttöliittymä on ohjelmaa paikallisesti käytettäessä ensisijainen käyttöliittymä, mutta sen tärkein tavoite on silti yksinkertaisuus ja selkeys. Käyttöliittymä tarjoaa käyttäjälle simulaatiotyövaihtoehdot ja mahdollisuuden antaa parametrit siististi ohjelmalle. Lisäksi käyttöliittymä tarjoaa mahdollisuuden seurata simulaation etenemistä ja keskeyttää sen. Tuloksia ei visualisoida eikä erilaisten tulos-, syöte- ja datatiedostojen katselua tai hallintaa toteuteta käyttöliittymään toissijaisina vaatimuksina. NCurses on UNIXien vanha terminaalipohjainen kirjasto, joka on puhdasta C:tä. Tämä näkyy erittäin hyvin kirjaston luonteessa ja sen tarjoamissa funktiossa, makroissa ja määrityksissä, mitkä ovat hyvin matalalla tasolla ja erityisen proseduraalisia. Tämä asettaa suunnittelulle ja toteutukselle tiettyjä rajoitteita. Tekstikäyttöliittymää ei suunnitella erityisesti oliopohjaiseksi. NCursesista löytyy natiivina hyvät työkalut ruudun manipuloinnille sekä ikkunoiden käyttämiselle. Lisäksi apukirjastopaketit tarjoavat ikkunoiden käyttöä helpottavat panelit, sekä tietojen syötön ja kenttien automatisoinnin form-pakkauksen myötä. Form-pakkauksella voidaan rakentaa web-tyylisiä tiedonkeruulomakkeita ruudulle. Jokaista datakenttää vastaa staattinen selitekenttä. Datakentille on valmiita ja tehokkaita rajatarkistusfunktiota. Käyttöliittymä pohjautuukin useisiin näkymiin (ncursesin WINDOW), sekä tiedonsyöttönäkymissä käytettyihin formeihin. Näkymät vastaavat terminaali-ikkunan koon asettamissa rajoissa mahdollisimman suoraan Swing- käyttöliittymän ikkunoita. Yksi näkymä on ruudulla kerrallaan. Ruudun yläreunassa näkyy aina ohjelman nimi ja näkymän nimi. Parametrien keruu suoritetaan formeilla, jotka korjaavat parametrien arvoalueet automaattisesti ja tarkistavat, että syöte on validissa muodossa (ei kirjaimia jos haluttiin numero, yms.). Näkymien rakenne on seuraava: 1. Alkuvalikko Alkuvalikko on ensimmäinen näkymä käynnistettäessä. Valintamahdollisuuksina "New simulation", "Exit". 2. Simulaatio-optiot Luetellaan simulaation optiot. Tarjotaan paluu alkuvalikkoon tai kohti simulaatiodatan syöttöä.

47 3. Simulaatiodata Luetellaan simulaatiodata ja sen syötöt. Sivulta pääsee takaisin simulaatio-optionäkymään tai voidaan käynnistää simulaatio ( seurantanäkymä). 4. Simulaation seuranta Näytetään missä vaiheessa simulaatio on. Työn valmistuttua tulostetaan yhteenveto simulaatiosta ja tulostiedostojen kirjoitussijainnit. Tarjotaan paluuta takaisin alkuvalikkoon. Simulaation aikana control-c tulostaa tähän näkymään tiedon keskeytymisestä ja tarjoaa reitin alkuvalikkoon. Tiedostosyötteistä tarkistetaan suoraan tiedostojen olemassaolo, muttei tiedostojen validiutta. Ladatessa parametrit tiedostosta, ohjelma täyttää jokaisen kentän valmiiksi, jotka käyttäjä voi hyväksyä ja käynnistää simulaation Graafinen käyttöliittymä (Java Swing) Graafisen käyttöliittymän suunnittelussa on käytetty Helsingin yliopiston Tietojenkäsittelytieteen laitoksen ja Interactan yhteistyössä kehittämää GDD (Goal Derived Design) -suunnitteluprosessia, jossa käyttöpaus kerrallaan piirretään dataa ja toimintoja näkyviin ikkunaan. Järjestelmän toimintaan liittyvät tavoitepohjaiset käyttötapaukset ovat prioriteettijärjestyksessä: Käyttötapaus 1: Sokeritaudin periytymisen tutkiminen Käyttötapaus 2: Aineistoa artikkelia varten Käyttötapaus 3: Sokeritautigeenitutkimuksen uusiminen Käyttötapaus 4: Geeniparametrien toimivuuden testaus Käyttötapaus 5: Väärät tutkimustiedot Käyttötapaus 6: Ämmänsaaren väestön kehittyminen Käyttötapaus 7: Siirtolaisten vaikutus Ämmänsaaren geeniperimään Käyttötapaukset on tarkemmin esitetty kussakin aliluvussa, jossa ko. käyttötapaukseen liittyvät tavoitteet on kirjattu Käyttötapaus 1: Sokeritaudin periytymisen tutkiminen. Tavoite: Petteri on juuri aloittanut työt uudessa työpaikassa Tietojenkäsittelytieteen laitoksella projektissa, jossa hänen tehtävänään on tutkia sokeritautia aiheuttavien geenien periytymistä Ilomantsin väestössä.

48 Tilatiedot: Nyt on to ja kello on Petteri haluaa tehdä alustavat selvitykset ennen ruokatuntia. Hän on sopinut menevänsä ystävänsä Kallen kanssa syömään klo noin 12. Petteri on työhuoneessaan oman koneensa ääressä. Hän ei ole tehnyt tästä tapauksesta aikaisempia simulaatioita ja aikoo nyt tehdä yhden kokonaisen simulaation eli luoda sukupuun ja simuloida periytymistä kerran. Mitään ylimääräisiä tiedostoja ei oteta talteen. Koska tämä on ensimmäinen simulaatio Petteri nimeää sen Simulaatio1 :ksi. Aiempia tuloksia eikä syöttötiedostoja ole tallennettu. Petteri käyttää simulaatiossaan seuraavia parametreja: number of founders = 500 individuals size of last generation = individuals number of generations = 20 chromosome length = bp SNP -rate = 1 x 10-8 number of markers = 100 effective population size = recombination rate = 1 x 10-8 samplesize = 100 sample type = affected disease mutation frequency = 20 minimum minor allele frequency = 20 prevalence = 20 penetrance = 20 Käyttötapauskuvasarjadokumentin kuvasarja Sokeritaudin periytymisen tutkiminen. esittää Petterin toiminnan hänen käyttäessään populaatiosimulaattoria Käyttötapaus 2: Aineistoa artikkelia varten. Tavoite: Petteri aikoo julkaista sokeritaudin periytymistä koskevat tutkimustuloksensa Science -lehdessä. Artikkelia varten hän tarvitsee simulaatioista tilastollista aineistoa. Tilatiedot: Nyt on pe ja kello on Petterillä on koko päivä varattu tämän työn tekemiseen. Petteri on työhuoneessaan oman koneensa ääressä. Petteri on tehnyt tästä tapauksesta aikaisempia simulaatioita. Aiemmat tulokset ja käytetyt syöttötiedot on tallennettu tekstitiedostoina. Petteri käyttää parametritiedostoa nimeltä diabetes.data tämän simulaation syötteenä. Simulaation nimeksi hän antaa diabetes100.

49 Normaalin simulaatiotuloksen lisäksi Petteri tarvitsee tietoja, jotka sisältyvät tulostiedostoihin markermapfile ja reportfile. Kuvasarjassa Aineistoa artikkelia varten Käyttötapauskuvasarjadokumentissa on esitetty käyttötapaukseen liittyvä Petterin toiminta hänen käyttäessään populaatiosimulaattoria Käyttötapaus 3: Sokeritautigeenitutkimuksen uusiminen. Tavoite: Petterin aikaisemmin tekemä sokeritaudin periytymisen simulaatio on epäonnistunut. Hän päättää suorittaa viime viikolla tekemänsä simulaation uudelleen hiukan parannetuilla parametreilla. Tilatiedot: Nyt on ma ja kello on Petteri on kahvitauolla saanut kuulla sokeritautitutkimuksen projektipäälliköltä, että simulaation tulos näyttäisi olevan täyttä roskaa. Petteri on työhuoneessaan oman koneensa ääressä. Hän on tehnyt tästä tapauksesta simulaation viime viikolla. Petteri käyttää pohjana viime viikolla tallentamaansa sukupuuta, joka on tiedostossa /results/diabetes_001/001_pedigree.txt. Myös kromosomitiedot on tallennettu tiedostoon /parameters/diabetes_001/diabetes _ilomantsi.data. Uudet arvot, joita käytetään ovat: chromosome length = bp number of markers = 300 samplesize = 200 sample type = affected disease mutation frequency = 20 minimum minor allele frequency = 20 prevalence = 20 penetrance = 20 Simulaation nimeksi Petteri antaa kuvaavasti diabetes_002. Tuloksiin sisällytetään tieto vanhemmista ja sisaruksista. Petterin toiminta hänen käyttäessään populaatiosimulaattoria on kuvattu Käyttötapauskuvasarjadokumentin kuvasarjassa Sokeritautigeenitutkimuksen uusiminen Käyttötapaus 4: Geeniparametrien toimivuuden testaus. Tavoite: Minnalla on uusi tutkimusaihe astman perinnöllisyydestä, johon liittyviä parametreja täytyy vielä kehitellä. Petteri toimii projektissa populaatiosimulaatioasiantuntijana. Minna pyytää Petteriä testaamaan uutta aineistoa.

50 Tilatiedot: Tänään on ke ja kello on Petteri on tullut projektipalaverista, jossa hän on lupautunut kokeilemaan kollegansa Minnan keräämää aineistoa perinnöllisestä sairaudesta. Petteri on työhuoneessaan oman koneensa ääressä. Astman tutkimusaineisto on kerätty viime kesänä Kainuussa Ämmänsaaren kunnan terveyskeskuksessa. Aineistoa ei ole ennen käytetty simulaatiossa, joten sitä on hyvä testata esim. 50 iteraatiolla, jotta lopulliset, tutkimuksessa käytettävät parametrit voidaan päättää. Minna on tallentanut kromosomitiedot projektin hakemistoon /astma/ammansaari_04.data Käyttötapauskuvasarjadokumentin kuvasarja Geeniparametrien toimivuuden testaus kuvaa Petterin toimintaa hänen käyttäessään populaatiosimulaattoria käyttötapauksen suorittamiseen Käyttötapaus 5: Väärät tutkimustiedot. Tavoite: Petteri on tutkimassa edelleen astmageenidataa. Hän aikoo tehdä lisää kokeiluja muuttaen Minnan antamia parametreja. Tilatiedot: Tänään on to ja kello on Petterillä on nyt varattuna aikaa tähän projektiin noin kaksi tuntia. Petteri on työhuoneessaan oman koneensa ääressä. Petteri on tallentanut muokkaamansa kromosomitiedot hakemistoon /astma/ammansaari2_04 Petteri nimeää simulaation astma2:ksi. Välittömästi painettuaan start -nappia Petteri tajuaa antaneensa uudelleen edellisenä päivänä suoritetut parametrit tiedostosta ammansaari_04.data eikä uudesta tiedostosta ammansaari2 _04.data kuten oli tarkoitus. Kuvasarja Väärät tutkimustiedot Käyttötapauskuvasarjadokumentissa esittää Petterin toiminnan hänen suorittaessaan käyttötapauksen populaatiosimulaattoria käyttäen Käyttötapaus 6: Ämmänsaaren väestön kehittyminen. Tavoite: Petteri on kiinnostunut siitä, miten Ämmänsaaren väestö on kehittynyt. Tutkimusten mukaan paikalle on muuttanut viisisataa henkeä vuonna luvulla. Nyt noin 15 sukupolven jälkeen Ämmänsaaren ja sen lähikuntien asukasluku on noin Tilatiedot: Tänään on to ja kello on Petteri tekee tänään töitä ainakin kuuteen saakka. Petteri on työhuoneessaan oman koneensa ääressä.

51 Tämä on ensimmäinen sukupuukokeilu. Aiempia tuloksia eikä syöttötiedostoja ole käytettävissä. Petteri päättää nimetä tämän sukupuusimulaation ammapuu1:ksi. Tulokset tallennetaan kaikista ensimmäisestä viidestä sukupolvesta ja siitä eteenpäin joka toisesta. Petterin toimintaa hänen käyttäessään populaatiosimulaattoria käyttötapauksen suorittamiseen esittää Käyttötapauskuvasarjadokumentin kuvasarja Ämmänsaaren väestön kehittyminen Käyttötapaus 7: Siirtolaisten vaikutus Ämmänsaaren geeniperimään. Tavoite: Petteri on kiinnostunut siitä, miten siirtolaiset ovat vaikuttaneet Ämmänsaaren geeniperimään. Todellisuudessa Ämmänsaaren väestö ei ole ollut täysin eristäytynyt vaan seudulle on muuttanut jonkin verran väkeä naapurikunnista. Tilatiedot: Tänään on to ja kello on Petteri on päättänyt tänään ahkeroida loppupäivän tämän tehtävän parissa, ainakin kuuteen saakka. Petteri on työhuoneessaan oman koneensa ääressä. Petteri käyttää samaa dataa, jota hän aiemmin käytti Ämmänsaaren väestön simulointiin, nyt kuitenkin lisätään mukaan kromosomitiedot. Kromosomin pituutena Petteripäätää käyttää 80 miljoonaa emäsparia. Petteri on tehnyt siirtymistodennäköisyystaulukon valmiiksi parametrihakemistoon nimellä migration6.txt. Tämän työn Petteri nimeää ammapuu2_6:ksi, koska mukaan otetaan kuusi naapurikuntaa. Käyttötapauskuvasarjadokumentin kuvasarja Siirtolaisten vaikutus Ämmänsaaren geeniperimään. esittää Petterin toiminnan hänen käyttäessään populaatiosimulaattoria tämän käyttötapauksen suorittamiseen.