revisit 0.0.25

No project description provided

revisit

Installation

pip install revisit

or with uv:

uv add revisit

Usage

The reVISit python package wraps the standard items of the reVISit configuration file with readable, easy-to-use functions. We expose a factory function for each top-level item in the reVISit configuration: studyMetadata, uiConfig, components, sequence, and studyMetadata. Currently, we do not expose a baseComponents function. Instead, base components are still well-defined components and can be passed during the creation of another component. The final configuration will not include base components but will have the expected inherited output.

Each factory function takes in the same parameters as the reVISit configuration file. For example, the studyMetadata function requires the author, organizations, title, version, and description parameters. Robust error output will help you, the user, understand what is required in each function. For the sake of brevity, we do not list every possible parameter since these are already defined in the current study configuration. Instead, we will show additional required/optional parameters as well as additional methods and other exposed functions.

Functions

component(component_name__: str, base__: Optional[component], **kwargs: dict) -> Component

Description:

Instantiates a Component class with the given input parameters.

Parameters:

Parameter	Type	Description	Default Value
component_name__	str	Names the component for use in the final configuration file.	None
base__	Optional[component]	When a base component is passed, all properties of the base are inherited by the component. Any other specified property during input will override base properties.	None
**kwargs	dict	The component function requires any property that the component already requires, such as "type". Refer to the configuration documentation for required properties.	None

Returns:

• Component: Returns an instantiation of the Component class.

Raises:

• RevisitError: If the required properties are not specified, and exception will be raised.

Example:

import revisit as rvt

# Initializing a markdown component with an empty response list.
my_component = rvt.component(
    component_name__='my-component',
    response=[],
    type='markdown',
    path='./assets/my-markdown-file.md'
)

# Instantiating a component with the base as "my_component".
my_other_component = rvt.component(
    component_name__='my-other-component',
    base__=my_component,
    path='./assets/my-other-markdown-file.md'
)

response(**kwargs: dict) -> Response

Description:

Instantiates a Response class with the given input parameters.

Parameters:

Parameter	Type	Description	Default Value
**kwargs	dict	The component function requires any property that the component already requires, such as "type". Refer to the configuration documentation for required properties.	None

Returns:

• Response: Returns an instantiation of the Response class.

Raises:

• RevisitError: If the required properties are not specified, and exception will be raised.

Example:

import revisit as rvt

# Initializing a matrix radio response
my_response = rvt.response(
    type='matrix-radio',
    answerOptions='likely5',
    questionOptions=['Question 1', 'Question 2', 'Question 3'],
    required=True,
    location='sidebar'
)

Classes

Component

Description:
A brief summary of the class's purpose and functionality.

Attributes:

Attribute	Type	Description	Default Value
component_name__	type	Description of attribute 1.	default
base__	type	Description of attribute 2.	None

Methods:

responses(responses: List[Response]) -> self

Description:
Sets responses for the component

Parameters:

Parameter	Type	Description	Default Value
responses	List[Response]	Valid list of responses.	None

Returns:

• self: Returns self for method chaining.

Raises:

• RevisitError: If the list is not a valid list of responses, raises and exception.

Example:

my_response=rvt.response(
    id='my_response',
    type='dropdown',
    options=['Option 1', 'Option 2']
)

my_component = rvt.component(
    component_name__='my_component',
    type='markdown',
    path='assets/my-markdown-file.md'
).responses([
    my_response
])

get_response(id: str) -> Response | None

Description: Returns the response of the component with the given ID. If the Response does not exist, returns None.

Parameters:

Parameter	Type	Description	Default Value
id	str	ID of Response	None

Returns:

• Response: The response with the given ID.

Examples:

the_response = my_component.get_response(id='the_response')

if the_response is not None:
    print(the_response)

edit_response(id: str, **kwargs: dict) -> self

Description: Edits the Response in the Component with the given ID. This is done by creating a new copy of the existing Response.

Parameters:

Parameter	Type	Description	Default Value
id	str	ID of Response	None

Returns:

• self: Returns self for method chaining.

Examples:

test_response = rvt.response(
    id='test_response',
    type='shortText',
    prompt='Original Prompt:',
    required=True
)

component_one = rvt.component(
    component_name__='component_one',
    type='questionnaire',
    response=[test_response]
)

component_two = rvt.component(
    component_name__='component_two',
    type='questionnaire',
    response=[test_response]
).edit_response(id='test_response', prompt='New Prompt', required=False)

print(component_one)
'''
Expected Output:
{
    "response": [
        {
            "id": "test_response",
            "prompt": "Original Prompt:",
            "required": true,
            "type": "shortText"
        }
    ],
    "type": "questionnaire"
}
'''
print(component_two)
'''
{
    "response": [
        {
            "id": "test_response",
            "prompt": "New Prompt",
            "required": false,
            "type": "shortText"
        }
    ],
    "type": "questionnaire"
}
'''

