tuiksdmx Sigla pachetului RIntroducere
Accesarea statisticilor oficiale în mod programatic ar trebui să fie simplă. În practică, totuși, găsirea setului de date potrivit este doar o parte a problemei. De asemenea, un analist trebuie să înțeleagă dimensiunile, clasificările disponibile, codurile valide și structura cererii acceptate de furnizorul de date.
Acest lucru este deosebit de relevant pentru SDMX (Statistical Data and Metadata eXchange), standardul internațional utilizat pe scară largă pentru schimbul de date statistice și metadate. SDMX oferă un cadru consistent pentru descrierea seturilor de date statistice multidimensionale, dar nu elimină nevoia de a înțelege structurile acestora.
m-am dezvoltat tuiksdmxun pachet R open-source care oferă un interfață autentificată, bazată pe metadate la serviciul SDMX REST al Institutului de Statistică Turc (TÜİK sau TurkStat). Scopul nu este pur și simplu descărcarea datelor. Este de a face pașii care conduc la o cerere validă și reproductibilă mai ușor de descoperit, înțeles și verificat.
De ce un client bazat pe metadate?
Un set de date SDMX nu este neapărat un tabel dreptunghiular convențional care așteaptă să fie descărcat. Un particular Flux de date este asociat cu a Definirea structurii datelor (DSD), care specifică dimensiunile utilizate pentru identificarea unei serii statistice. Aceste dimensiuni pot face referire Liste de coduri definirea valorilor permise, în timp ce Concepte descrie ce reprezintă dimensiunile.
Prin urmare, un flux de lucru tipic implică mai multe întrebări:
- Ce flux de date conține statisticile de care am nevoie?
- Ce dimensiuni și clasificări definesc acel flux de date?
- Ce coduri sunt valabile pentru dimensiunile relevante?
- Cum pot solicita observații fără a asambla manual o cheie SDMX brută?
tuiksdmx reunește acești pași. Acceptă descoperirea Dataflow, inspecția DSD și Codelist, validarea filtrului bazată pe metadate, construcția cheii conștientă de structură și recuperarea observațiilor. De asemenea, ajută la distingerea între codurile definite în metadate și cele prezente efectiv în datele returnate.
Distincția contează: un cod valabil nu înseamnă că există observații pentru el în fiecare perioadă.
Noțiuni de bază
Instalați pachetul
install.packages("pak") # If needed
pak::pak("MFatihTuzen/tuiksdmx")
library(tuiksdmx)
Configurați autentificarea
Serviciul TÜİK SDMX necesită în prezent autentificare pentru punctele sale finale de date. tuiksdmx acceptă o cheie API și gestionează fluxul de lucru de autentificare intern. Pentru utilizare regulată, vă recomand să păstrați cheia în personalul dvs .Renviron fișier, mai degrabă decât încorporarea acreditărilor într-un script R.
TUIK_SDMX_API_KEY=YOUR_OWN_API_KEY
Puteți deschide acel fișier folosind usethis::edit_r_environ() dacă ai foloseste asta instalat. Reporniți R după ce îl salvați. Pachetul va citi apoi variabila de mediu automat.
Nu vă publicați niciodată cheia API sau jetoanele de acces într-un script, o postare de blog, un depozit sau un raport de problemă. Trebuie să obțineți și să configurați propriile acreditări; instalarea pachetului nu oferă o cheie API.
Găsiți un flux de date
În loc să începeți cu un punct final codificat, căutați fluxurile de date disponibile după subiect:
# Search by an English description flows <- tuik_search_dataflows( "consumer price", language = "en", limit = 10 ) flows
Puteți căuta și în turcă, de exemplu cu tuik_search_dataflows("tüketici fiyat"). Acest lucru face posibilă descoperirea fără a cunoaște în prealabil identificatorul Dataflow.
Explorați dimensiunile înainte de a prelua date
Următorul exemplu utilizează prețul de consum Dataflow DF_TUFE_SDMX_TT01inspectat în timpul dezvoltării pachetului. Deoarece cataloagele furnizorilor pot evolua, verificați întotdeauna metadatele curente înainte de a crea un flux de lucru de producție.
# Explore the structure without retrieving observations
tuik_explore("DF_TUFE_SDMX_TT01")
# Inspect the codes associated with one dimension
tuik_explore(
"DF_TUFE_SDMX_TT01",
dimension = "DEGISIM"
)
Aceasta este una dintre deciziile centrale de proiectare din spatele pachetului: înțelegeți mai întâi structura datelor, apoi solicitați observații. Reduce nevoia de a ghici identificatori de dimensiune sau de a construi manual chei de interogare.
Preluați observațiile
Odată ce fluxul de date și perioada relevante sunt cunoscute, recuperarea datelor poate fi concisă:
cpi <- tuik_get_data( "DF_TUFE_SDMX_TT01", start_period = "2026-01", end_period = "2026-01" ) head(cpi)
Există o calificare importantă: această solicitare preia toate seriile pentru perioada de observare selectatănu doar un indicator CPI. Numai restrângerea intervalului de timp nu garantează un răspuns mic.
Pentru o interogare mai concentrată, pachetul acceptă filtre de dimensiuni cu nume, validate cu metadate:
selected <- list( REF_AREA = "TR", FREQ = "M", DEGISIM = "1", SINIFLAMA_DUZEYI = "2" ) # Validate the chosen values against the Dataflow structure tuik_explore( "DF_TUFE_SDMX_TT01", filters = selected )
O limitare practică merită subliniată. Filtre complete cu cheie de serie permite pachetului să construiască o solicitare SDMX țintită pe partea serverului. Filtre parțialepe de altă parte, necesită un explicit allow_all = TRUE opt-in și poate duce la o descărcare mai largă, urmată de filtrare în R. Pachetul nu prezintă acest lucru ca o solicitare eficientă de cheie parțială pe partea serverului și nici nu allow_all impune o limită de dimensiune a datelor. Ghidul de filtrare și performanță explică distincția în detaliu.
O întrebare subtilă, dar importantă: ce coduri au de fapt date?
Metadatele și datele observate răspund la diferite întrebări.
O Lista de coduri definește setul teoretic de coduri pentru o dimensiune. Dar este posibil ca unele dintre aceste coduri să nu apară în observațiile returnate pentru o anumită perioadă și un anumit set de filtre.
tuiksdmx abordează această distincție prin două operațiuni complementare:
profile <- tuik_flow_profile("DF_TUFE_SDMX_TT01")
# Permitted codes in the metadata
tuik_dimension_codes(profile, dimension = "DEGISIM")
# Codes observed in the data for a bounded request
observed <- tuik_available_codes(
profile,
dimension = "COICOP_2018",
start_period = "2026-01",
end_period = "2026-01",
allow_all = TRUE
)
observed
A doua operațiune inspectează observatii recuperatedeci rezultatul este condiționat de cerere. Este nu o implementare a SDMX ContentConstraint interogări. Mai mult decât atât, exemplul permite în mod deliberat o descărcare potențial largă și ar trebui folosit cu atenție la dimensiunea răspunsului.
Pentru munca statistică, această separare ajută la prevenirea unei neînțelegeri comune: universul categoriilor valide nu este neapărat același cu categoriile populate de date.
Documentație și domeniul actual
Pachetul include documentație privind autentificarea, descoperirea fluxului de date, metadatele DSD, filtrarea, disponibilitatea observată și decodarea etichetelor de cod. În loc să repet acele ghiduri aici, vă recomand să începeți cu ghidul Noțiuni introductive și referința la funcție.
Versiunea inițială este concentrată în mod deliberat. tuiksdmx este un client SDMX, nu o interfață de uz general pentru fiecare resursă de pe portalul TÜİK. Nu pretinde că acceptă fiecare caracteristică de serviciu SDMX sau fiecare Dataflow fără teste suplimentare. Structurile furnizorilor și comportamentul de autentificare se pot schimba, astfel încât munca reproductibilă necesită încă validare și limite sensibile ale cererilor.
Gânduri finale
Când lucrați cu un API, este tentant să judecați un client numai după cât de repede returnează un tabel. Pentru datele statistice structurate, cred că o măsură mai utilă este dacă putem identificați ceea ce am solicitat, validați alegerile pe care le-am făcut și reproduceți rezultatul mai târziu.
Asta e ideea din spate tuiksdmx: aduceți descoperirea, metadatele statistice, validarea și recuperarea datelor în același flux de lucru R, ținând în același timp echipamentul SDMX brut în mare parte din cale.
Salut feedback, rapoarte de erori reproductibile și contribuții prin intermediul depozitului de proiect. Pachetul este un proiect open source dezvoltat independentnu un produs software oficial TÜİK.
