> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archetypeai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Sheets Integration

> Analyze time-series sensor data and log results to Google Sheets for collaborative monitoring and visualization.

```mermaid theme={"system"}
graph LR
    A[CSV Sensor Data] --> B[Machine State Lens]
    C[N-shot files] --> B
    B --> D[Google Sheets Results]
    
    style B fill:#9EBBFF,stroke:none,color:#000000
```

## How it works

* **Machine State Lens** running in Archetype platform for time-series classification
* **CSV analysis** with n-shot files sent to Newton for few-shot learning classification
* **Google Sheets integration** for real-time results logging and collaborative monitoring
* **Two integration modes**:
  1. **File-to-Sheets**: Run code in the terminal and log results in Sheets
  2. **Spreadsheet-Driven**: Control everything from Sheets

## Prerequisites

The instructions below assume you are following best practices and have downloaded this git repo into a parent directory at: \~/atai.

If you have already installed the [ATAI Python Library](https://github.com/archetypeai/python-client) and cloned the [cookbook repository](https://github.com/archetypeai/archetypeai-cookbook),proceed directly to [Setup](#setup).

#### Install Conda

```
wget https://repo.anaconda.com/archive/Anaconda3-2022.05-Linux-x86_64.sh
bash Anaconda3-2022.05-Linux-x86_64.sh
source ~/.bashrc
```

#### Setup dev environment

```
conda create -n dev_env python=3.10
conda activate dev_env
```

#### Install [ATAI Python Library](https://github.com/archetypeai/python-client)

```bash theme={"system"}
git clone git@github.com:archetypeai/python-client.git
cd python-client
python -m pip install .
```

#### Clone [Cookbook Repository](https://github.com/archetypeai/archetypeai-cookbook)

```bash theme={"system"}
git clone https://github.com/archetypeai/archetypeai-cookbook.git
```

## Setup

### Google API Configuration

To authenticate with Google Sheets, you'll need OAuth 2.0 credentials. Follow the [Google Sheets API Credentials Setup Guide](/code-examples/machine-state/setup/credentials-setup) to configure your `credentials.json` file.

## Run Demos

## Demo 1: Command Line to Sheets

Analyze local CSV files and automatically log results to Google Sheets.

### Running the Demo

From the Cookbook root directory with your conda environment activated:

```bash theme={"system"}
cd spreadsheet-analysis/cl-to-sheets/
pip install -r requirements.txt
python app.py
```

### Interactive Prompts

1. **API Key**: Your ArchetypeAI API key
2. **Google Sheets ID**: Extract from your spreadsheet URL
3. **Data file**: Path to CSV file to analyze (drag & drop supported) - you can use the files under `command-line-demos/machine-state/sample-files`
4. **N-shot files**: Example CSV files for each state class

### Example Session

```
=== Sensor Analysis with Google Sheets ===

Enter your Archetype AI API key: your-key-here
Enter your Google Sheets ID: 1ehByJmpvDBH357BRuDBmQ2EB12qjTjj4Y0Z1OXxmGro

Enter path to the file to analyze: /path/to/sensor_data.csv
✓ File loaded: 5000 rows

Enter path to focus CSV file: /path/to/healthy.csv
✓ Added: class 'healthy' from healthy.csv

Enter path to focus CSV file: /path/to/broken.csv  
✓ Added: class 'broken' from broken.csv

Enter path to focus CSV file: done

--- Configuration Summary ---
Data file: sensor_data.csv
Focus classes: healthy, broken

Press Enter to start analysis...

🔍 Analyzing sensor data...
✓ Window 1: healthy (92% confidence) - Logged to sheet
✓ Window 2: healthy (88% confidence) - Logged to sheet
✓ Window 3: broken (95% confidence) - Logged to sheet
```

## Demo 2: Spreadsheet-Driven

Control everything directly from Google Sheets - no need to interact with terminal once script is running.

### Setup Template

Create a pre-configured spreadsheet template:

```bash theme={"system"}
cd spreadsheet-analysis/spreadsheet-driven
pip install -r requirements.txt
python create_example_spreadsheet.py
```

Keep the spreadsheet ID for next step.

### Running the Monitor

Start the monitoring script:

```bash theme={"system"}
python app.py
```

### Triggering Analysis

#### Prepare Your Data

1. Open the Google Sheet created in the previous step
2. Navigate to the **Config** sheet and add your API key in cell **B1**
3. Import your sensor data:
   * Click on the **Data** sheet tab
   * Import your CSV data to analyze (File → Import → Upload)
   * Ensure headers match: `timestamp`, `a1`, `a2`, `a3`, `a4`

#### Add Focus Examples

1. Create sheets for each machine state you want to classify
2. Import example data for each state:
   * Create/rename a sheet tab (e.g., "healthy", "broken")
   * Import CSV data representing that state
   * Repeat for each classification category

#### Start Analysis

1. Return to the **Config** sheet
2. Type **"RUN"** in cell **B10**
3. Monitor progress in cell **B11** (status updates)
4. View results in the automatically created **Results** sheet

### Real-time Monitoring

The script monitors cell B10 for triggers and updates status in B11:

* **"Ready"** - Waiting for trigger
* **"TRIGGERED"** - Analysis starting
* **"RUNNING - Processed X windows"** - In progress
* **"COMPLETED - Analyzed X windows"** - Finished
* **"ERROR - \[details]"** - Something went wrong

## Window Size Configuration (to be reviewed)

The window size parameter determines how many data points Newton analyzes in each inference cycle. This affects the granularity of state classification.

### Recommended Settings

* **Default**: Auto-calculated based on focus file lengths
* **High-frequency sensors** (greater than 100Hz): 256-512 points
* **Low-frequency sensors** (less than 10Hz): 64-128 points
* **Maximum**: 1024 points

### How It Works

Each window represents a time segment of sensor data. The system compares these windows against your focus examples to classify the machine state. Non-overlapping windows (step size = window size) provide independent classifications, while overlapping windows offer smoother state transitions.

### Constraints

* Window size cannot exceed the length of your shortest focus file
* Minimum window size is 16 data points for meaningful analysis