revisit 0.0.26__tar.gz → 0.0.28__tar.gz

{revisit-0.0.26 → revisit-0.0.28}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.4
 Name: revisit
-Version: 0.0.26
+Version: 0.0.28
 Requires-Dist: anywidget
 Requires-Dist: pandas
 Requires-Dist: pydantic>=2.10.5
+Requires-Dist: revisit-server>=0.0.1
 Provides-Extra: dev
 Requires-Dist: jupyterlab; extra == 'dev'
 Requires-Dist: watchfiles; extra == 'dev'
@@ -11,7 +12,7 @@ Description-Content-Type: text/markdown
 
 # revisit
 
-## Installation
+# Installation
 
 ```sh
 pip install revisit
@@ -23,34 +24,34 @@ or with [uv](https://github.com/astral-sh/uv):
 uv add revisit
 ```
 
-## Usage
+# 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
+The individual classes (`Component`, `Response`, `Sequence`, `StudyMetadata`, `UIConfig`, and `StudyConfig`) should not be created directly. Instead, you should use the corresponding factory functions to insantiate them (`component()`, `response()`, `sequence()`, `studyMetadata()`, `uiConfig()`, and `studyConfig`).
 
-#### `component(component_name__: str, base__: Optional[component], **kwargs: dict) -> Component`
+# Functions
 
-**Description**:  
+## `component(component_name__: str, base__: Optional[component], **kwargs: dict) -> Component`
 
 Instantiates a Component class with the given input parameters.
 
-#### **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**:
+### **Returns**:
 - `Component`: Returns an instantiation of the Component class.
 
-#### **Raises**:
+### **Raises**:
 - `RevisitError`: If the required properties are not specified, and exception will be raised.
 
-#### **Example**:
+### **Example**:
 ```python
 import revisit as rvt
 
@@ -71,24 +72,23 @@ my_other_component = rvt.component(
 ```
 
 
-#### `response(**kwargs: dict) -> Response`
+## `response(**kwargs: dict) -> Response`
 
-**Description**:  
 
 Instantiates a Response class with the given input parameters.
 
-#### **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**:
+### **Returns**:
 - `Response`: Returns an instantiation of the Response class.
 
-#### **Raises**:
+### **Raises**:
 - `RevisitError`: If the required properties are not specified, and exception will be raised.
 
-#### **Example**:
+### **Example**:
 ```python
 import revisit as rvt
 
@@ -102,22 +102,51 @@ my_response = rvt.response(
 )
 ```
 
-### Classes 
+## `studyMetadata(**kwargs: dict) -> StudyMetadata`
 
-#### `Component`
+## `uiConfig(**kwargs: dict) -> UIConfig`
 
-**Description**:  
-A brief summary of the class's purpose and functionality.
+### `studyConfig(studyMetadata: StudyMetadata, uiConfig: UIConfig, sequence: ComponentBlock, schema: str, components: Optional[List[Component]]) -> StudyConfig`
+
+Instantiates a the final `StudyConfig` based on the `UIConfig`, `StudyMetadata`, `Sequence`, and `Components` input. Note that the components list is completely optional: using the `studyConfig` factory function automatically populates all components based on their presence in the sequence.
+
+### **Parameters**:
+| Parameter | Type   | Description                     | Default Value |
+|-----------|--------|---------------------------------|---------------|
+| `studyMetadata` | `StudyMetadata` | An instance of the `StudyMetadata` class | _None_ |
+| `uiConfig` | `UIConfig` | An instance of the `UIConfig` class | _None_ |
+| `sequence` | `ComponentBlock` | The top level member of your sequence. | _None_ |
+| `components` | `Optional[List[Component]]` | The list of `Component`s to be added to the config. This is automatically populated based on the inputted sequence | `[]` |
+| `schema` | `str` |The valid `$schema` value for the config | _None_ |
+
+### **Returns**:
+- `StudyConfig`: Returns an instantiation of the StudyConfig class.
+
+### **Raises**:
+- `RevisitError`: If the required properties are not specified, and exception will be raised.
 
