9 Discussion Forum Dashboard Functions

9.1 Wrangling Functions

9.1.1 get_activity_levels

9.1.1.1 Main Documentation

Convert sum_dt to activity_level.

Description:

     Convert sum_dt to activity_level.

Usage:

     get_activity_levels(forum)
     
Arguments:

   forum: A forum dataframe.

Value:

     The same dataframe with a new column for activity_level.

Examples:

     get_activity_levels(forum)
     

9.1.2 get_discussion_vars_json

9.1.2.1 Main Documentation

Get the variables associated with each forum element in the JSON file.
(for use in 'prepare_json').

Description:

     Get the variables associated with each forum element in the JSON
     file. (for use in 'prepare_json').

Usage:

     get_discussion_vars_json(i, all_elements)
     
Arguments:

       i: An iterator.

all_elements: A nested list containing attributes for each course
          element.

Value:

     A vector containing the 'commentable_id', 'display_name',
     'discussion_category', and 'discussion_target' of a course
     element.

Examples:

     get_discussion_vars_json(i, all_elements)
     

9.1.3 get_discussion_vars_xml

9.1.3.1 Main Documentation

Get the variables associated with each forum element in the XML file
(for use in 'prepare_xml').

Description:

     Get the variables associated with each forum element in the XML
     file (for use in 'prepare_xml').

Usage:

     get_discussion_vars_xml(i, all_parameters)
     
Arguments:

       i: An iterator.

all_parameters: An XML tree containing all the parameters associated
          with each discussion node.

Value:

     A vector containing the 'display_name', 'discussion_category', and
     'discussion_target' of a course element.

Examples:

     get_discussion_vars_xml(i, all_parameters)
     

9.1.4 infer_post_subcategories

9.1.4.1 Main Documentation

Infer the subcategories of each post, even if it's a response post or a
comment.

Description:

     Infer the subcategories of each post, even if it's a response post
     or a comment.

Usage:

     infer_post_subcategories(forum)
     
Arguments:

   forum: A forum dataframe.

Value:

     The same dataframe with commentable_id filled in for everything.

Examples:

     infer_post_subcategories(forum)
     

9.1.5 prepare_json

9.1.5.1 Main Documentation

Prepare the JSON file for joining with the XML file.

Description:

     Prepare the JSON file for joining with the XML file.

Usage:

     prepare_json(json)
     
Arguments:

    json: A JSON file containing information about the course elements.

Value:

     A dataframe with four columns: 'commentable_id', 'display_name',
     'discussion_category', and 'discussion_target'.

Examples:

     prepare_json(json)
     

9.1.6 prepare_posts

9.1.6.1 Main Documentation

Prepare the forum posts.

Description:

     Prepare the forum posts.

Usage:

     prepare_posts(forum)
     
Arguments:

   forum: A dataframe with one post per row.

Value:

     The prepared forum posts data.

Examples:

     prepare_posts(forum)
     

9.1.7 prepare_searches

9.1.7.1 Main Documentation

Prepare the forum searches dataframe.

Description:

     Prepare the forum searches dataframe.

Usage:

     prepare_searches(forum)
     
Arguments:

   forum: A dataframe with one search event per row.

Value:

     The forum searches data with a new column for activity level.

Examples:

     prepare_searches(forum)
     

9.1.8 prepare_views

9.1.8.1 Main Documentation

Prepare the forum views dataframe.

Description:

     Prepare the forum views dataframe.

Usage:

     prepare_views(forum)
     
Arguments:

   forum: A dataframe with one read event per row.

Value:

     The prepared forum views data.

Examples:

     prepare_views(forum)
     

9.1.9 prepare_words

9.1.9.1 Main Documentation

Prepare the forum words.

Description:

     Prepare the forum words.

Usage:

     prepare_words(forum)
     
Arguments:

   forum: A dataframe with one row per post.

Value:

     The dataframe with each row containing a word, prepared for
     joining with the forum elements.

