Input files voor ALVA - conventies en programma's

Hier alvast een preview op APpendix C van de beschrijving van ALVA 2.2.
Commentaar is zeer welkom
Frans Kets

Appendix C. Inlezen meetgegevens

Conventies csv files

De meetgegevens worden betrokken van RIVM en worden ingelezen in ALVA in de vorm van csv files (comma separated volumes). ALVA veronderstelt de volgende conventies:

• Ordening van de files:

  • o * Er is één, en niet meer dan één, csv file per station per maand. Alle csv files staan in één directory. In ALVA wordt een analyse gemaakt van de inhoud van deze data directory zodat alléén de gegevens worden ingelezen waarnaar gevraagd wordt in het carddeck.

  • o Uitzondering op deze regel is als er twee reeksen files bestaan, waarvan de éne reeks de tijdaanduiding in lokale Nederlandse tijd heeft, en de andere reeks de tijdaanduiding in UTC (Universele Tijd = Greenwich (winter) tijd zonder wisseling van winter- naar zomertijd). ALVA beschouwt een station waarvoor deze twee tijdaanduidingen bestaan als twee verschillende stations.

• Naamgeving van de files:

  • o De naam van het station en de maand staan gecodeerd in de naam van de file. Bovendien kan een precursor zijn gespecificeerd. Deze precursor kan noodzakelijk zijn om aan te geven hoe de inhoud van de csv moet worden geïnterpreteerd, met name de aanduiding van de tijd, of dat de gegevensreeksen gekalibreerd zijn of niet (of dat zowel gekalibreerd als niet gekalibreerde data aanwezig zijn). Het eerste teken is altijd een underscore, daarna de eventuele precursor, dan de stationnaam, dan een underscore, dan de maand aanduiding (formaat yyyymm), dan .csv.
  • o De aanwezigheid van precursor ~ geeft aan dat de tijdaanduiding niet in lokaal Nederlandse tijd wordt gegeven maar in UTC (Universele tijd = Greenwich (winter) tijd zonder wisseling van winter- naar zomertijd).
  • o De precursor X is specifiek voor paddenstoelen, waarbij de stikstofdioxide meting niet is gekalibreerd (bijv de file _XSPPS014_201812.csv). Normaliter doet RIVM een zogenaamde nachtkalibratie.
  • o De maand wordt gegeven in de notatie jjjjmm
  • o Welke stations door ALVA worden herkend is gespecificeerd in StationDirectory22.py (subroutine stationdir()). Deze python subroutine kan naar de wens van de gebruiker worden aangepast. Daarvoor gelden de volgende regels:
     Elk station is deel van een familie van stations. Het station wordt in het carddeck aangeduid met de naam “familie van station” en een getal.
     Deze combinatie van familienaam en getal (bijvoorbeeld ~RIVM 0) wordt gebruikt in het bepalen van:
    • een stationsnaam, zoals aanwezig in de filenaam (in dit voorbeeld: NL10404)
    • een alias, die in de plots van ALVA en in diagnostische teksten van ALVA wordt gebruikt (in dit voorbeeld: NL404)
    • een adres (in dit voorbeeld: Den Haag-Rebecquestraat)
    • een eigenaar (niet relevant in dit geval)
    • een email adres (niet relevant in dit geval)
    o In het voorbeeld hierboven bevat de file met filenaam _~NL10404_202009.csv de gegevens van 1 september 2009 middernacht (op UTC tijd) tot het eind van de maand. In Nederlandse lokale tijd begint deze tijdreeks op 30 augustus 10 uur ’s avonds (verschil Nederlandse zomertijd met UTC).