-#### **Attributes**:
+### **Example**:
+
+```python
+
+```
+
+# Classes 
+
+## `Component`
+
+The class that is instantiated when calling the `component` factory function. Used to define the components in the study configuration file.
+
+### **Attributes**:
 | Attribute   | Type     | Description                         | Default Value |
 |-------------|----------|-------------------------------------|---------------|
-| `component_name__`     | `type`   | Description of attribute 1.         | `default`     |
-| `base__`     | `type`   | Description of attribute 2.         | _None_        |
+| `component_name__`     | `str`   | Name of the component to be used as the key in the study config.        | _None_     |
+| `base__`     | `Optional[Component]`   | The base component which is inherited by this component.         | _None_        |
+| `metadata__` | `Optional[dict]` | A dictionary specifying metadata of the object. This is purely used for additional properties which are not written to the config and may be used to attach arbitrary data to the component without affecting the final output. | _None_ |
 
+### **Methods**:
 
-#### **Methods**:
-##### `responses(responses: List[Response]) -> self`
+#### `responses(responses: List[Response]) -> self`
 
 **Description**:  
 Sets responses for the component
@@ -133,7 +162,7 @@ Sets responses for the component
 **Raises**:  
 - `RevisitError`: If the list is not a valid list of responses, raises and exception.
 
-#### **Example**:
+**Example**:
 ```python
 my_response=rvt.response(
     id='my_response',
@@ -163,7 +192,7 @@ Returns the response of the component with the given ID. If the Response does no
 **Returns**:
 - `Response`: The response with the given ID.
 
-#### **Examples**:
+**Example**:
 ```python
 the_response = my_component.get_response(id='the_response')
 
@@ -184,7 +213,7 @@ Edits the Response in the Component with the given ID. This is done by creating
 **Returns**:
 - `self`: Returns self for method chaining.
 
