id: https://nde.nl/ontology/hc/classes/ConversionRate
name: ConversionRate
title: ConversionRate

prefixes:
  linkml: https://w3id.org/linkml/
  hc: https://nde.nl/ontology/hc/
  schema: http://schema.org/
  xsd: http://www.w3.org/2001/XMLSchema#

imports:
  - linkml:types
  - ./ConversionRateType
  - ./ConversionRateTypes
  - ./TimeSpan
  - ../slots/has_or_had_type
  - ../slots/temporal_extent

default_range: string

classes:
  ConversionRate:
    description: >-
      Structured representation of a conversion rate metric for heritage institutions.
      
      **WHY A DEDICATED CLASS?**
      
      Conversion rates are more than simple floats - they need:
      - **Type**: What kind of conversion (visitor-to-purchase, visitor-to-member)
      - **Value**: The actual percentage (0.35 = 35%)
      - **Time Period**: When this rate was measured
      - **Context**: Comparison benchmarks, notes
      
      **SLOT_FIXES.YAML REVISION** (lines 1646-1669):
      - Branch 1: has_or_had_type → ConversionRateType/ConversionRateTypes
      - Branch 2: temporal_extent → TimeSpan (measurement period)
      
      **USE CASES**:
      - Gift shop performance: 35% visitor-to-purchase conversion
      - Membership drives: 5% visitor-to-member conversion
      - Digital engagement: 3% website-to-visit conversion
      
      **ONTOLOGY MAPPING**:
      - class_uri: schema:QuantitativeValue (numeric measurement)
      - Uses schema:interactionStatistic for behavioral metrics
      
    class_uri: schema:QuantitativeValue
    
    exact_mappings:
      - schema:QuantitativeValue
    
    close_mappings:
      - schema:interactionStatistic
    
    slots:
      - has_or_had_type
      - temporal_extent
    
    attributes:
      rate_value:
        range: float
        required: true
        description: >-
          The conversion rate as a decimal (0.35 = 35%).
          Always expressed as proportion between 0.0 and 1.0.
        minimum_value: 0.0
        maximum_value: 1.0
      
      rate_percentage:
        range: float
        description: >-
          The conversion rate as a percentage (35 = 35%).
          Calculated field: rate_value × 100.
        minimum_value: 0.0
        maximum_value: 100.0
      
      sample_size:
        range: integer
        description: >-
          The number of observations in the denominator (total visitors, emails sent, etc.).
          Required for statistical significance assessment.
      
      converted_count:
        range: integer
        description: >-
          The number of successful conversions (numerator).
          Required for statistical significance assessment.
      
      measurement_period_description:
        range: string
        description: >-
          Human-readable description of the measurement period.
          Examples: "Q1 2025", "Calendar Year 2024", "Exhibition period"
      
      benchmark_comparison:
        range: string
        description: >-
          How this rate compares to industry benchmarks.
          Examples: "Above average", "Top quartile", "Below benchmark"
      
      notes:
        range: string
        description: >-
          Additional context about this conversion rate measurement.
          Examples: Special circumstances, data collection methodology.
    
    slot_usage:
      has_or_had_type:
        range: ConversionRateType
        inlined: true
        description: >-
          The type of conversion being measured.
          Use concrete types from ConversionRateTypes (VisitorToPurchaseConversion, etc.)
        examples:
          - value: |
              has_or_had_type:
                has_or_had_label: "Visitor to Purchase"
                source_population: "museum visitors"
                target_action: "made gift shop purchase"
            description: Visitor to purchase conversion type
      
      temporal_extent:
        range: TimeSpan
        inlined: true
        description: >-
          The time period during which this conversion rate was measured.
          Use begin/end dates to specify the measurement window.
        examples:
          - value: |
              temporal_extent:
                begin_of_the_begin: "2024-01-01"
                end_of_the_end: "2024-12-31"
            description: Calendar year 2024 measurement period
    
    annotations:
      custodian_types: '["*"]'
      custodian_types_rationale: >-
        Conversion rates applicable to all custodian types with retail or engagement.
      custodian_types_primary: "*"
      specificity_score: 0.45
      specificity_rationale: >-
        Moderate specificity - relevant to custodians tracking performance metrics.
    
    examples:
      - value: |
          ConversionRate:
            rate_value: 0.35
            rate_percentage: 35.0
            sample_size: 500000
            converted_count: 175000
            has_or_had_type:
              has_or_had_label: "Visitor to Purchase"
            temporal_extent:
              begin_of_the_begin: "2024-01-01"
              end_of_the_end: "2024-12-31"
            measurement_period_description: "Calendar Year 2024"
            benchmark_comparison: "Above average (industry avg 15-25%)"
        description: Gift shop 35% visitor-to-purchase conversion rate.
      
      - value: |
          ConversionRate:
            rate_value: 0.05
            rate_percentage: 5.0
            sample_size: 100000
            converted_count: 5000
            has_or_had_type:
              has_or_had_label: "Visitor to Member"
            temporal_extent:
              begin_of_the_begin: "2024-06-01"
              end_of_the_end: "2024-08-31"
            measurement_period_description: "Summer membership drive"
            benchmark_comparison: "Strong (industry avg 1-3%)"
        description: Summer membership campaign with 5% conversion.
    
    comments:
      - Created from slot_fixes.yaml migration (2026-01-14)
      - Replaces simple float visitor_conversion_rate slot
      - Supports multiple conversion types with industry benchmarks
      - Temporal extent enables trend analysis over time