User Workbench
==============

This section provides a comprehensive guide on how to use the Visual Viper library for various tasks. Whether you are a researcher, a data scientist, or a developer, you'll find actionable steps and examples here.

Getting Started
---------------

Start by importing the library. Here is a simple example:

.. code-block:: python

   from visual_viper import *

Creating a Basic Chart: Forest Plot using Google Spreadsheet Data
----------------------------------------------------------------

This example demonstrates how to create a forest plot using data fetched from Google Spreadsheets with named ranges and deploy the resulting chart to Google Drive.

1. **Initialize the Orchestrator**

   Initialize the `VisualViperOrchestrator` which will coordinate the entire process.

   .. code-block:: python

      vv = VisualViperOrchestrator()

2. **Register Components**

   Register the dataset builder, chart renderer, and chart deployer.

   .. code-block:: python

      vv.register_dataset_builder(GoogleSpreadsheetDatasetBuilder())
      vv.register_chart_renderer(AltairChartRenderer())
      vv.register_chart_deployer(GdriveChartDeployer(
        folder_id="your_google_drive_folder_id",
        mime_type="image/svg+xml"
      ))

3. **Data Source Configuration for Forest Plots**

   This step involves setting up the configuration for generating a forest plot. Here, you'll specify where to source various data metrics for the plot using the `ForestPlot` and `ForestPlotBinding` classes.

   **Understanding the `Key` Class**

   The `Key` class is crucial for specifying data sources. Each `Key` instance requires two pieces of information:

   1. **Named Range**: A string identifier that points to the specific metric in the Google Spreadsheet.
   2. **Spreadsheet ID**: The unique identifier for the Google Spreadsheet.

   These allow the system to fetch the exact data you need for your forest plot.

   .. code-block:: python

      notation_builder = ForestPlot(
        id="the_id_for_the_plot",
        title="the_title_for_the_plot",
        subtitle="the_subtitle_for_the_plot",
        bindings=[
          ForestPlotBinding(
            measure="your_measure",
            hr=Key("your_hr_named_range", "your_spreadsheet_id"),
            lo=Key("your_low_ci_named_range", "your_spreadsheet_id"),
            hi=Key("your_high_ci_named_range", "your_spreadsheet_id"),
          ),
          # Add more bindings as needed
        ]
      )
      vv.register_notation_builder(notation_builder)

   Both `title`and `subtitle` may be either a string or a list with strings (each element of the list will be printed in a different line).

4. **Run the Process**

   Finally, execute the entire process to generate and deploy the forest plot.

   .. code-block:: python

      vv.run()

.. Advanced Usage
.. --------------

.. 1. **Customizing Notations**: How to customize chart notations for unique requirements.

.. 2. **Other Advanced Use Cases**: TBD

.. Troubleshooting
.. ---------------

.. Provide common troubleshooting steps, FAQs, and tips for resolving issues.

.. 1. **Issue 1**: Description and resolution steps.
.. 2. **Issue 2**: Description and resolution steps.