# Root-Level Properties

## Overview

Every Protobi dataset has a special element with `"key": "$root"` that serves as the dataset's root configuration. This document identifies properties that are primarily or exclusively used at the root level.

## What is the Root Element?

The `$root` element is the top-level configuration object for a Protobi dataset. It contains:
- Dataset metadata (title, dates, identifiers)
- Global display settings (symbols, precision, toolbar)
- Default behavior configurations
- Project-level settings

**Example:**
```json
{
  "$root": {
    "key": "$root",
    "title": "Consumer Survey 2024",
    "toolbar": "...",
    "nsymbol": "n=",
    "precisionFreq": 0,
    "showPercentSymbol": true,
    "colorway": ["#1f77b4", "#ff7f0e", "#2ca02c"],
    "children": ["q1", "q2", "demographics"]
  }
}
```

## Analysis Results

Analyzed **509 datasets** with:
- **488 root elements** (`$root`)
- **889,458 non-root elements** (questions, categories, etc.)

Found **36 root-level properties**:
- **35 properties** used exclusively at root (100% root usage)
- **1 property** used primarily at root (95% root usage)

## Root-Only Properties (100%)

These properties **never** appear on non-root elements.

### Dataset Metadata

| Property | Description | Usage |
|----------|-------------|-------|
| `projectId` | Project identifier | 5.3% of roots |
| `identifier` | Dataset identifier | 5.5% of roots |
| `internalTitle` | Internal project title | 5.5% of roots |
| `description` | Dataset description | 5.5% of roots |
| `startDate` | Survey start date | 5.3% of roots |
| `endDate` | Survey end date | 5.3% of roots |
| `fieldingTime` | Fielding duration/time | 5.3% of roots |
| `id` | Unique ID | 12.9% of roots |

### Display Symbols & Formatting

| Property | Description | Usage |
|----------|-------------|-------|
| `nsymbol` | Symbol for sample size display (e.g., "n=", "N=") | **24.0% of roots** |
| `nilSymbol` | Symbol for missing/null values | 15.8% of roots |
| `zeroSymbol` | Symbol for zero values | 15.8% of roots |
| `minPercentSymbol` | Symbol for percentages below threshold | 12.3% of roots |
| `nunwtdsymbol` | Symbol for unweighted sample size | 9.4% of roots |
| `showPercentSymbol` | Whether to show % symbol | 15.4% of roots |

### Precision Settings

| Property | Description | Usage |
|----------|-------------|-------|
| `precisionFreq` | Decimal places for frequencies | **88.9% of roots** |
| `precisionMean` | Decimal places for means | 4.1% of roots |

### UI Configuration

| Property | Description | Usage |
|----------|-------------|-------|
| `toolbar` | Toolbar configuration/buttons | **30.1% of roots** |
| `toolbarOrientation` | Toolbar layout orientation | 0.6% of roots |
| `view` | View settings object | 20.1% of roots |
| `view.showMissing` | Show missing values in view | 0.8% of roots |
| `displayMode` | Display mode setting | 1.8% of roots |

### Statistical Testing

| Property | Description | Usage |
|----------|-------------|-------|
| `pval` | P-value threshold for significance | 7.0% of roots |
| `showPairwise` | Show pairwise comparisons | 20.1% of roots |

### Color Settings

| Property | Description | Usage |
|----------|-------------|-------|
| `colorway` | Default color palette (array) | 0.4% of roots |
| `chartOptions.colorway` | Chart-specific color palette | 8.2% of roots |

### Weighting & Data

| Property | Description | Usage |
|----------|-------------|-------|
| `weightFields` | Fields used for weighting | 1.8% of roots |
| `loops` | Number of data loops | 14.5% of roots |

### Localization

| Property | Description | Usage |
|----------|-------------|-------|
| `language` | Current language code | 1.0% of roots |
| `usedLanguages` | Available languages array | 3.3% of roots |

### Survey Content

| Property | Description | Usage |
|----------|-------------|-------|
| `questions` | Questions metadata | 5.5% of roots |
| `externalIntroduction` | External introduction text | 5.5% of roots |

### References

| Property | Description | Usage |
|----------|-------------|-------|
| `referenceDatasetIds` | Referenced dataset IDs | 4.5% of roots |
| `idKey` | Key field for IDs | 1.0% of roots |

### Chart Defaults

| Property | Description | Usage |
|----------|-------------|-------|
| `chartOptions.defaultSeriesName` | Default name for chart series | 0.4% of roots |