• De kolommen van de csv files.

  • o Scheidingsteken, en conventie voor decimaal teken:
  • Scheidingsteken, dat de scheiding tussen kolommen aangeeft, is een komma (“,”).
  • Het decimaalteken is een punt “.”.
  • Hiermee volgt ALVA de Amerikaanse conventie.
  • o Tijdaanduiding:
  • De naam van de tijdkolom is altijd “periode”.
  • Metingen zijn altijd op hele uren.
  • Er wordt onderscheid gemaakt tussen de NL lokale tijd, die wordt ingelezen in een formaat zonder aanduiding van tijdzone (naïeve tijd), en de tijd met tijdzone aanduiding in UTC vorm (UTC = Universele tijd = Greenwich (winter) tijd zonder wisseling van winter- naar zomertijd).
  • De volgende formaten worden herkend:
  • Naïef: jjjj-mm-dd uu:mm:ss (voorbeeld: 2020-09-01 12:00:00)
  • UTC : jjjj-mm-ddTuu:mm:ss+00:00 (voorbeeld: 2017-01-01T01:00:00+00:00)
  •         jjjj-mm-dd uu:mm:ss+00:00              (voorbeeld: 2020-04-18 11:00:00+00:00)
    
  • Het naïeve formaat wordt geleverd door de getrivm.exe van Diederik van Hemert en de webinterface van Eddy Cornelisse. Het eerste UTC formaat komt van de interface naar luchtmeetnet.nl geschreven door Walter Takens (RIVMplain) , het laatste formaat komt van de getrivm.exe geschreven door Walter Takens. Deze laatste software benadert samenmeten.rivm.nl via de officiële RIVM API. Al deze programma’s, behalve de webinterface van Eddy Cornelisse, worden hieronder beschreven.
  • o De meetwaarden:
  • Er wordt een beperkt aantal types metingen herkend. De namen van deze meetwaardes zijn vermeld in het hoofdstuk “De attributen, wat voor een soort gegevens worden gebruikt?”. De daar genoemde namen worden gebruikt in de carddecks. In de carddecks worden geen andere namen geaccepteerd (behalve de namen van grootheden die door één of andere bewerking in ALVA worden gegenereerd). Deze namen zijn over het algemeen kort, wat handig is wanneer lijstjes worden geprint. Als voorbeeld: in ALVA wordt met P10 het grove fijnstof PM10 aangeduid. De completere aanduiding (bijvoorbeeld PM10) of een wat explicietere beschrijving van de attribuut (bijvoorbeeld Roet in plaats van FN) wordt als bijschrift bij plots gegeven.
  • De namen van de kolommen in de csv files kunnen verschillen van de in het bovengenoemde hoofdstuk genoemde namen. De vertaling van de naam als gebruikt in de csv file naar de in ALVA geaccepteerde namen gebeurt bij het inlezen en is verschillend voor de verschillende families van meetstations en van hoe de file is geproduceerd.
  • Er is dus sprake van drie benamingen van de meetwaarden; deze worden vermeld in de file StationDirectory22.py in de subroutine attribdir().
    DE ONDERSTAANDE TABEL KOMT HIER NIET GOED OVER
    Naam in csv file
    (afhankelijk van type file) Naam in ALVA
    [te gebruiken in carddeck] Betekenis /
    “mooiere” naam
    NO2 NO2_gemeten NO2 (gemeten)
    NO2_ref1 NO2_ref1 NO2 (ref 1)
    NO2_ref2 NO2_ref2 NO2 (ref 2)
    NO2_kal, NO2_KAL
    NO2 NO2 NO2 (geijkt)
    P10, PM10 P10_gemeten PM10 (gemeten)
    P10_ref1, PM10_ref1 P10_ref1 PM10 (ref 1)
    P10_ref2, PM10_ref2 P10_ref2 PM10 (ref 2)
    P10_kal, PM10_kal, P10_KAL, PM10_KAL,
    P10 P10 PM10 (geijkt)
    P25, PM25 P25_gemeten PM25 (gemeten)
    P25_ref1, PM25_ref1 P25_ref1 PM25 (ref 1)
    P25_ref2, PM25_ref2 P25_ref2 PM25 (ref 2)
    P25_kal, PM25_kal, P25_KAL, PM25_KAL,
    P25 P25 PM25 (geijkt)
    temp, TEMP temp Temperatuur sensor
    rh, RH rh Luchtvochtigheid sensor
    ld, LD ld Luchtdruk sensor
    FN FN Roet
    O3 O3 Ozon
    NO NO NO
    SO2 SO2 SO2
    o Andere in de csv files genoemde attributen:
    Kolommen in de csv files met namen die niet in de linker kolom van bovengenoemde lijst zijn vermeld worden genegeerd.

Programma’s om gegevens op te halen.