-#### **Examples**:
+**Example**:
 ```python
 test_response = rvt.response(
     id='test_response',
@@ -246,10 +275,11 @@ Clones the component with the given new component name.
 |-------------|----------|-------------------------------------|---------------|
 | `component_name__`    | `str`   | New component name to assign to cloned component.        | _None_     |
 
+
 **Returns**:
 - `self`: Returns self for method chaining.
 
-#### **Examples**:
+**Example**:
 ```python
 test_response = rvt.response(
     id='test_response',
@@ -297,19 +327,15 @@ print(component_two)
 '''
 ```
 
-#### `Response`
+## `Response`
 
-**Description**:  
-A brief summary of the class's purpose and functionality.
+This is the `Responsse` class. When calling the `response` factory function, an instantiation of this class is returned.
 
-#### **Attributes**:
-| Attribute   | Type     | Description                         | Default Value |
-|-------------|----------|-------------------------------------|---------------|
-| `component_name__`     | `type`   | Description of attribute 1.         | `default`     |
-| `base__`     | `type`   | Description of attribute 2.         | _None_        |
+### **Attributes**:
+_No attributes_
 
 
-#### **Methods**:
+### **Methods**:
 
 #### `set(**kwargs: dict) -> self`
 
@@ -325,10 +351,10 @@ Sets the values of the response to the input dictionary. The `type` cannot be ch
 **Returns**:
 - `self`: Returns self for method chaining.
 
-#### **Raises**:
+**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**:
+**Examples**:
 ```python
 response_one = rvt.response(
     id='r-1',
@@ -369,7 +395,7 @@ _No parameters_
 **Returns**:
 - `self`: Returns self for method chaining.
 
-#### **Examples**:
+**Examples**:
 ```python
 import random
 question_1 = rvt.response(
@@ -432,6 +458,279 @@ Expected Output:
 '''
 ```
 
+
+## `ComponentBlock`
+
+**Description**:  
+The `ComponentBlock` class (also referred to as a "Sequence"). A well-defined sequence simply contains an order and a set of components, with other optional properties. Just as in the nested structure of component blocks in the reVISit study configuration, `ComponentBlock` classes can be added together.
+
+A `ComponentBlock` automatically tracks all of its existing `Component` classes. When the `ComponentBlock` is added to the study configuration, all components will automatically be added to the high-level components element of the study config.
+
+### **Attributes**:
+_No attributes_
+
+
+### **Methods**:
+
+#### `__add__(other: Union[ComponentBlock, Component]) -> self:`
+
+**Description**:
+
+Adds two `ComponentBlock` or `Component` to the input sequence. When adding two sequences together, the right sequence gets added as a `ComponentBlock` to the list of components of the left sequence. When the right object is an instance of the `Component` class, the component is added to the `ComponentBlock`'s list of components.
+
+
+**Parameters**:  
+| Parameter   | Type     | Description                         | Default Value |
+|-------------|----------|-------------------------------------|---------------|
+| `other`   | `Union[ComponentBlock, Component]`   | Other item adding to left sequence.        | _None_     |
+
+**Returns**:
+- `self`: Returns self for method chaining.
+
+**Raises**:
+- `NotImplemented`: If the right item is not a `Component` or `ComponentBlock`, raises a `NotImplemented` exception.
+
+**Examples**:
+```python
+first_sequence = rvt.sequence(
+    order='fixed',
+    components=[introduction]
+)
+second_sequence = rvt.sequence(
+    order='random',
+    components=[comp_one, comp_two]
+)
+
+first_sequence = first_sequence + second_sequence
+
+print(first_sequence)
+'''
+Expected Output:
+{
+    "order": "fixed",
+    "components" : [
+        "introduction",
+        {
+            "order": "random"
+            "components" : [
+                "comp_one",
+                "comp_two"
+            ]
+        }
+    ]
+}
+'''
+post_study = rvt.component(
+    component_name__='post-study',
+    type='markdown',
+    path='./post-study.md'
+)
+
+first_sequence = first_sequence + post_study
+print(first_sequence)
+'''
+Expected Output:
+{
+    "order": "fixed",
+    "components" : [
+        "introduction",
+        {
+            "order": "random"
+            "components" : [
+                "comp_one",
+                "comp_two"
+            ]
+        },
+        "post-study"
+    ]
+}
+'''
+```
+
+#### `get_component(name: str) -> Component:`
+
+**Description**:
+
+Fetches the `Component` with the given component name from the sequence.
+
+
+**Parameters**:  
+| Parameter   | Type     | Description                         | Default Value |
+|-------------|----------|-------------------------------------|---------------|
+| `name`   | `str`   | string matching the `component_name__` attribute of the desired `Component`.       | _None_     |
+
+**Returns**:
+- `Component`: Returns desired `Component`. If no component with specified name is found, returns `None`.
+
+
+**Examples**:
+```python
+
+sequence = rvt.sequence(
+    order='random',
+    components=[comp_one, comp_two]
+)
+
+print(sequence.get_component(name='comp_two'))
+'''
+{
+    "type": "markdown",
+    "path": "my_markdown_file.md",
+    "response": []
+}
+'''
+```
+
+#### `permute(factors: List[dict], order: 'fixed' | 'latinSquare' | 'random', numSamples: Optional[int], component_function: Optional[Callable]) -> self`
+
+**Description**:
+Permutes the the existing components of the sequence over the given `factors`. The permute method can be chained to complex study sequences. By default, the factors are attached as `metadata__` attributes to each component created. If a `component_function` is passed in as an argument, all current factors and `metadata__` of the component will be passed into the component function. The component function must return a valid `Component` instance. 
+
+**Parameters**:  
+| Parameter   | Type     | Description                         | Default Value |
+|-------------|----------|-------------------------------------|---------------|
+| `factors`   | `List[dict]`   | A list of single-key dictionaries to permute over. | _None_     |
+| `order` | `'fixed' \| 'latinSquare' \| 'random' ` |The order to assign to the current permuted component block. |  _None_ |
+| `numSamples` | `Optional[int]` | The `numSamples` value to assign to the current permuted block. | _None_ |
+| `component_function` | `Optional[Callable]` | A function defining what component should be generated during permutation. If not provided, the permutation function inherits the existing components in the sequence as new components and applies the factors as metadata. If given, the metadata is passed into the component function as arguments.  | _None_ |
+
+**Returns**:
+- `self`: Returns self for method chaining.
+
+**Raises**:
+- `TypeError`: The `component_function` must be able to take in all metadata of the sequence's existing components as well as the current factors. For example, if you start with a component with no metadata and permute over the factors `[{'key_1':'value_1'}, {'key_1': 'value_2'}]`, the component function should be defined to take in the parameter `key_1`. Otherwise, this will most likely result in a `TypeError` being raised. If you are chaining multiple permute methods after one another, please note that the the set of factors that are passed into the permute function are applied as metadata to the resulting components. Thus, your function must be able to take in all factors as arguments. To avoid this, you can simply use `**kwargs` as your parameter input of your component function.
+
+#### **Examples**:
+
+**Simple Permutation**
+```python
+
+comp_one = rvt.component(component_name__='my-base', type='markdown', path='./my-markdown.md')
+
+sequence = rvt.component(order='fixed',components=[comp_one])
+
+sequence.permute(
+    factors=[{'condition':'A'}, {'condition':'B'}],
+    order='random'
+)
+
+print(sequence)
+'''
+Expected Output:
+{
+    "order": "random", <--- Since there was only one component in the original sequence, order gets overwritten.
+    "components": [
+        "my-base_condition:A",
+        "my-base_condition:B" <--- Note that the default behavior appends the factors to the name
+    ]
+}
+
+The two components generated are inherently identical, except with different metadata__ attributes. 
+These metadata__ attributes are not outputed into the final JSON study config or seen when printing out
+the individual components.
+'''
+
+sequence.permute(
+    factors=[{'type':'1'}, {'type': '2'}]
+    order='fixed',
+    numSamples=1
+)
+
+print(sequence)
+'''
+Expected Output:
+{
+    "order": "random",
+    "components": [
+        {
+            "order": "fixed", <--- New order gets added to inner most component blocks.
+            "components": [
+                "my-base_condition:A_type:1",
+                "my-base_condition:A_type:2",
+            ],
+            "numSamples": 1
+        },
+        {
+            "order": "fixed",
+            "components": [
+                "my-base_condition:B_type:1",
+                "my-base_condition:B_type:2",
+            ],
+            "numSamples": 1
+        },
+    ]
+
+}
+'''
+```
+
+**Using the `component_function`**
+
+```python
+# Defining component function.
+# Takes in kwargs to prevent conflicts with any existing metadata.
+def my_comp_function(**kwargs):
+    condition = kwargs.get('condition')
+    type_ = kwargs.get('type')
+    # If condition and type_ are both defined, return new component.
+    if condition is not None and type_ is not None:
+        rvt.component(
+            type='website'
+            component_name__=f"{condition}__{type_}"
+            parameters={
+                'condition': condition,
+                'type': type_
+            },
+            response=[
+                rvt.response(
+                    id=f"response_{condition}_{type_}",
+                    type="longText",
+                    prompt=f"How do you feel about condition {condition} and type {type_}?",
+                    required=True
+                )
+            ]
+        )
+
+    # If not both defined, return a blank component with "BAD-COMPONENT" name.
+    # Useful for debugging
+    return rvt.component(type='questionnaire',component_name__="BAD-COMPONENT")
+
+sequence = rvt.sequence(order='fixed').permute(
+    factors=[{'condition':'A'}, {'condition':'B'}],
+    order='random'
+).permute(
+    factors=[{'type':'1'}, {'type': '2'}]
+    order='fixed',
+    numSamples=1,
+    component_function=my_comp_function
+)
+print(sequence)
+'''
+Expected Output:
+{
+    "order": "random",
+    "components": [
+        {
+            "order": "fixed", <--- New order gets added to inner most component blocks.
+            "components": [
+                "A__1",
+                "A__2",
+            ],
+            "numSamples": 1
+        },
+        {
+            "order": "fixed",
+            "components": [
+                "B__1",
+                "B__2"
+            ],
+            "numSamples": 1
+        },
+    ]
+
+}
+'''
+```
 ## Development
 
 We recommend using [uv](https://github.com/astral-sh/uv) for development.