### Internal/System

| Property | Description | Usage |
|----------|-------------|-------|
| `gsg-initialized` | Initialization flag | 1.6% of roots |

## Primarily Root Properties (90-99%)

These properties are **mostly** used at root but occasionally appear elsewhere.

| Property | Root Usage | Non-Root Usage | Percentage |
|----------|-----------|----------------|------------|
| `minPercent` | 60 | 3 | 95.2% root |

## Property Scope in Schema

Root-level properties are now marked in `properties-dict-enhanced.json` with:

```json
{
  "toolbar": {
    "name": "toolbar",
    "type": "string",
    "description": "Toolbar configuration",
    "scope": "root",
    "scopeNote": "Used exclusively at root level ($root element)",
    "rootUsage": {
      "rootCount": 147,
      "nonRootCount": 0,
      "rootPercentage": 100
    }
  }
}
```

## Usage Examples

### Accessing Root Properties

```javascript
// Get root element
const root = dataset.get('$root');

// Access root properties
console.log(root.nsymbol);        // "n="
console.log(root.precisionFreq);  // 0
console.log(root.toolbar);        // toolbar config
console.log(root.colorway);       // ["#1f77b4", ...]
```

### Checking Property Scope

```javascript
import properties from './properties-dict-enhanced.json';

function isRootProperty(propName) {
  const prop = properties[propName];
  return prop && prop.scope === 'root';
}

console.log(isRootProperty('toolbar'));      // true
console.log(isRootProperty('title'));        // false
console.log(isRootProperty('nsymbol'));      // true
```

### Filtering Root Properties

```javascript
// Get all root-level properties
const rootProps = Object.entries(properties)
  .filter(([k, v]) => v.scope === 'root')
  .map(([k, v]) => k);

console.log(rootProps);
// ["toolbar", "nsymbol", "precisionFreq", "pval", ...]
```

## Key Observations

### Most Common Root Properties

1. **`precisionFreq`** (88.9%) - Nearly all datasets specify frequency precision
2. **`toolbar`** (30.1%) - Common to configure toolbar
3. **`nsymbol`** (24.0%) - Common to customize sample size display
4. **`showPairwise`** (20.1%) - Statistical testing configuration
5. **`view`** (20.1%) - View configuration settings

### Categories of Root Properties

1. **Global Display Settings** (28.6%)
   - Symbols, precision, formatting defaults
   - Apply to entire dataset unless overridden

2. **Dataset Metadata** (22.9%)
   - Project info, dates, identifiers
   - Used for organization and reporting

3. **Statistical Defaults** (11.4%)
   - P-values, significance settings
   - Control testing across entire dataset

4. **UI Configuration** (17.1%)
   - Toolbar, view modes, display modes
   - Control user interface behavior

5. **Color & Styling** (5.7%)
   - Default color palettes
   - Inherited by child elements

6. **Data Processing** (14.3%)
   - Weighting, loops, data handling
   - Affect how data is computed

## Property Inheritance

Root properties typically define **defaults** that cascade to child elements:

```javascript
// Root defines default
{
  "$root": {
    "nsymbol": "n=",
    "precisionFreq": 0,
    "colorway": ["#1f77b4", "#ff7f0e"]
  }
}

// Child elements inherit these defaults
// unless they override them
{
  "q1": {
    "title": "Age",
    // inherits nsymbol: "n=" from root
    // inherits precisionFreq: 0 from root
    // inherits colorway from root
  }
}
```

## Implementation Notes

### When to Use Root Properties

✅ **Use root-level properties for:**
- Dataset-wide defaults
- Global UI configuration
- Project metadata
- Statistical test parameters
- Display symbol conventions

❌ **Don't use root-level properties for:**
- Element-specific settings
- Question text or labels
- Individual chart configurations
- Per-element display overrides

### Validation

When validating element data:

```javascript
function validateElement(element, properties) {
  const isRoot = element.key === '$root';

  for (const [key, value] of Object.entries(element)) {
    const prop = properties[key];

    // Check if root-only property used on non-root element
    if (prop && prop.scope === 'root' && !isRoot) {
      console.warn(`Property '${key}' should only be used on $root element`);
    }
  }
}
```

## See Also

- **properties-dict-enhanced.json** - Full property definitions with scope markers
- **root-properties.json** - List of all root-level properties
- **SUMMARY.md** - Overview of documentation system

---

*Analysis based on 509 datasets with 488 root elements*
*Properties with scope="root" are used exclusively or primarily at the dataset root level*