clone(component_name__) -> Component

Description: Clones the component with the given new component name.

Parameters:

Parameter	Type	Description	Default Value
component_name__	str	New component name to assign to cloned component.	None

Returns:

• self: Returns self for method chaining.

Examples:

test_response = rvt.response(
    id='test_response',
    type='shortText',
    prompt='Original Prompt:',
    required=True
)

component_one = rvt.component(
    component_name__='component_one',
    type='questionnaire',
    response=[test_response]
)

component_two = component_one.clone(component_name__='component_two').edit_response(id='test_response', prompt='New Prompt', required=False)

print(component_one)
'''
Expected Output:
{
    "response": [
        {
            "id": "test_response",
            "prompt": "Original Prompt:",
            "required": true,
            "type": "shortText"
        }
    ],
    "type": "questionnaire"
}
'''
print(component_two)
'''
{
    "response": [
        {
            "id": "test_response",
            "prompt": "New Prompt",
            "required": false,
            "type": "shortText"
        }
    ],
    "type": "questionnaire"
}
'''

Response

Description:
A brief summary of the class's purpose and functionality.

Attributes:

Attribute	Type	Description	Default Value
component_name__	type	Description of attribute 1.	default
base__	type	Description of attribute 2.	None

Methods:

set(**kwargs: dict) -> self

Description:

Sets the values of the response to the input dictionary. The type cannot be changed and would require creating a new response

Parameters:

Parameter	Type	Description	Default Value
**kwargs	dict	Dictionary containing valid values for the current response type.	None

Returns:

• self: Returns self for method chaining.

Raises:

• RevisitError: If the user attempts to change the type attribute of the response, an exception will be raised. Any invalid inputs for the instantiated response type will also raise an exception.

Examples:

response_one = rvt.response(
    id='r-1',
    type='shortText',
    required=False,
    location='belowStimulus',
    prompt=''
)

response_one.set(prompt='New Prompt')
print(response_one)
'''
Expected Output
{
    "id": "r-1",
    "location": "belowStimulus",
    "prompt": "New Prompt",
    "required": false,
    "type": "shortText"
}
'''

response_one.set(type='longText')
# Raises Exception: 'Cannot change type from shortText to longText'

response_one.set(options=[1,2,3])

clone() -> Response

Description: Clones the response.

Parameters:
No parameters

Returns:

• self: Returns self for method chaining.

Examples:

import random
question_1 = rvt.response(
    id='q-1',
    type='shortText',
    prompt='What is 4 - 2?',
    required=True,
    location='belowStimulus'
)

# Initialize a list with first question
final_responses = [question_1]

# Randomly generate different arithmetic questions by cloning original question.
for i in range(2, 21):
    curr_response = question_1.clone().set(
        id=f'q-{i}',
        prompt=f'What is {random.randint(1, 10)} - {random.randint(1, 10)}'
    )
    final_responses.append(curr_response)

component_one = rvt.component(
    component_name__='component_one',
    type='questionnaire',
    response=final_responses
)

print(component_one)
'''
Expected Output:
{
    "response": [
        {
            "id": "q-1",
            "location": "belowStimulus",
            "prompt": "What is 4 - 2?",
            "required": true,
            "type": "shortText"
        },
        {
            "id": "q-2",
            "location": "belowStimulus",
            "prompt": "What is 10 - 4",
            "required": true,
            "type": "shortText"
        },

        ...

        {
            "id": "q-20",
            "location": "belowStimulus",
            "prompt": "What is 2 - 5",
            "required": true,
            "type": "shortText"
        }
    ],
    "type": "questionnaire"
}
'''

Development

We recommend using uv for development. It will automatically manage virtual environments and dependencies for you.

uv run jupyter lab example.ipynb

Alternatively, create and manage your own virtual environment:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
jupyter lab example.ipynb

The widget front-end code bundles it's JavaScript dependencies. After setting up Python, make sure to install these dependencies locally:

yarn install

While developing, you can run the following in a separate terminal to automatically rebuild JavaScript as you make changes:

yarn run dev

Open example.ipynb in JupyterLab, VS Code, or your favorite editor to start developing. Changes made in js/ will be reflected in the notebook.

CODE GEN

datamodel-codegen --input src/revisit/StudyConfigSchema.json --output src/revisit/models.py  --custom-template-dir custom_templates --output-model-type pydantic_v2.BaseModel --additional-imports "typing.TypedDict, warnings" --input-file-type jsonschema --special-field-name-prefix we_are_going_to_replace_this && sed -i '' 's/we_are_going_to_replace_this_//g'  src/revisit/models.py

TESTS

cd revisit-py
python -m unittest tests.test_module_one