Examples:

     prepare_words(forum)
     

9.1.10 prepare_xml

9.1.10.1 Main Documentation

Prepare the XML file for joining with the JSON file.

Description:

     Prepare the XML file for joining with the JSON file.

Usage:

     prepare_xml(xml)
     
Arguments:

     xml: An XML file containing information about the course elements.

Value:

     A dataframe with three columns: 'display_name',
     'discussion_category', and 'discussion_target'.

Examples:

     prepare_xml(xml)
     

9.1.11 wrangle_forum

9.1.11.1 Main Documentation

Write the forum posts and forum words to csv.

Description:

     Write the forum posts and forum words to csv.

Usage:

     wrangle_forum(posts_input_path, views_input_path, searches_input_path,
       json_input_path, xml_input_path, posts_output_path, words_output_path,
       views_output_path, searches_output_path, elements_output_path)
     
Arguments:

posts_input_path: The path to the CSV file containing the forum posts
          data.

views_input_path: The path to the CSV file containing the forum reads
          data.

searches_input_path: The path to the CSV file containing the forum
          searches data.

json_input_path: The path to the JSON file containing data on all
          course elements.

xml_input_path: The path to the XML file containing data on the course
          structure.

posts_output_path: The desired path to which to write the prepared
          forum posts dataframe.

words_output_path: The desired path to which to write the prepared
          forum words dataframe.

views_output_path: The desired path to which to write the prepared
          forum views dataframe.

searches_output_path: The desired path to which to write the prepared
          forum searches dataframe.

elements_output_path: The desired path to which to write the prepared
          forum elements dataframe.

Value:

     None.

Examples:

     wrangle_forum(csv_path, json_path, xml_path)
     

9.2 Server Functions

9.2.1 apply_forum_filters

9.2.1.1 Main Documentation

Apply the selected filter settings to the forum data.

Description:

     Apply the selected filter settings to the forum data.

Usage:

     apply_forum_filters(input_df, forum_elements, activity_level = "All",
       gender = "All", registration_status = "All", category = "All")
     
Arguments:

input_df: The input dataframe.

forum_elements: The forum elements dataframe.

activity_level: One of 'under_30_min', '30_min_to_5_hr', 'over_5_hr',
          or (default) 'All'.

  gender: One of 'male', 'female', 'other', or (default) 'All'.

registration_status: One of 'audit', 'verified', or (default) 'All'.

category: One of the forum categories.

Value:

     'filtered_df' A dataframe filtered by the selected settings.

Examples:

     apply_forum_filters(forum_posts, forum_elements, "All", "All", "All")
     

9.2.2 calculate_forum_searches

9.2.2.1 Main Documentation

Calculates the number of unique users who searched for each search
query, given the selected filters.

Description:

     Calculates the number of unique users who searched for each search
     query, given the selected filters.

Usage:

     calculate_forum_searches(forum_searches = wrangled_forum_searches,
       forum_elements, activity_level, gender, registration_status, category)
     
Arguments:

forum_searches: The wrangled forum searches dataframe.

forum_elements: The forum elements dataframe.

activity_level: The activity level of the students.

  gender: The gender of the students.

registration_status: The registration status of the students.

category: The forum category.

Value:

     'forum_searches' The filtered forum searches dataframe.

Examples:

     calculate_forum_searches(wrangled_forum_searches, "under_30_min", "female", "verified", "Part 3")
     

9.2.3 count_authors

9.2.3.1 Main Documentation

Count the number of authors for each subcategory in an input forum.

Description:

     Count the number of authors for each subcategory in an input
     forum.

Usage:

     count_authors(input_forum, wrangled_forum_elements)
     
Arguments:

input_forum: The input dataframe containing a row for each post in the
          forum.

wrangled_forum_elements: A dataframe containing information about each
          of the forum subcategories.

Value:

     'author_counts' A dataframe containing the unique author counts
     for each subcategory in the forum.

