11 Problem Dashboard Functions

11.1 Assessment Functions

11.1.1 extract_assessment_json

11.1.1.1 Main Documentation

Convert a JSON object into a tidyJSON dataframe

Description:

     Convert a JSON object into a tidyJSON dataframe

Usage:

     extract_assessment_json(assessment_json)
     
Arguments:

assessment_json: An JSON file generated through `xml_extraction
          <course> -assessments`

Value:

     A flattened dataframe with the columns `url_name`, `title`,
     `label`, `name`

11.1.2 extract_assessment_csv

11.1.2.1 Main Documentation

Convert a CSV respresenting an open_assessment.sql query into a usable
format

Description:

     Extracts the nececessary information from event JSON and discards
     it. Points possible should always be the same for each assessment.

Usage:

     extract_assessment_csv(assessment_tbl)
     
Arguments:

assessment_tbl:

Value:

     An extracted table

11.1.3 join_extracted_assessment_data

11.1.3.1 Main Documentation

Join the results of extract_assessment_csv and extract_assessment_json

Description:

     This function joins the BigQuery and XML data. This is needed to
     populate the BigQuery data with the title and label fields. If the
     ID of the assessment does not occur in the XML, it is removed
     before preceding.

Usage:

     join_extracted_assessment_data(extracted_csv, extracted_json)
     
Arguments:

extracted_csv: the result of extract_assessment_csv

extracted_json: the result of extract_assessment_csv

Value:

     A joined dataframe of the two incoming dataframes

11.1.4 summarise_joined_assessment_data

11.1.4.1 Main Documentation

Summarise assessment data for plotting

Description:

     This function checks that the number of points possible does not
     vary within title-label groups.

Usage:

     summarise_joined_assessment_data(joint_assessment, trunc_length = 20)
     
Arguments:

joint_assessment: The result of join_extracted_assessment_data

trunc_length: The length of that the label should be truncated to. Do
          set to less than 4

Value:

     A summarised dataframe of the average scores in each area.

11.1.5 plot_assessment

11.1.5.1 Main Documentation

Plot the summary assessment data

Description:

     Plot the summary assessment data

Usage:

     plot_assessment(summary_assessment)
     
Arguments:

summary_assessment: the resulting dataframe from `summary_assessment`

Value:

     A faceted bar plot

11.2 Problems Functions

11.2.1 clean_multiple_choice

11.2.1.1 Main Documentation

Clean a demographic multiple choice CSV

Description:

     This function cleans a CSV retrieved from the
     `demographic_multiple_choice` SQL script. It transforms the
     `sum_dt` column into activity_level. It also removes any
     non-multiple choice problems.

Usage:

     clean_multiple_choice(raw_csv)
     
Arguments:

raw_csv:: A dataframe from the read_csv

Value:

     A dataframe with the same dimensions as the CSV

11.2.2 create_question_lookup_from_json

11.2.2.1 Main Documentation

Parse a JSON object and return it as a flat dataframe.

Description:

     This function is required to convert the JSON derived from the
     xbundle XML into a format that other dataframes can interact with.

Usage:

     create_question_lookup_from_json(name_lookup)
     
Arguments:

name_lookup: A JSON object contain keys for `id`, `problem`,
          `chapter_name`, `chapter_name`, `choices`, `correct_id` and
          `correct`

Value:

     A flat dataframe with the above columns

11.2.3 filter_valid_questions

11.2.3.1 Main Documentation

Filter out invalid multiple choice problems

Description:

     Removes problems that were marked as 100 problems where every
     answer is correct). Also checks from the dataframe derived from
     xbundle to ensure that the problem exists in the course.

Usage:

     filter_valid_questions(problems_tbl, lookup_table)
     
Arguments:

problems_tbl: The result of `read_multiple_choice_csv`

lookup_table: The result of `create_question_lookup_from_json`

Value:

     The filtered problems_tbl

11.2.4 get_mean_scores

11.2.4.1 Main Documentation

Get mean scores.

Description:

     This function is not affected by filters. If you need a function
     that is, use `get_mean_scores_filterable`. Removes scores that do
     not appear in the xbundle XML or have a 100 questions masquerading
     as multiple choice problems.

Usage:

     get_mean_scores(problems_tbl, lookup_table)
     
Arguments:

problems_tbl: The result of `clean_multiple_choice`

lookup_table: The result of `create_question_lookup_from_json`

Value:

     A dataframe with each problem, the number of users that attempted
     the problem and the percent score

11.2.5 tally_correct_answers

11.2.5.1 Main Documentation

Count the number of correct answers for each question.

Description:

     Count the number of correct answers for each question.

Usage:

     tally_correct_answers(joined_scores)
     
Arguments:

joined_scores: `problems_tbl` and `lookup_table` joined by `id` and
          `item_response`

Value:

     A summarised dataframe of correct counts

11.2.6 calculate_percent_correct_tbl

11.2.6.1 Main Documentation

Calculate the percent of correct answers

Description:

     Each row represents a problem.

Usage:

     calculate_percent_correct_tbl(joined_scores, number_correct)
     
Arguments:

joined_scores: `problems_tbl` and `lookup_table` joined by `id` and
          `item_response`

number_correct: the result of `tally_correct_answer`

Value:

     A dataframe where each row is a row and the columns show the
     percentage and absolute number of students that got the problem
     correct.

11.2.7 get_mean_scores_filterable

11.2.7.1 Main Documentation

A filterable version of get_mean_scores

Description:

     A filterable version of get_mean_scores

Usage:

     get_mean_scores_filterable(filtered_problems_tbl)
     
Arguments:

filtered_problems_tbl: The result of `read_multiple_choice_csv`
          filtered by demographics and chapter

