dsci524_group13_quizit

Submodules

• dsci524_group13_quizit.load_questions
• dsci524_group13_quizit.question_type
• dsci524_group13_quizit.quizit
• dsci524_group13_quizit.utils

Attributes

__version__

Classes

Quizit	A class to manage and conduct custom quizzes with multiple-choice and short-answer questions.
QuestionType	A class for the different types of questions. Inherits from the Enum Class

Package Contents

dsci524_group13_quizit.__version__

class dsci524_group13_quizit.Quizit

A class to manage and conduct custom quizzes with multiple-choice and short-answer questions.

This class allows users to load multiple-choice and short-answer question sets, and take multiple-choice or short-answer quizzes. The quiz can save the user’s score, and optionally log the answered questions and their correctness.

mcq = None

shrtq = None

_process_save_questions(questions: pandas.DataFrame, question_type: dsci524_group13_quizit.load_questions.QuestionType, delimiter: string)

Internal Helper Function Processes the questions DataFrame by splitting the ‘options’ and ‘answers’ columns based on the provided delimiter.

Parameters:

• questions ((pd.DataFrame)) – DataFrame containing the questions to be processed.

• question_type ((QuestionType)) – Enum indicating the type of questions (e.g., MULTIPLE_CHOICE).

• delimiter ((str)) – The delimiter used to split the ‘options’ and ‘answers’ columns.

Returns:

questions – The processed DataFrame with ‘options’ and ‘answers’ columns split based on the delimiter.

Return type:

(pd.DataFrame)

load_questions(questions: pandas.DataFrame = None, input_file: string = None, question_type: dsci524_group13_quizit.load_questions.QuestionType = None, has_header: bool = True, delimiter: string = None) → pandas.DataFrame

Wrapper function to load in questions from a DataFrame or a file (CSV).

Parameters:

• questions (pd.DataFrame, optional) – The user questions as a pandas DataFrame. Default is None.

• input_file (str, optional) – The path to the CSV file containing the questions. Default is None.

• question_type (QuestionType, optional) – The type of questions, either ‘multiple choice’ or ‘short answer’. Default is None.

• has_header (bool, optional) – Indicates if the CSV file or DataFrame contains a header. Default is True.

• delimiter (bool, optional) – The delimiter of the answers and options for the ‘multiple choice’ questions. Default is None.

Returns:

A pandas DataFrame containing the questions.

Return type:

pd.DataFrame

Raises:

ValueError – If both questions and input_file are provided or neither is provided.

Examples

>>> quiz = Quizit()
>>> quiz.load_questions(input_file="questions.csv", question_type=QuestionType.MULTIPLE_CHOICE)
>>> quiz.load_questions(questions=pd.DataFrame(data), question_type=QuestionType.SHORT_ANSWER)

Notes

The input file needs to be formatted as follows:

For multiple choice questions:

Question | Answers       | Correct Answers | Explanation
-------- | ------------- | --------------- | -----------
mcq      | [A, B, C]     | [B, C]          | explanation

For short answer questions:

Question                                    | Answer | Explanation
--------------------------------------------| ------ | -----------
What continent has the largest population?  | Asia   | explanation

take_multiple_choice(n, save_questions=False, save_score=False, file_path=None)

Conducts a multiple-choice quiz and provides optional result tracking.

This method randomly selects n questions from the question bank and prompts the user to answer one question at a time. At the end of the quiz, the function will display the total score and the time taken.

Optional logging and score saving:

• If save_score is True, the final score and time spent are saved to a txt file.

• If save_questions is set to “all”, “incorrect”, or “correct”, corresponding questions, along with multiple choice options, user answers, correct answers, and explanations are saved to a txt file.

Notes:

If file_path is not specified, all files will be saved to “results” folder in your current working directory.

Parameters:

• n (int) – The number of questions to randomly select from the question bank. If n exceeds the total number of questions in the bank, all available questions are used.

• save_questions (str or bool, optional (default=False)) –

  Specifies which questions to save to a log file

  • ”all”: Saves correct and incorrect questions in separate files.

  • ”incorrect”: Saves only the incorrect questions.

  • ”correct”: Saves only the correct questions.

  • False: No questions are saved.

• save_score (bool, optional (default=False)) – If True, save the final quiz score and the time taken to a file.

• file_path (str, optional (default=None)) – Allows users to specify the location where the quiz score and question log are stored.

Returns:

results –

An instance of QuizResult class, which contains:

• time_used: The time (in seconds) taken to complete the quiz.

• score: The final quiz percentage score.

• question_summary: A DataFrame with details about all answered questions, including user responses, correct answers, and scores.

• question_type: A string specifying the type of questions (“mcq” or “shrtq”)

Return type:

QuizResult

Raises:

• ValueError –

  • If no multiple-choice questions are loaded in the Quizit class instance (self.mcq == None).

  • If there are no valid multiple-choice questions available.

• TypeError –

  • If the save_questions parameter is not one of: ‘all’, ‘correct’, ‘incorrect’, or False.

  • If the save_score parameter is not a boolean (True or False).

  • If the n parameter is not an integer.

• Scoring System –

• -------- –

• - Each question has correct and incorrect options. –

• - Users will earn points for selecting correct answers and for not selecting incorrect ones. –

• - The score is calculated as the sum of correctly chosen answers and correctly avoided wrong answers, divided by the total number of options. –

• - If no answer is selected or user input is invalid, the score is 0. –

Example

>>> results = quiz.take_multiple_choice(10, save_questions="incorrect", save_score=True, file_path=None)

take_short_answer(n, save_questions=False, save_score=False, file_path='')

Conducts a short-answer quiz and evaluates the user’s performance.

This method displays a series of n short-answer questions, prompts the user for their responses, and compares the responses with the correct answers. Based on the correctness of the answers, the function calculates the user’s score. It also provides an option to save the answers to log files and save the final score.

Parameters:

nint

The number of short-answer questions to present in the quiz. If n exceeds the number of available questions, it will present all available questions.

save_questionsbool, optional (default=False)

If True, saves the questions that were answered correctly and incorrectly to separate files. The correct answers are saved to “correct_answers.txt” and the incorrect answers are saved to “incorrect_answers.txt”.

save_scorebool, optional (default=False)

If True, saves the final quiz score and the time taken to a file (“score.txt”).

file_pathstr, optional (default=””)

The directory path where the quiz score and question logs will be saved. If not provided, it defaults to the current directory, and folders will be created as necessary.

returns:

A dictionary containing: - score (float): The final score percentage (0-100%). - correct_answers (list): A list of questions that were answered correctly. - incorrect_answers (list): A list of questions that were answered incorrectly.

rtype:

dict

raises ValueError:

• If there are no short-answer questions loaded in self.shrtq.

• If the number of questions n exceeds the number of available questions in the quiz bank.

raises TypeError:

• If any question format is not as expected (e.g., missing required fields).

raises Example::

raises ——–:

raises result = quiz.take_short_answer(3, save_questions=True, save_score=True, file_path=”results/”):

class dsci524_group13_quizit.QuestionType(*args, **kwds)

Bases: enum.Enum

A class for the different types of questions. Inherits from the Enum Class

MULTIPLE_CHOICE(str)

Type:

Represents a multiple choice question type.

SHORT_ANSWER(str)

Type:

Represents a short answer question type.

MULTIPLE_CHOICE = 'multiple choice'

SHORT_ANSWER = 'short answer'