Examples:

     count_authors(wrangled_forum_posts)
     

9.2.4 count_posts

9.2.4.1 Main Documentation

Count the number of posts for each subcategory in an input forum.

Description:

     Count the number of posts for each subcategory in an input forum.

Usage:

     count_posts(input_forum, wrangled_forum_elements)
     
Arguments:

input_forum: The input dataframe containing a row for each post in the
          forum.

wrangled_forum_elements: A dataframe containing information about each
          of the forum subcategories.

Value:

     'post_counts' A dataframe containing the post counts for each
     subcategory in the forum.

Examples:

     count_posts(wrangled_forum_posts)
     

9.2.5 count_views

9.2.5.1 Main Documentation

Count the number of view events for each subcategory in an input forum.

Description:

     Count the number of view events for each subcategory in an input
     forum.

Usage:

     count_views(input_forum, wrangled_forum_elements)
     
Arguments:

input_forum: The input dataframe containing a row for each read event
          in the forum.

wrangled_forum_elements: A dataframe containing information about each
          of the forum subcategories.

Value:

     'view_counts' A dataframe containing the read counts for each
     subcategory in the forum.

Examples:

     count_views(wrangled_forum_views)
     

9.2.6 filter_forum_elements

9.2.6.1 Main Documentation

Filter the forum elements by the selected filter variables.

Description:

     Filter the forum elements by the selected filter variables.

Usage:

     filter_forum_elements(forum_elements, category)
     
Arguments:

forum_elements: The forum elements dataframe that was passed in from
          the wrangling script.

category: The forum category that the user has selected.

Details:

     The forum elements dataframe only needs to be filtered by
     category, since it doesn't include any variables related to
     students.

Value:

     'filtered_forum_elements' The same dataframe, filtered by category
     if appropriate.

Examples:

     filter_forum_elements(wrangled_forum_elements, "Part 1")
     

9.2.7 filter_wordcloud_data

9.2.7.1 Main Documentation

Filter the wordcloud data by the selected filters.

Description:

     Filter the wordcloud data by the selected filters.

Usage:

     filter_wordcloud_data(forum_words, forum_elements, activity_level, gender,
       registration_status, category)
     
Arguments:

forum_words: The forum words dataframe passed in from the wrangling
          script.

forum_elements: The forum elements dataframe.

activity_level: The activity level of the students.

  gender: The gender of the students.

registration_status: The registration status of the students.

category: The forum category.

Value:

     'filtered_wordcloud_data' The filtered forum words dataframe.

Examples:

     filter_wordcloud_data(wrangled_forum_words, forum_elements, "30_min_to_5_hr", "female", "All", "General")
     

9.2.8 gather_post_types

9.2.8.1 Main Documentation

Gather the post types into a single column for easy plotting.

Description:

     Gather the post types into a single column for easy plotting.

Usage:

     gather_post_types(forum_data, grouping_var)
     
Arguments:

forum_data: The forum data for the main barplot.

grouping_var: grouping_var One of 'discussion_category' or
          'display_name', depending on whether a category has been
          selected.

Value:

     'gathered' A dataframe with the post types gathered into a single
     column.

Examples:

     gather_post_types(forum_data, grouping_var = "discussion_category")
     

9.2.9 get_author_count

9.2.9.1 Main Documentation

Get the number of authors for which the selected filter settings apply.

Description:

     Get the number of authors for which the selected filter settings
     apply.

Usage:

     get_author_count(forum_posts, forum_elements, activity_level, gender,
       registration_status, category)
     
Arguments:

forum_posts: The forum posts dataframe that was passed in from the
          wrangling script.

forum_elements: The forum elements dataframe.

activity_level: The activity level of the students.

  gender: The gender of the students.

registration_status: The registration status of the students.

category: The forum category.

Value:

     'author_count' A string showing the number of authors.

Examples:

     get_author_count(wrangled_forum_posts, forum_elements, "All", "male", "verified", "All")
     

