# Displaying Risk Scores

This guide covers best practices for visualizing Cubit's AI vulnerability scores in user interfaces.

## Understanding the Scores

Before displaying scores, ensure you understand what each represents:

| Score                         | Range        | Meaning                                              |
| ----------------------------- | ------------ | ---------------------------------------------------- |
| **Automation Susceptibility** | 0-100        | AI exposure level (higher = more vulnerable)         |
| **Human-Centric Resilience**  | 0-100        | Human necessity protection (higher = more protected) |
| **Balanced Impact**           | -100 to +100 | Net positioning (positive = favorable)               |

## Basic Score Display

### Python Example

```python
from cubit import CubitClient

client = CubitClient("cubit_your_key")
job = client.get_job("15-1252.00")  # Software Developers

def format_score(score: float, show_sign: bool = False) -> str:
    """Format score for display."""
    if show_sign:
        return f"{score:+.0f}"
    return f"{score:.0f}"

def interpret_balanced_impact(score: float) -> str:
    """Generate human-readable interpretation."""
    if score >= 20:
        return "Strong position - significant human necessity"
    elif score >= 5:
        return "Favorable position - protected factors outweigh risks"
    elif score >= -5:
        return "Transition zone - role likely to evolve with AI"
    elif score >= -20:
        return "Elevated risk - AI pressure outweighs protection"
    else:
        return "High risk - consider skill development in adjacent areas"

print(f" AI Impact Profile: {job['title']}\n")
print(f"Automation Susceptibility: {format_score(job['scores']['automation_susceptibility_score'])}/100")
print(f"Human-Centric Resilience:  {format_score(job['scores']['human_centric_resilience_score'])}/100")
print(f"Balanced Impact:           {format_score(job['scores']['balanced_impact_score'], show_sign=True)}")
print(f"\n {interpret_balanced_impact(job['scores']['balanced_impact_score'])}")
```

## Color Coding

### Balanced Impact Color Scale

```python
def get_impact_color(score: float) -> str:
    """Return color for balanced impact score."""
    if score >= 15:
        return "#10B981"  # Green - strong position
    elif score >= 5:
        return "#34D399"  # Light green - favorable
    elif score >= -5:
        return "#F59E0B"  # Yellow/amber - transition
    elif score >= -15:
        return "#F97316"  # Orange - elevated risk
    else:
        return "#EF4444"  # Red - high risk
```

### CSS Classes

```css
.score-very-positive { color: #10B981; }  /* +15 or higher */
.score-positive { color: #34D399; }       /* +5 to +15 */
.score-neutral { color: #F59E0B; }        /* -5 to +5 */
.score-negative { color: #F97316; }       /* -15 to -5 */
.score-very-negative { color: #EF4444; }  /* -15 or lower */
```

## Visualization Components

### Progress Bars (React + Tailwind)

```tsx
interface ScoreBarProps {
  label: string;
  value: number;
  max: number;
  colorClass?: string;
}

function ScoreBar({ label, value, max, colorClass = "bg-blue-500" }: ScoreBarProps) {
  const percentage = (value / max) * 100;
  
  return (
    <div className="mb-4">
      <div className="flex justify-between mb-1">
        <span className="text-sm font-medium">{label}</span>
        <span className="text-sm text-gray-500">{value.toFixed(0)}/{max}</span>
      </div>
      <div className="w-full bg-gray-200 rounded-full h-2.5">
        <div 
          className={`h-2.5 rounded-full ${colorClass}`}
          style={{ width: `${percentage}%` }}
        />
      </div>
    </div>
  );
}

function JobScoreCard({ job }) {
  const impactColor = job.balanced_impact_score >= 5 ? "text-green-600" :
                      job.balanced_impact_score <= -5 ? "text-red-600" : 
                      "text-yellow-600";
  
  return (
    <div className="bg-white rounded-lg shadow p-6">
      <h2 className="text-xl font-bold mb-4">{job.title}</h2>
      
      <ScoreBar 
        label="Automation Susceptibility" 
        value={job.scores.automation_susceptibility_score}
        max={100}
        colorClass="bg-red-400"
      />
      
      <ScoreBar 
        label="Human-Centric Resilience" 
        value={job.scores.human_centric_resilience_score}
        max={100}
        colorClass="bg-green-400"
      />
      
      <div className="mt-6 text-center">
        <span className="text-sm text-gray-500">Balanced Impact</span>
        <div className={`text-3xl font-bold ${impactColor}`}>
          {job.balanced_impact_score > 0 ? '+' : ''}
          {job.balanced_impact_score.toFixed(0)}
        </div>
      </div>
    </div>
  );
}
```

