hifis_surveyval.models package¶
Subpackages¶
Submodules¶
hifis_surveyval.models.answer_option module¶
This module contains a class to represent survey answers.
- class hifis_surveyval.models.answer_option.AnswerOption(parent_id: str, option_id: str, text: hifis_surveyval.models.translated.Translated, label: str)[source]¶
Bases:
hifis_surveyval.models.mixins.yaml_constructable.YamlConstructable
,hifis_surveyval.models.mixins.identifiable.Identifiable
The AnswerOption models allowed answers for a specific Question.
- __init__(parent_id: str, option_id: str, text: hifis_surveyval.models.translated.Translated, label: str) None [source]¶
Create an answer option from the metadata.
- Args:
- parent_id:
The full ID of the question this answer option belongs to.
- option_id (str):
A unique string identifying the answer.
- text:
A Translated object containing the texts that represent the answer option across various languages.
- label:
A short string used to represent the answer option in plotting.
- property label: str¶
Get the label of this answer option.
- Returns:
A label serving as a short description of this option.
- schema: schema.Schema = Schema({'id': <class 'str'>, 'label': <class 'str'>, 'text': <class 'dict'>})¶
The default schema of a YamlConstructable validates everything which is formatted like a YamlDictionary
- property text: hifis_surveyval.models.translated.Translated¶
Obtain the full text that was associated with this answer.
- Returns:
An object containing all the translations for text associated with this answer option.
- token_ID = 'id'¶
- token_LABEL = 'label'¶
- token_TEXT = 'text'¶
hifis_surveyval.models.answer_types module¶
This contains information about the data types supported by answers.
hifis_surveyval.models.question module¶
This module contains classes to represent survey questions.
These can be constructed from YAML through the YamlConstructable abstract class.
- class hifis_surveyval.models.question.Question(parent_id: str, question_id: str, text: hifis_surveyval.models.translated.Translated, label: str, answer_type: type, mandatory: bool, answer_options: List[hifis_surveyval.models.answer_option.AnswerOption], settings: hifis_surveyval.core.settings.Settings)[source]¶
Bases:
hifis_surveyval.models.mixins.yaml_constructable.YamlConstructable
,hifis_surveyval.models.mixins.identifiable.Identifiable
Questions model concrete questions that could be answered in the survey.
They can be constructed from YAML metadata via from_yaml_dictionary(). For this to be successful the YAML data has to adhere to Question.schema which describes the required fields and their data types. Answers then have to be added separately via add_answer().
- __init__(parent_id: str, question_id: str, text: hifis_surveyval.models.translated.Translated, label: str, answer_type: type, mandatory: bool, answer_options: List[hifis_surveyval.models.answer_option.AnswerOption], settings: hifis_surveyval.core.settings.Settings)[source]¶
Initialize a question object with metadata.
The answers have to be added separately via add_answer().
- Args:
- parent_id:
The ID of the question collection this question is embedded in.
- question_id:
An identifier assigned to the question. Must be unique within the question collection.
- text:
A Translated object representing the text that describes the question.
- label:
A short label that can be used in plotting to represent the question collection.
- answer_type:
The data type of the answers. Must be one of the supported data types. See also hifis_surveyval.models.answer_types.VALID_ANSWER_TYPES
- mandatory:
Whether there is an answer to this question expected from each participant in oder to consider the participant’s answer data complete.
- answer_options:
An optional list of predefined answers. If there are none given, the question can have any answer, otherwise the answer must be the short ID of the selected answer option.
- settings:
An object reflecting the application settings.
- add_answer(participant_id: str, value: str)[source]¶
Store a given answer to this question.
The answer value will be casted to the expected answer type.
- Args:
- participant_id:
The ID of the participant who gave the answer
- value:
The text-version of the answer as stored in the CSV. If the question is mandatory, the value must not be empty. If answer options are defined the value must match the short id of the selected answer option.
- Raises:
- ValueError:
- if the question was marked as mandatory but the given value was
an empty string
- KeyError:
If answer options were present, but none of the answer options had an ID that matched the given value
- property answers: Dict[str, Optional[object]]¶
Obtain the given answers as read from the survey data.
The answers are given as a mapping: participant ID -> participant answer
The participant ID will be a string, while the answers may be assumed to be of the answer_type of the Question. If the Question is not mandatory, answers may also be None.
- Returns:
The mapping from participant ID to the participant’s answer for this question.
- as_series() <MagicMock id=’140236676051152’> [source]¶
Obtain the answers to this question as a pandas.Series.
The series’ index are the participant IDs, while data for the indices are the respective answers.
The series will be named with the question’s full ID.
- Returns:
A pandas.Series representing the answers for each participant
- remove_answers(participant_ids: Set[str]) None [source]¶
Remove the answers by the specified participants.
- Args:
- participant_ids:
The IDs of the participants whose answers are to be removed. Invalid IDs are ignored.
- schema: schema.Schema = Schema({'id': <class 'str'>, 'label': <class 'str'>, 'text': <class 'dict'>, 'datatype': <function Question.<lambda>>, 'mandatory': <class 'bool'>, Optional('answers'): <class 'list'>, Optional(<class 'str'>): <class 'object'>})¶
The default schema of a YamlConstructable validates everything which is formatted like a YamlDictionary
- token_ANSWER_OPTIONS = 'answers'¶
- token_DATA_TYPE = 'datatype'¶
- token_ID = 'id'¶
- token_LABEL = 'label'¶
- token_MANDATORY = 'mandatory'¶
- token_TEXT = 'text'¶
hifis_surveyval.models.question_collection module¶
This module contains classes to represent groups of survey questions.
These can be constructed from YAML through the YamlConstructable abstract class.
- class hifis_surveyval.models.question_collection.QuestionCollection(collection_id: str, text: hifis_surveyval.models.translated.Translated, label: str, questions: List[hifis_surveyval.models.question.Question])[source]¶
Bases:
hifis_surveyval.models.mixins.yaml_constructable.YamlConstructable
,hifis_surveyval.models.mixins.identifiable.Identifiable
QuestionCollections group a set of questions into a common context.
This kind of question has no answers by itself. These are to be found in the according sub-questions.
- __init__(collection_id: str, text: hifis_surveyval.models.translated.Translated, label: str, questions: List[hifis_surveyval.models.question.Question]) None [source]¶
Initialize an empty question collection.
It is recommended to refer to from_yaml_dictionary() for constructing instances when parsing metadata.
- Args:
- collection_id:
The unique ID that is to be assigned to the collection.
- text:
A Translated object representing the text that describes the question collection.
- label:
A short label that can be used in plotting to represent the question collection.
- questions:
A list of questions that are contained within the question collection.
- as_data_frame(exclude_labels: Optional[Union[str, List[str]]] = None) <MagicMock id=’140236676163184’> [source]¶
Gather the answers given to each question as a data frame.
- Args:
- exclude_labels:
A short label or a list of short labels for questions that are to be excluded from the data frame.
- Returns:
A pandas data frame with participants in the rows and the questions of this collection in the columns. The fields in the data frame then contain the answer to a question for a given participant.
- question_for_id(question_short_id: str) hifis_surveyval.models.question.Question [source]¶
Obtain a question from the collection for a given short ID.
- Args:
- question_short_id:
The short id used within the collection for this question.
- Returns:
The question for the given ID.
- Raises:
KeyError - if no question with the given ID did exist.
- property questions: List[hifis_surveyval.models.question.Question]¶
List all questions in this collection.
- Returns:
A list with all question objects associated with this collection
- remove_answers(participant_ids: Set[str]) None [source]¶
Remove the answers by the specified participants.
- Args:
- participant_ids:
The IDs of the participants whose answers are to be removed. Invalid IDs are ignored.
- schema: schema.Schema = Schema({'id': <class 'str'>, 'label': <class 'str'>, 'text': <class 'dict'>, Optional('questions'): <class 'list'>, Optional(<class 'str'>): <class 'object'>})¶
The default schema of a YamlConstructable validates everything which is formatted like a YamlDictionary
- token_ID = 'id'¶
- token_LABEL = 'label'¶
- token_QUESTIONS = 'questions'¶
- token_TEXT = 'text'¶
hifis_surveyval.models.translated module¶
Models survey elements that can be represented in multiple languages.
- class hifis_surveyval.models.translated.Translated(translations: Dict[str, str])[source]¶
Bases:
hifis_surveyval.models.mixins.yaml_constructable.YamlConstructable
A wrapper around text instances with multiple translations.
Languages are identified by their ISO 693-1 two-letter codes. Optionally an uppercase region identifier may be appended as well. Region identifiers consist of a two or three letter code and must be separated by a dash from the language identifier.
Examples for valid identifiers are de, en-US but not frFR.
- __init__(translations: Dict[str, str])[source]¶
Create a new instance of translated text.
- Args:
- translations:
A mapping from the language code to the translation in the respective language. The dictionary must not be empty. Keys are expected to be two-letter codes with an optional region code, and values must neither be None nor be empty.
- available_languages() List[str] [source]¶
Get all languages for which translations exist.
- Returns:
A list of language codes
- get_translation(language_code: str) str [source]¶
Get the translation for a specific language.
If the passed in language code has a region specifier, and no translation for this region is given, a translation with only the language code will be looked up as a fallback.
- Args:
- language_code:
The ISO 693-1 two letter code for the language the text is requested for. Optionally a dash followed by an uppercase two or three letter region code may be appended as well.
- Returns:
The text in the requested language or None if no translation for this language exists.
- Raises:
- KeyError:
If no translation for the requested language (with or without region code) can be found.
- schema: schema.Schema = Schema({And(<class 'str'>, Regex('^[a-z]{2}(-[A-Z]{2,3})?$')): And(<class 'str'>, <function Translated.<lambda>>)})¶
The validation schema used for translation dictionaries. * The dictionary may not be empty * The key must exist, be a string and consist of two lower-case letters * The value must be a string and must not be empty
Module contents¶
Provides data models used in this program.