Anunțând … schematic | R-BLOGGERS

Motivație

După ce am construit și implementat o serie de aplicații strălucitoare sau API -uri care necesită utilizatorilor să încarce date, am observat un punct de durere obișnuit: Cum comunic în termeni simpli cu probleme cu datele și, mai important, care sunt aceste probleme? Aveam nevoie de o modalitate de a prezenta utilizatorului mesaje de eroare care satisfac două nevoi:

1. Simplu și non-tehnic: permite dezvoltatorilor să explice problema, mai degrabă decât să oblige utilizatorii să înțeleagă aspectele tehnice ale fiecărui test (nu doriți să le explicați utilizatorilor ce is.logical mijloace).
2. Verificare holistică: prezentați toate problemele de validare, mai degrabă decât oprirea evaluării la primul eșec.

Există deja o serie de pachete de validare a datelor pentru R, inclusiv (dar fără a se limita la) PointBlank, Data.Validator și Validate; Deci, de ce să introducem un jucător nou? Schema împărtășește cu siguranță asemănări cu multe dintre aceste pachete, dar în cazul în care cred că inovează pe soluțiile existente se află în combinația sa unică de următoarele:

1. Ușor: dependențe minime, cu un accent clar pe verificarea datelor fără clopotele și fluierele de grafică, tabele și ce nu.
2. Orientată pe utilizator, dar prietenoasă cu dezvoltatorii: dezvoltatorii (în special cei care se apropie dintr-o mentalitate ordonată) le va plăcea sintaxa expresivă; Utilizatorii vor aprecia instrucțiunile informative despre cum să rezolve în mod cuprinzător problemele de date (nu mai sunt whack-a-mole cu rezolvarea unei probleme doar pentru a învăța că există multe altele).
3. Ușor de integrat în aplicații (de exemplu, strălucitor, instalator): schematice returnează mesaje de eroare, mai degrabă decât rapoarte sau date.Frames, ceea ce înseamnă că nu aveți nevoie de o logică suplimentară pentru a declanșa o eroare de timp de rulare; Treceți doar mesajul de eroare într -o notificare sau cod de eroare.

Cum funcționează

Schema este extrem de simplă. Trebuie doar să faceți două lucruri: creați o schemă și apoi verificați un date.frame împotriva schemei.

O schemă este un set de reguli pentru coloanele dintr -un cadru de date.frame. O regulă constă din două părți:

1. Selector – coloana (coloana) pe care se aplică regula
2. Predicat – o funcție care trebuie să returneze un singur adevărat sau fals care indică trecerea sau eșecul cecului

Să ne imaginăm un scenariu în care avem date de sondaj și dorim să ne asigurăm că se potrivește cu așteptările noastre. Iată câteva date de sondaj de probă:

survey_data <- data.frame(
  id = c(1:3, NA, 5),
  name = c("Emmett", "Billy", "Sally", "Woolley", "Duchess"),
  age = c(19.2, 10, 22.5, 19, 19),
  sex = c("M", "M", "F", "M", NA),
  q_1 = c(TRUE, FALSE, FALSE, FALSE, TRUE),
  q_2 = c(FALSE, FALSE, TRUE, TRUE, TRUE),
  q_3 = c(TRUE, TRUE, TRUE, TRUE, FALSE)
)

Declarăm o schemă folosind schema() și să -i furnizeze reguli care urmează formatului selector ~ predicate:

library(schematic)

my_schema <- schema(
  id ~ is_incrementing,
  id ~ is_all_distinct,
  c(name, sex) ~ is.character,
  c(id, age) ~ is_whole_number,
  education ~ is.factor,
  sex ~ function(x) all(x %in% c("M", "F")),
  starts_with("q_") ~ is.logical,
  final_score ~ is.numeric
)

Atunci folosim check_schema Pentru a evalua datele noastre împotriva schemei. Orice erori vor fi capturate în mesajul de eroare:

check_schema(
  data = survey_data,
  schema = my_schema
)

Error in `check_schema()`:
! Schema Error:
- Columns `education` and `final_score` missing from data
- Column `id` failed check `is_incrementing`
- Column `age` failed check `is_whole_number`
- Column `sex` failed check `function(x) all(x %in% c("M", "F"))`

Mesajul de eroare va combina coloanele într -o singură declarație dacă partajează aceeași problemă de validare. Schematica va raporta automat, de asemenea, dacă există coloane declarate în schemă din date.

Personalizarea mesajului

În mod implicit, mesajul de eroare este util pentru dezvoltatori, dar dacă trebuie să comunicați nepotrivirea schemei unei persoane non-tehnice, vor avea probleme să înțeleagă unele sau toate erorile. Puteți personaliza ieșirea fiecărei reguli introducând regula ca un argument numit.

Să rezolvăm exemplul anterior pentru a face mesajele mai inteligibile.

my_helpful_schema <- schema(
  "values are increasing" = id ~ is_incrementing,
  "values are all distinct" = id ~ is_all_distinct,
  "is a string" = c(name, sex) ~ is.character,
  "is a string with specific levels" = education ~ is.factor,
  "is a whole number (no decimals)" = c(id, age) ~ is_whole_number,
  "has only entries 'F' or 'M'" = sex ~ function(x) all(x %in% c("M", "F")),
  "includes only TRUE or FALSE" = starts_with("q_") ~ is.logical,
  "is a number" = final_score ~ is.numeric
)

check_schema(
  data = survey_data,
  schema = my_helpful_schema
)

Error in `check_schema()`:
! Schema Error:
- Columns `education` and `final_score` missing from data
- Column `id` failed check `values are increasing`
- Column `age` failed check `is a whole number (no decimals)`
- Column `sex` failed check `has only entries 'F' or 'M'`

Și asta este cu adevărat tot ce există. Schema vine cu câteva funcții predicate la îndemână precum is_whole_number() care este o versiune mai permisivă a is.integer() Acest lucru permite coloanele stocate ca numerice sau duble, dar necesită totuși valori non-decimale.

Mai mult, schema include o mână de modificatori care vă permit să schimbați comportamentul unor predicate, de exemplu, permițând NAS cu mod_nullable():

# Before using `mod_nullable()` this rule triggered an error
my_schema <- schema(
  "all values are increasing (except empty values)" = id ~ mod_nullable(is_incrementing)
)

check_schema(
  data = survey_data,
  schema = my_schema
)

Concluzie

În cele din urmă, speranța mea este să fac schematică cât mai simplă și să ajut atât dezvoltatorii, cât și utilizatorii. Este un pachet pe care l -am proiectat inițial cu singura intenție de a mă salva de la scrierea codului de validare care preia 80% din codul de bază.¹ Sper că vi se pare util.