9.2.10 get_forum_threads

9.2.10.1 Main Documentation

Get the forum threads for the authors who match the filter settings.

Description:

     Get the forum threads for the authors who match the filter
     settings.

Usage:

     get_forum_threads(forum_posts, forum_elements, activity_level, gender,
       registration_status, category, selected_subcategory)
     
Arguments:

forum_posts: The forum posts dataframe that was passed in from the
          wrangling script.

forum_elements: The forum elements dataframe.

activity_level: The activity level of the students.

  gender: The gender of the students.

registration_status: The registration status of the students.

category: The selected forum category.

selected_subcategory: The selected forum subcategory.

Value:

     'forum_threads' The forum threads that were authored by students
     for which the filter settings apply.

Examples:

     get_forum_threads(forum_posts = wrangled_forum_posts, forum_elements, "over_5_hr", "female", "audit", "All", "All")
     

9.2.11 get_label_lengths

9.2.11.1 Main Documentation

Get the lengths of the labels on the main barplot (either the
categories or the subcategories).

Description:

     Get the lengths of the labels on the main barplot (either the
     categories or the subcategories).

Usage:

     get_label_lengths(forum_data, category)
     
Arguments:

forum_data: The forum data for the main barplot.

category: The selected category.

Value:

     'label_lengths' A list with the lengths (in characters) of each
     label on the main plot.

Examples:

     get_label_lengths(forum_data, "Technical Questions")
     

9.2.12 get_post_types

9.2.12.1 Main Documentation

Get the post types.

Description:

     Get the post types.

Usage:

     get_post_types(forum)
     
Arguments:

   forum: A forum dataframe.

Value:

     The same dataframe with a new column for post_type.

Examples:

     get_post_types(forum)
     

9.2.13 get_subcategory_options

9.2.13.1 Main Documentation

Get the options for the subcategory options, given the selected
category.

Description:

     Get the options for the subcategory options, given the selected
     category.

Usage:

     get_subcategory_options(category, filtered_forum_elements)
     
Arguments:

category: The selected category.

filtered_forum_elements: The forum elements dataframe, filtered by the
          selected category.

Value:

     'subcategory_options' A list of options for the user to select
     from.

Examples:

     get_subcategory_options("Part 1", filtered_forum_elements)
     

9.2.14 get_target_word_counts

9.2.14.1 Main Documentation

Get the top words for each subcategory.

Description:

     Get the top words for each subcategory.

Usage:

     get_target_word_counts(input_forum)
     
Arguments:

input_forum: The input dataframe containing a row for each word in the
          forum.

Value:

     'word_counts' A dataframe containing the counts for each word in
     each subcategory.

Examples:

     get_target_word_counts(wrangled_forum_words)
     

9.2.15 get_wordcloud_data

9.2.15.1 Main Documentation

Get the counts of each word in the selected subcategories.

Description:

     Get the counts of each word in the selected subcategories.

Usage:

     get_wordcloud_data(filtered_wordcloud_data, filtered_forum_elements, category,
       selected_subcategory)
     
Arguments:

filtered_wordcloud_data: The filtered forum words dataframe.

filtered_forum_elements: The filtered forum elements dataframe.

category: The selected category.

selected_subcategory: The selected subcategory.

Value:

     'wordcloud_data' A dataframe with the counts of each word in the
     selected subcategory(ies).

Examples:

     get_wordcloud_data(filtered_wordcloud_data, filtered_forum_elements, "Part 1", "Part 1 Lecture 1 Discussion")
     

9.2.16 make_forum_barplot

9.2.16.1 Main Documentation

Make the main barplot for displaying the forum data.

Description:

     Make the main barplot for displaying the forum data.

Usage:

     make_forum_barplot(forum_data, xvar_string, plot_variable, fill_value,
       axis_limit, category, ylabel, breakdown)
     
Arguments:

forum_data: The forum data for the main barplot.

xvar_string: A string that matches the function to call for the x value
          of aes_string().