name_lookup: A JSON object contain keys for `id`, `problem`,
          `chapter_name`, `chapter_name`, `choices`, `correct_id` and
          `correct`

Value:

     A dataframe where each row is a row and the columns show the
     percentage and absolute number of students that got the question
     correct.

11.2.8 join_summary_lookup

11.2.8.1 Main Documentation

Join the summary and lookup tables

Description:

     Join the summary and lookup tables

Usage:

     join_summary_lookup(summarised_scores, lookup_table)
     
Arguments:

summarised_scores: the result of `get_mean_scores_filterable`

lookup_table: The result of `create_question_lookup_from_json`

Value:

     The inner join of the two dataframes

11.2.9 summarise_scores_by_chapter

11.2.9.1 Main Documentation

Summarise scores by chapter

Description:

     Calculates the average score on problems for each of the chapters
     based.

Usage:

     summarise_scores_by_chapter(summarised_scores, lookup_table)
     
Arguments:

summarised_scores: the result of `get_mean_scores_filterable`

lookup_table: The result of `create_question_lookup_from_json`

Value:

     A dataframe where each row is a chapter that contains the average
     score on that chapter

11.2.10 prepare_filterable_problems

11.2.10.1 Main Documentation

Produce a dataframe clean dataframe of all questions

Description:

     Returns the question name and it's rounded percentage (out of
     100). This function is used to prepare the data table shown at the
     bottom of the problem dashboard.

Usage:

     prepare_filterable_problems(summarised_scores, lookup_table)
     
Arguments:

summarised_scores: the result of `get_mean_scores_filterable`

lookup_table: The result of `create_question_lookup_from_json`

Value:

     A dataframe with the question and percent correct.

11.2.11 get_extreme_summarised_scores

11.2.11.1 Main Documentation

Select the easiest (or hardest) problems

Description:

     Set the index negative to receive the hardest problems.

Usage:

     get_extreme_summarised_scores(summarised_scores, index)
     
Arguments:

summarised_scores: the result of `get_mean_scores_filterable`

   index: the number of questions you wish to view

Value:

     The summarised scores dataframe with the with the number of rows
     equal to the absolute value of the index.

11.2.12 join_problems_to_lookup

11.2.12.1 Main Documentation

Left join extracted problems and lookup table

Description:

     Left join extracted problems and lookup table

Usage:

     join_problems_to_lookup(extracted_problems, lookup_table)
     
Arguments:

extracted_problems: the result of `clean_multiple_choice`

lookup_table: The result of `create_question_lookup_from_json`

Value:

     The left joined dataframe by id and choice_id, filtering out blank
     problems

11.2.13 join_users_problems

11.2.13.1 Main Documentation

The left join of joined problems and summarised scores

Description:

     The left join of joined problems and summarised scores

Usage:

     join_users_problems(joined_problems, summarised_scores)
     
Arguments:

joined_problems: `problems_tbl` and `lookup_table` joined by `id` and
          `item_response`

summarised_scores: the result of `get_mean_scores_filterable`

Value:

     A left joined dataframe of joined problems and summarised scores

11.2.14 filter_counts

11.2.14.1 Main Documentation

Count the number of filtered users for each problem

Description:

     Count the number of filtered users for each problem

Usage:

     filter_counts(joined_user_problems)
     
Arguments:

joined_user_problems: The result of `join_users_problems`

Value:

     A dataframe with the count of unique users for each question

11.2.15 filter_extreme_problem_choices

11.2.15.1 Main Documentation

Retrieve the question and choice information from the extreme problems

Description:

     Retrieve the question and choice information from the extreme
     problems

Usage:

     filter_extreme_problem_choices(lookup_table, extreme_problems, filtered_counts)
     
Arguments:

lookup_table: The result of `create_question_lookup_from_json`

extreme_problems: The result of `get_extreme_summarised_score`

filtered_counts: The result of `filter_counts`

Value:

     A dataframe with lookup information attached

11.2.16 aggregate_extracted_problems

11.2.16.1 Main Documentation

Perform the last wrangling before plotting extreme problems

Description:

     Calculates the percent of students selected each option and
     determines if that option is correct.

Usage:

     aggregate_extracted_problems(joined_user_problems, extreme_problems,
       question_choices)
     
Arguments:

joined_user_problems: The result of `join_users_problems`

extreme_problems: The result of `get_extreme_summarised_score`

question_choices: The result of `filter_extreme_problem_choices`

Value:

     A dataframe with `problem,` `choice` and percent `correct`

11.2.17 aggregate_melted_problems

11.2.17.1 Main Documentation

Aggregate questions before plotting

Description:

     Aggregate questions before plotting

Usage:

     aggregate_melted_problems(lookup_table, joined_user_problems, extreme_problems)
     
Arguments:

lookup_table: The result of `create_question_lookup_from_json`

joined_user_problems: The result of `join_users_problems`

extreme_problems: The result of `get_extreme_summarised_score`

Value:

     A dataframe ready to be plotted by `plot_aggregated_problems`

11.2.18 plot_aggregated_problems

11.2.18.1 Main Documentation

Plot aggregated problems

Description:

     This funciton is used to plot the top or bottom questions.

Usage:

     plot_aggregated_problems(agg_melted_problems)
     
Arguments:

agg_melted_problems: A dataframe with the problem and choice names as
          well as the number of students who chose each option.

Value:

     A facetted ggplot bar chart

11.2.19 plot_problem_chapter_summaries

11.2.19.1 Main Documentation

Overview plot (Chapter by Course)

Description:

     Overview plot (Chapter by Course)

Usage:

     plot_problem_chapter_summaries(chapter_summary_tbl)
     
Arguments:

chapter_summary_tbl: The aggregated data on a per chapter basis

Value:

     A ggplot bar chart