Skip to contents

Check objectives for data problems

Source: R/check_objectives.R
check_objectives.Rd

Reads the objectives one step before they are mapped and reports what is wrong with them. Takes what read_objectives() and read_objectives_table() return, so a YAML file edited by hand and a spreadsheet built by copying columns are checked by the same code – they carry the same mistakes, and a check that lived in one reader would miss the other.

Usage

check_objectives(
  x,
  course_id = "course",
  redundancy_threshold = 0.85,
  verbosity = 1L
)

Arguments

x

Named list of objectives, as returned by read_objectives() or read_objectives_table().

course_id

Character: Course identifier, used to build the ids in the report. Pass the one map_course_to_sessions() will be given and the ids match the mapping's.

redundancy_threshold

Numeric [0, 1]: Token overlap at or above which a near-duplicate pair is reported. NULL skips the check.

verbosity

Integer: If > 0, print a one-line summary.

Value

data.frame of check, severity, scope, id, id_b, text and detail, most severe first; zero rows if nothing was found, returned invisibly in that case so a clean file prints its message and nothing else. id is an objective id, or a session key for a finding about a whole session; id_b is the other half of a pair. Counts are in the "run" attribute.

Details

Unlike the check_* argument validators this package inherits, this one reports rather than aborts: every problem in the file is found in one pass, and the table can be handed to the person who can answer it.

What it checks

Per objective, wherever it sits – course, session or assessment:

  • empty_text – empty or whitespace-only (error).

  • whitespace – untrimmed, a non-breaking space pasted from Word, an embedded tab or newline, repeated spaces.

  • numbering – a "1." or "LO2:" prefix left over from the source layout, which otherwise becomes part of the text the model scores.

  • truncated – ends mid-sentence, or is exactly 255 characters.

  • short_text – a single word: a topic label rather than an objective.

  • duplicate_objective – the same text twice in one list, compared ignoring case and spacing.

Across the file:

  • shared_text – a session objective identical to a course objective. Scoring a statement against itself is congruent by construction, so the cell says nothing.

  • identical_sessions – two sessions holding the same objectives.

  • empty_session, session_key, duplicate_session_key – a session with nothing in it, a key that is not session_NN and so lands in every id it builds as written, or a key used twice.

  • structure – a missing or malformed objectives or sessions element (error).

  • redundancy – near-duplicate pairs, from the same token overlap redundant_objectives() uses. Running it here is the point: it costs nothing and it happens before the mapping is paid for, rather than after.

What it does not do

It corrects nothing. Rewriting an objective would change what the instructors said, and dropping one would renumber every id after it. It also does not judge wording: an objective that opens with "Understand" names no observable behavior, but that is a matter for the instructors and for the revision step, not a data problem.

Author

EDG

Examples

if (FALSE) { # \dontrun{
  obj <- read_objectives_table("datasci213.xlsx", course_name = "DS 213")
  check_objectives(obj, course_id = "datasci213")
} # }