plot_variable: One of (default) 'posts', 'authors', or 'views'.

fill_value: A hex value representing the color for the bar fill.

axis_limit: The maximum axis limit for the horizontal axis in the main
          barplot.

category: The selected category.

  ylabel: The label of the y-axis in the main barplot.

breakdown: One of 'TRUE' or 'FALSE'; determines whether the post types
          breakdown is shown.

Value:

     'forum_barplot' A ggplot2 object to be rendered as the main forum
     barplot.

Examples:

     make_forum_barplot(forum_data, xvar_string = "fct_reorder(discussion_category, course_order, .desc = TRUE)", plot_variable = "authors", fill_value = "red", axis_limit = 100, category = "All", ylabel = "Category", breakdown = FALSE)
     

9.2.17 make_forum_breakdown_barplot

9.2.17.1 Main Documentation

Make the main forum barplot with the post types breakdown.

Description:

     Make the main forum barplot with the post types breakdown.

Usage:

     make_forum_breakdown_barplot(gathered, xvar_string, grouping_var, axis_limit,
       xlabel)
     
Arguments:

xvar_string: A string that matches the function to call for the x value
          of aes_string().

grouping_var: grouping_var One of 'discussion_category' or
          'display_name', depending on whether a category has been
          selected.

axis_limit: The maximum axis limit for the horizontal axis in the main
          barplot.

  xlabel: The label of the x-axis in the main barplot.

forum_data: The forum data for the main barplot.

Value:

     'forum_breakdown_barplot' A ggplot2 object to be rendered as the
     main forum barplot.

Examples:

     make_forum_breakdown_barplot(forum_data = forum_data, xvar_string = "fct_reorder(discussion_category, course_order, .desc = TRUE)", axis_limit = 100, grouping_var = "discussion_category", xlabel = "Category")
     

9.2.18 make_wordcloud

9.2.18.1 Main Documentation

Make the wordcloud.

Description:

     Make the wordcloud.

Usage:

     make_wordcloud(wordcloud_data, max_words = 20, scale = c(3.5, 1))
     
Arguments:

wordcloud_data: A dataframe showing the counts of the top words in the
          selected subcategory.

max_words: The maximum number of words to show in the wordcloud.
          Default is 20.

   scale: A list giving the range of sizes to for the display of words
          in the wordcloud. Default is c(3.5,1).

Value:

     A wordcloud object.

Examples:

     make_wordcloud(wordcloud_data, max_words = 30, scale = c(4,1.5))
     

9.2.19 set_axis_limit

9.2.19.1 Main Documentation

Set the horizontal axis limit of the main barplot.

Description:

     Set the horizontal axis limit of the main barplot.

Usage:

     set_axis_limit(forum_data, plot_variable, label_lengths,
       min_axis_length = 0.1, percent_addition_per_char = 0.023)
     
Arguments:

forum_data: The forum data for the main barplot.

plot_variable: One of (default) 'posts', 'authors', or 'views'.

label_lengths: A list containing the lengths (in characters) of each
          label on the barplot.

min_axis_length: The axis length to set if all the values are set to
          zero (i.e. all students have been filtered out). Default is
          0.1 so that the axis is minimally affected when values are
          small.

percent_addition_per_char: The percentage by which to expand the axis
          per character in the label of the longest bar. Default is
          0.023 because that tends to look good.

Details:

     Usually, the variance in bar lengths is greater than the variance
     in label lengths. If this is not the case, it is possible that the
     axis limit will need to be expanded further. For example, the
     second-longest bar may have a label that is twice as long as the
     label of the longest bar. In the future, it will be desirable to
     account for these cases.

Value:

     'axis_limit' The maximum axis limit for the horizontal axis in the
     main barplot.

Examples:

     set_axis_limit(forum_data, "views", c(15,12,14,7))
     

9.2.20 set_breakdown

9.2.20.1 Main Documentation

Determines whether the plot types breakdown will be shown.