### Quadrant Badge

```tsx
function QuadrantBadge({ quadrant }: { quadrant: string }) {
  const config = {
    automation: {
      label: "Automation Zone",
      color: "bg-red-100 text-red-800",
      icon: ""
    },
    augmentation: {
      label: "Augmentation Zone", 
      color: "bg-yellow-100 text-yellow-800",
      icon: ""
    },
    protected: {
      label: "Protected Zone",
      color: "bg-green-100 text-green-800", 
      icon: ""
    },
    transitional: {
      label: "Transitional",
      color: "bg-gray-100 text-gray-800",
      icon: ""
    }
  };
  
  const { label, color, icon } = config[quadrant] || config.transitional;
  
  return (
    <span className={`inline-flex items-center px-3 py-1 rounded-full text-sm font-medium ${color}`}>
      <span className="mr-1">{icon}</span>
      {label}
    </span>
  );
}
```

## Comparative Displays

### Side-by-Side Comparison

```python
def compare_jobs_display(soc_codes: list[str]):
    """Display multiple jobs in comparison format."""
    comparison = client.compare_jobs(soc_codes)
    
    # Print header
    print(f"\n{'Job Title':<35} {'Risk':>8} {'Resil':>8} {'Impact':>8} {'Quadrant':<15}")
    print("-" * 80)
    
    for job in comparison["comparison"]:
        print(f"{job['title'][:35]:<35} "
              f"{job['automation_susceptibility_score']:>8.0f} "
              f"{job['human_centric_resilience_score']:>8.0f} "
              f"{job['balanced_impact_score']:>+8.0f} "
              f"{job['quadrant']:<15}")

# Usage
compare_jobs_display([
    "15-1252.00",  # Software Developers
    "29-1141.00",  # Registered Nurses
    "43-3031.00",  # Bookkeeping Clerks
    "23-1011.00",  # Lawyers
])
```

**Output:**

```
Job Title                           Risk    Resil   Impact Quadrant       
--------------------------------------------------------------------------------
Software Developers                   48       55       +7 transitional     
Registered Nurses                     47       70      +23 protected      
Bookkeeping Clerks                    49       49       +0 transitional     
Lawyers                               42       63      +21 transitional     
```

### Scatter Plot (Chart.js)

```javascript
// Data preparation
const jobs = await fetch('/api/jobs/batch').then(r => r.json());

const chartData = {
  datasets: [{
    label: 'Jobs',
    data: jobs.map(job => ({
      x: job.automation_susceptibility_score,
      y: job.human_centric_resilience_score,
      label: job.title,
      quadrant: job.classification.quadrant
    })),
    backgroundColor: jobs.map(job => {
      switch(job.classification.quadrant) {
        case 'protected': return '#10B981';
        case 'augmentation': return '#F59E0B';
        case 'automation': return '#EF4444';
        default: return '#6B7280';
      }
    }),
  }]
};

const config = {
  type: 'scatter',
  data: chartData,
  options: {
    scales: {
      x: {
        title: { display: true, text: 'Automation Susceptibility ->' },
        min: 0, max: 100
      },
      y: {
        title: { display: true, text: 'Human Resilience ->' },
        min: 0, max: 100
      }
    },
    plugins: {
      tooltip: {
        callbacks: {
          label: (ctx) => ctx.raw.label
        }
      },
      annotation: {
        annotations: {
          hLine: {
            type: 'line',
            yMin: 50, yMax: 50,
            borderColor: 'rgba(0,0,0,0.2)',
            borderDash: [5, 5]
          },
          vLine: {
            type: 'line',
            xMin: 50, xMax: 50,
            borderColor: 'rgba(0,0,0,0.2)',
            borderDash: [5, 5]
          }
        }
      }
    }
  }
};
```