GetRIVM (oude versie)
Diederik van Hemert (LV2, Leidschendam-Voorburg) heeft de eerste versie van getRIVM gebouwd. Dit is een vb.net applicatie en draait alleen op Windows of een Windows emulator. De applicatie kan van elke Windows console worden gedraaid (te openen via Start – Systeem – Opdrachtprompt).
Deze versie leest de gegevens van de oude versie van samenmeten.rivm.nl
Versie 1 van GetRivm levert gegevens per maand op voor elk station. ALVA veronderstelt deze indeling in zijn inleesprocedure.
GEBRUIKSAANWIJZING GETRIVM VERSIE 1:
Afbeelding1
In de directory moet het programma getRivm.exe aanwezig zijn. Er wordt gebruik gemaakt van een commandline interface. Bij het downloaden van RIVM ga je door de volgende stappen
a. Verzamel de gegevens van de stations op de RIVM website.
Met het commando getRivm.exe reset maak je het bestand _stations.csv aan. Deze bevat alle meetstations & meta gegevens die via de site beschikbaar zijn. De batfile Reset.bat bevat dit commando.
b. Het bestand _stations.csv bevat per station de stationsnaam en de kitnaam. Deze zijn nodig bij de aanroep van getRivm om de gegevens van het station te downloaden.
c. Omdat de file _stations.csv erg groot is, is het aan te raden een programmatje te schrijven om deze gegevens automatisch te selecteren.
d. De aanroep getRivm.exe station kit jaar maand (jaar en maand als getallen) download gegevens van de website en slaat deze op in een csv file. De naamgeving van de csv file is:
underscore stationsnaam underscore jaar maand punt csv.
Voorbeeld: voor de gegevens van station SPPS018, met kitnaam RTD_15708092, voor jaar 2018 maand 7 gebruik je getRivm.exe SPPS018 RTD_15708092 2018 7 . Het resultaat komt dan in file _SPPS018_201807.csv . Alle files worden geplaatst in een subdirectory _SRC.
e. Aangezien men typisch veel files moet downloaden is het verstandig deze commando’s in een programmatje te genereren en in een batfile op te slaan.

GetRIVM (nieuwe versie)
Walter Takens (Gouda) heeft een versie van getRIVM gebouwd op de door RIVM gebouwde API (Application Programmers Interface) van de RIVM website. Deze software heeft twee bronnen van informatie: de samenmeten.rivm API, en de API van luchtmeetnet.nl. De laatste website geeft de gegevens van de officiële RIVM stations.
Het programma is geschreven in python, en vereist daarom een environment waarin python bekend is. Net als in Appendix A kan men de software benaderen via de Anaconda Prompt (via Start menu). De opzet van de ALVA omgeving in Appendix A bevat alle python pakketten die voor getRIVM nodig zijn. getRIVM gebruikt een SQLite database als een tussentijdse opslag tussen de opslag op de RIVM website en de opslag als csv files. De SQLite database kan apart worden bestudeerd via een DB browser (te downloaden van het adres https://sqlitebrowser.org/).
De getRIVM software is nu benaderbaar via de Anaconda prompt (in Start menu) met de volgende stappen:

  1. Activeren van de environment:
    conda activate ALVA
  2. Navigeren naar de directory waar de software aanwezig is (bijvoorbeeld :Documents\Calc\getRIVM):
    cd Documents
    cd Calc
    cd getrivm
  3. Een handleiding hoe getrivm te gebruiken is te verkrijgen door in te typen:
    python getrivm.py –man > handleiding.txt
    Deze versie van getRivm is erg flexibel. Men kan er voor kiezen om de Sqlite database geheel te vullen, of men kan elke keer selectief gegevens van de website halen en die dan vervolgens door te sluizen naar een csv file. Het is aan te bevelen scripts te ontwikkelen voor vaste taken, en deze als batfiles uit te voeren.
    De tijden in de csv files zijn in UTC tijd.
    De software is op een dusdanige manier geschreven dat het niet gemakkelijk aan te passen is door anderen dan de auteurs.

RIVMplain
RIVMplain is python software ontwikkeld door Walter Takens (Gouda) waarbij gegevens van luchtmeetnet.nl worden gelezen. De software is aan te passen voor eigen taken. Output geschikt voor ALVA wordt gegenereerd in een versie RIVMplainkts.py, met een functionaliteit die beperkt is ten opzichte van de oorspronkelijke RIVM plain.
RIVMplainkts.py kan worden aangeroepen als volgt, met station (stationnaam), year (in formaat yyyy) en month (getal van 1 – 12) als variabelen.:
python rivmplainkts.py --s station --y year
python rivmplainkts.py --s station --y year --m month
De gegenereerde outputfiles worden geplaatst in een subdirectory _SRC. De tijden in de csv files zijn in UTC tijd.