Description:

     Determines whether the plot types breakdown will be shown.

Usage:

     set_breakdown(plot_variable, breakdown)
     
Arguments:

plot_variable: One of (default) 'posts', 'authors', or 'views'.

breakdown: One of 'TRUE' or (default) 'FALSE'.

Details:

     This option only comes into play if the plot variable is 'posts'.

Value:

     'TRUE' or 'FALSE'

Examples:

     set_breakdown(plot_variable = "posts", breakdown = FALSE)
     

9.2.21 set_forum_plot_title

9.2.21.1 Main Documentation

Set the title of the main barplot, according to the relevant variable
and category.

Description:

     Set the title of the main barplot, according to the relevant
     variable and category.

Usage:

     set_forum_plot_title(plot_variable, category)
     
Arguments:

plot_variable: One of (default) 'posts', 'authors', or 'views'.

Value:

     'forum_plot_title' A string for the plot title.

Examples:

     set_forum_plot_title("views", "Part 1")
     

9.2.22 set_forum_plot_ylabel

9.2.22.1 Main Documentation

Set the label of the y-axis in the main barplot.

Description:

     Set the label of the y-axis in the main barplot.

Usage:

     set_forum_plot_ylabel(plot_variable)
     
Arguments:

plot_variable: One of (default) 'posts', 'authors', or 'views'.

Value:

     'forum_plot_ylabe' The label of the y-axis in the main barplot.

Examples:

     set_forum_plot_ylabel("authors")
     

9.2.23 set_forum_threads_title

9.2.23.1 Main Documentation

Set the title of the forum threads table.

Description:

     Set the title of the forum threads table.

Usage:

     set_forum_threads_title(category, selected_subcategory)
     
Arguments:

category: The selected category.

selected_subcategory: The selected subcategory.

Value:

     'forum_threads_title' A string for the title of the forum threads
     table.

Examples:

     set_forum_threads_title("Part 3", "All")
     

9.2.24 set_wordcloud_title

9.2.24.1 Main Documentation

Set the title of the wordcloud.

Description:

     Set the title of the wordcloud.

Usage:

     set_wordcloud_title(category, selected_subcategory)
     
Arguments:

category: The selected category.

selected_subcategory: The selected subcategory.

Value:

     'wordcloud_title' A string for the wordcloud title.

Examples:

     set_wordcloud_title("Part 3", "All")
     

9.2.25 specify_forum_data_selection

9.2.25.1 Main Documentation

Specify which subcategory has been selected.

Description:

     Specify which subcategory has been selected.

Usage:

     specify_forum_data_selection(updated_forum_data, category, selected_subcategory)
     
Arguments:

updated_forum_data: The dataframe containing the counts for each
          (sub)category.

category: The selected category.

selected_subcategory: The selected subcategory.

Value:

     'forum_w_selection' The same dataframe with a new column,
     'selected'.

Examples:

     specify_forum_data_selection(updated_forum_data, "Part 1", "Part 1 Video Discussion")
     

9.2.26 update_forum_data

9.2.26.1 Main Documentation

Update the post, view, and author counts for the selected filters.

Description:

     Update the post, view, and author counts for the selected filters.

Usage:

     update_forum_data(forum_posts, forum_views, forum_elements, activity_level,
       gender, registration_status, category)
     
Arguments:

forum_posts: The forum posts dataframe passed in from the wrangling
          script.

forum_views: The forum views dataframe passed in from the wrangling
          script.

forum_elements: The forum elements dataframe passed in from the
          wrangling script.

activity_level: The activity level of the students.

  gender: The gender of the students.

registration_status: The registration status of the students.

category: The forum category.

Value:

     'filtered_forum_data' A dataframe with one row per subcategory (or
     category), and counts for each variable.

Examples:

     update_forum_data(wrangled_forum_posts, wrangled_forum_views, filtered_forum_elements(), "over_5_hr", "other", "audit", "All")