## Percentile Context

Help users understand where a job ranks relative to others:

```python
job = client.get_job("15-1252.00")

auto_quantile = job["scores"]["automation_susceptibility_quantile"]
resil_quantile = job["scores"]["human_centric_resilience_quantile"]

print(f"Automation Susceptibility: {job['scores']['automation_susceptibility_score']:.0f}/100")
print(f"  -> Higher than {auto_quantile:.0%} of occupations")

print(f"Human-Centric Resilience: {job['scores']['human_centric_resilience_score']:.0f}/100")
print(f"  -> Higher than {resil_quantile:.0%} of occupations")
```

### Percentile Visualization

```tsx
function PercentileBar({ value, label }: { value: number; label: string }) {
  return (
    <div className="relative h-8 bg-gradient-to-r from-green-200 via-yellow-200 to-red-200 rounded">
      <div 
        className="absolute top-0 w-1 h-full bg-black"
        style={{ left: `${value * 100}%` }}
      />
      <div 
        className="absolute -top-6 text-xs font-medium"
        style={{ left: `${value * 100}%`, transform: 'translateX(-50%)' }}
      >
        {label}
      </div>
    </div>
  );
}
```

## Communication Best Practices

### Do

* **Provide context**: "47/100 automation risk (average is 46)"
* **Explain what scores mean**: Include tooltips or explainers
* **Show relative position**: Use percentiles or comparisons
* **Use color consistently**: Same colors for same meanings
* **Offer actionable insights**: "Consider developing these resilient skills..."

### Don't

* **Alarm users unnecessarily**: High risk != immediate job loss
* **Oversimplify**: Don't reduce to just "safe" vs "at risk"
* **Hide methodology**: Link to score explanations
* **Use confusing scales**: Stick to the native 0-100 or -100 to +100 ranges

## Sample Narratives

Generate human-readable interpretations:

```python
def generate_narrative(job: dict) -> str:
    """Generate a narrative interpretation of job scores."""
    title = job["title"]
    auto = job["scores"]["automation_susceptibility_score"]
    resil = job["scores"]["human_centric_resilience_score"]
    impact = job["scores"]["balanced_impact_score"]
    quadrant = job["classification"]["quadrant"]
    
    narratives = {
        "automation": f"{title} faces elevated AI exposure with limited protective factors. "
                     f"Many tasks are procedural and digital, while physical presence and "
                     f"relational depth are minimal. Workers should consider developing "
                     f"skills in adjacent, more protected roles.",
        
        "augmentation": f"{title} sits in the augmentation zone, where AI will likely "
                       f"transform rather than replace the role. Technical tasks may be "
                       f"automated, but human judgment, relationships, or physical presence "
                       f"remain essential. Expect human-AI collaboration.",
        
        "protected": f"{title} has strong protection from AI disruption. The work requires "
                    f"significant human presence-either physical skills, deep relationships, "
                    f"or both-that current AI cannot replicate. This represents durable "
                    f"human value.",
        
        "transitional": f"{title} is neither highly exposed nor deeply human-dependent. "
                     f"The varied, unstructured nature of the work makes automation "
                     f"investment less attractive, but there's also limited human necessity "
                     f"protecting the role long-term."
    }
    
    return narratives.get(quadrant, "")

# Usage
job = client.get_job("29-1141.00")  # Registered Nurses
print(generate_narrative(job))
```

## Next Steps

* [Task-Level Analysis](/guides/task-analysis.md) - Show which specific tasks are most/least vulnerable
* [Career Transitions](/guides/career-transitions.md) - Display alternative career paths
* [Regional Analysis](/guides/regional-analysis.md) - Geographic vulnerability maps


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maidenlabs.tools/guides/risk-scores.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.