page.proto

// Copyright 2024 The Cross-Media Measurement Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package wfa.measurement.reporting.v2alpha;

import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/type/dayofweek.proto";
import "google/type/interval.proto";
import "wfa/measurement/reporting/v2alpha/reporting_common.proto";

option java_package = "org.wfanet.measurement.reporting.v2alpha";
option java_multiple_files = true;
option java_outer_classname = "PageProto";

// Defines the Frequency, Groupings, and Filters for calculating
// a set of Metrics
message CalculationSpec {
  // The frequency at which metrics are reported.
  message FrequencySpec {
    // Specifies that metrics should be calculated on a weekly basis with
    // respect to the given day of the week.
    //
    // If the day of the week is not the same as the start or end day of the
    // report partial weeks will reported for the first and/or last value
    // in the result set.
    message Weekly {
      // The day of week to use as the starting day
      google.type.DayOfWeek start_day = 1 [
        (google.api.field_behavior) = REQUIRED,
        (google.api.field_behavior) = IMMUTABLE
      ];
    }
    // Report metrics daily with respect to the hour set in the
    // reporting_interval
    bool daily = 1 [(google.api.field_behavior) = IMMUTABLE];
    // Report metrics weekly
    Weekly weekly = 2 [(google.api.field_behavior) = IMMUTABLE];
    // Report metrics across the entire reporting_interval
    bool total = 3 [(google.api.field_behavior) = IMMUTABLE];
  }
  // The reporting frequency for this page of results.
  FrequencySpec frequency = 1 [(google.api.field_behavior) = IMMUTABLE];

  // Options for specifying cumulative or non-cumulative metrics.
  enum AccumulationOptions {
    // Default value. Unused.
    ACCUMULATION_OPTIONS_UNSPECIFIED = 0;
    // Compute comulative metrics
    CUMULATIVE = 1;
    // Compute non-cumulative metrics
    NON_CUMULATIVE = 2;
  }
  // How to accumulate results.
  AccumulationOptions accumulation_options = 2 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.field_behavior) = IMMUTABLE
  ];

  // Specifies the dimensions to Group output metrics on.
  //
  // Only those event template fields that are tagged as groupable
  // and in the common template are supported.
  message Grouping {
    // A field path with respect to the Event message that indicates the
    // dimension to group by.
    //
    // For example, if there is an event tempalte field in common
    // named "age_group" then this value should be common.age_group
    repeated string event_template_field = 1 [
      (google.api.field_behavior) = REQUIRED,
      (google.api.field_behavior) = IMMUTABLE
    ];
  }
  // Metric grouping
  Grouping grouping = 3 [(google.api.field_behavior) = IMMUTABLE];

  // The set of filters to be applied to a page of results.
  //
  // Only those event templates that are specified in the "common" event
  // template may be provided as filters.
  message Filter {
    // A term in the Filter expression
    //
    // Negation may be supported in the future.
    message Term {
      // A field path with respect to the Event message that indicates the
      // dimension to apply the filter to.
      //
      // For example, if there is an event tempalte field in common
      // named "age_group" then this value should be common.age_group
      string event_template_field = 1 [
        (google.api.field_behavior) = REQUIRED,
        (google.api.field_behavior) = IMMUTABLE
      ];
      // The value of the event template to filter
      message FieldValue {
        oneof value {
          // Used when the event template field is a string or enum
          string string_value = 1 [(google.api.field_behavior) = IMMUTABLE];
        }
      }
      // The value of the event_template_field to filter on.
      FieldValue value = 2 [
        (google.api.field_behavior) = REQUIRED,
        (google.api.field_behavior) = IMMUTABLE
      ];
    }
    // The term that defines the filter criteria.
    //
    // May be extended to a disjunction of terms in the future.
    Term term = 1 [
      (google.api.field_behavior) = REQUIRED,
      (google.api.field_behavior) = IMMUTABLE
    ];
  }
  // A conjunction of filters
  repeated Filter filters = 4 [(google.api.field_behavior) = IMMUTABLE];
}

// Defines a Page of results
message PageSpec {
  // The title of the page
  string title = 1 [(google.api.field_behavior) = IMMUTABLE];

  // The unit to compute metrics for
  ReportingUnit reporting_unit = 2 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.field_behavior) = IMMUTABLE
  ];

  // Specifies the window, grouping, and filter criteria
  // to use for this page of metrics.
  CalculationSpec calculation_spec = 3 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.field_behavior) = IMMUTABLE
  ];

  // Defines a set of Metrics to be computed
  message MetricSpec {
    // If specified the total population for the specified groupings and
    // filters that are associated with calculation spec is reported.
    bool population_size = 1 [(google.api.field_behavior) = IMMUTABLE];

    // The set of basic metrics that can be computed for any aspect of the
    // Reporting Unit (e.g. the whole thing, a single component, intersections,
    // etc.)
    message BasicMetricSpec {
      // The reach
      bool reach = 1 [(google.api.field_behavior) = IMMUTABLE];

      // The reach divided by the population
      bool percent_reach = 2 [(google.api.field_behavior) = IMMUTABLE];

      // The k plus reach up to the frequency specified. Value must be
      // positive.
      int32 k_plus_reach = 3 [(google.api.field_behavior) = IMMUTABLE];

      // This option requires that a positive value be given for
      // k_plus_reach, in which case if specified the percent k+
      // reach values are also computed.
      bool percent_k_plus_reach = 4 [(google.api.field_behavior) = IMMUTABLE];

      // Compute a frequency histogram with the given max frequency
      //
      // The last bin in the historgram will contain values for
      // all requencies >= the value provided here.
      // Phase III
      int32 frequency_histogram = 5 [(google.api.field_behavior) = IMMUTABLE];

      // The average frequency
      bool average_frequency = 6 [(google.api.field_behavior) = IMMUTABLE];

      // The impression count
      bool impressions = 7 [(google.api.field_behavior) = IMMUTABLE];

      // Gross ratings points
      bool grps = 8 [(google.api.field_behavior) = IMMUTABLE];

      // The new reach of all the unit(s) for the time period compared to
      // all previous time encompassed by the reporting_interval
      //
      // For cumualtive metrics this is the same as reach
      // Phase III
      bool new_reach = 9 [(google.api.field_behavior) = IMMUTABLE];

      // The impressions associated with the new reach
      // Phase III
      bool new_reach_impressions = 10 [(google.api.field_behavior) = IMMUTABLE];
    }

    // Metrics to be computed over the entire ReportingUnit
    message ReportingUnitMetricSpec {
      // Metrics for the union of the items in the ReportingUnit
      BasicMetricSpec union = 1 [(google.api.field_behavior) = IMMUTABLE];

      // Compute a stacked incremental reach result for the ReportingUnit
      // For example if the order of the items in the ReportingUnit.units
      // field is "rs1, rs2, rs3" then the following are reported:
      // 1. The reach of rs1
      // 2. The incremental reach of (rs1+rs2) over rs1
      //    (i.e. the unique contribution of rs2 with respect to rs2)
      // 3. The incremental reach of (rs1+rs2+rs3) over (rs1+rs2)
      //    (i.e. the unique contribution of rs3 with respect to rs1 and rs2.
      bool stacked_incremental_reach = 2;
    }
    // The set of metrics to compute for the entire Reporting Unit
    ReportingUnitMetricSpec reporting_unit = 2;

    // Compute metrics that apply to each unit of the reporting_unit_spec
    // with respect to all others.
    message ComponentMetricSpec {
      // The basic metrics for each ReportingUnit.unit
      BasicMetricSpec component = 1 [(google.api.field_behavior) = IMMUTABLE];

      // Compute the unique reach of each reporting unit in the
      // reporting_unit_spec with respect to all other reporting units.
      //
      // For example if reporting_sets=[RS1, RS2, RS3] the unique reach of
      // RS1, RS2, and RS3 are computed.
      //
      // It is an error to specify this if only a single reporting unit is
      // specified since it is the same thing as requesting union.reach.
      bool unique_reach = 2 [(google.api.field_behavior) = IMMUTABLE];

      // The impressions associated with the unique reach.
      // Phase III
      bool unique_reach_impressions = 3
          [(google.api.field_behavior) = IMMUTABLE];

      // The reach that is new to the time period and unique to each
      // unit in the reporting_unit_spec
      //
      // For cumulative metrics this is the same as unique_reach.
      // Phase III
      bool new_unique_reach = 4 [(google.api.field_behavior) = IMMUTABLE];

      // The impressions associated with the new_unique_reach
      // Phase III
      bool new_unique_reach_impressions = 5
          [(google.api.field_behavior) = IMMUTABLE];
    }
    // If ReportingUnit.unit is of size 1 the metrics computed for the component
    // are identical to those computed for the union. Specifying this value is
    // not recommended in this case.
    ComponentMetricSpec component = 3 [(google.api.field_behavior) = IMMUTABLE];

    // Request overlaps (i.e. intersections) of the various combinations
    // of reporting_units
    message IntersectionMetricSpec {
      // The number of units that contribute to the intersection.
      //
      // For example, a value of 2 will provide all 2-way intersections of
      // the reporting_unit_spec. A value of 2 and 3 will provide both the
      // 2 and 3 way intersections.
      //
      // Note that a value of 1 is not allowed. Set unique_reach
      // instead.
      //
      // The max value is the number of distrinct reporting
      // units in the reporting_unit_spec.
      repeated int32 contributor_count = 1 [
        (google.api.field_behavior) = IMMUTABLE,
        (google.api.field_behavior) = REQUIRED
      ];

      // The set of metrics to be computed for each intersection
      BasicMetricSpec basic = 2 [
        (google.api.field_behavior) = IMMUTABLE,
        (google.api.field_behavior) = REQUIRED
      ];
    }
    // Compute n-way intersections
    IntersectionMetricSpec intersection = 4
        [(google.api.field_behavior) = IMMUTABLE];
  }

  // Specifies the Metrics to compute.
  MetricSpec metric_spec = 4 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.field_behavior) = IMMUTABLE
  ];
}

// A page of results. This should be interpretable without any knowledge of
// the page definitions
message Page {
  // The title of the page.
  string title = 1 [(google.api.field_behavior) = IMMUTABLE];

  // The metadata associated with a particular result.
  message ResultMetadata {
    // A summary of the Page Spec Reporting Unit or subset of it for which the
    // Result was computed.
    message ReportingUnitSummary {
      // The reporting unit associated with the result.
      ReportingUnit reporting_unit = 1
          [(google.api.field_behavior) = IMMUTABLE];
      // Summaries a Event Group
      //
      // TODO(@kungfucraig): Include a copy of the EventGroup metadata
      // structure here once it's ready.
      message EventGroupSummary {
        // The resource name of the Event Group
        string event_group = 1 [
          (google.api.resource_reference) = {
            type: "reporting.halo-cmm.org/EventGroup"
          },
          (google.api.field_behavior) = IMMUTABLE
        ];
      }
      // A map of each resoucrce name in the reporting_unit to the
      // Event Groups Summary associated with it.
      // Phase II
      map<string, EventGroupSummary> event_group_summaries = 3
          [(google.api.field_behavior) = IMMUTABLE];
    }
    // A summary of the ReportingUnit
    ReportingUnitSummary reporting_unit_summary = 1
        [(google.api.field_behavior) = IMMUTABLE];

    // The time interval over which the result is computed.
    google.type.Interval time_interval = 2
        [(google.api.field_behavior) = IMMUTABLE];

    // Specifies the calculation spec used for these results.
    // Phase II - discuss
    CalculationSpec calculation_spec = 3
        [(google.api.field_behavior) = IMMUTABLE];

    // The qualification filter used when computing the result.
    ReportingImpressionQualificationFilter impression_qualification_filter = 4
        [(google.api.field_behavior) = IMMUTABLE];
  }

  // The value of a result.
  message ResultValue {
    // The size of the population for the filters/grouping specified
    int32 population_size = 9 [(google.api.field_behavior) = IMMUTABLE];

    // The result when the page selector is metric_type
    message MetricResult {
      // Captures results that are applicable to any subunit of the
      // Reporting Unit.
      message BasicMetricResult {
        // The reach
        int32 reach = 1 [(google.api.field_behavior) = IMMUTABLE];
        // The reach divided by the population_size
        float percent_reach = 2 [(google.api.field_behavior) = IMMUTABLE];
        // The k+ reach where the index is frequency - 1.
        repeated int32 k_plus_reach = 3
            [(google.api.field_behavior) = IMMUTABLE];
        // The perecent k+ reach
        repeated float percent_k_plus_reach = 4
            [(google.api.field_behavior) = IMMUTABLE];
        // The frequency historam where the index is frequency-1
        repeated float frequency_histogram = 5
            [(google.api.field_behavior) = IMMUTABLE];
        // The average frequency
        float average_frequency = 6 [(google.api.field_behavior) = IMMUTABLE];
        // The impression count
        int32 impressions = 7 [(google.api.field_behavior) = IMMUTABLE];
        // The gross ratings points
        float grps = 8 [(google.api.field_behavior) = IMMUTABLE];
        // The new reach
        int32 new_reach = 9 [(google.api.field_behavior) = IMMUTABLE];
        // The impressions associated with the new reach
        int32 new_reach_impressions = 10
            [(google.api.field_behavior) = IMMUTABLE];
      }
      // Stores the results for the entire Teporting Unit.
      message ReportingUnitResult {
        // The metrics for the union of the units
        BasicMetricResult union = 1 [(google.api.field_behavior) = IMMUTABLE];

        // The stacked incremental reach of the Reporting Unit.
        //
        // For example if the units in the ReportingUnit were "rs1", "rs2",
        // "rs3" then the values in this array are as follows:
        //  1. reach(rs1)
        //  2. reach(rs1+rs2) - reach(rs1)
        //  3. reach(rs1+rs2+rs3) - reach(rs1+rs2)
        repeated int32 stacked_incremental_reach = 2;
      }
      // The results for the whole Reporting Unit
      ReportingUnitResult reporting_unit = 1;

      // Stores the results for a single component of the Reporting Unit.
      message ComponentMetricResult {
        // The basic metrics for this component, which would be either for a
        // single component if the reporting_unit_spec has one item or for the
        // union of all components if it has more than one item.
        BasicMetricResult component = 1
            [(google.api.field_behavior) = IMMUTABLE];

        // The unique reach
        int32 unique_rech = 2 [(google.api.field_behavior) = IMMUTABLE];

        // The count of impressions associated with the unique reach
        // Phase III
        int32 unique_reach_impressions = 3
            [(google.api.field_behavior) = IMMUTABLE];

        // The new unique reach
        int32 new_unique_reach = 4 [(google.api.field_behavior) = IMMUTABLE];

        // The count of impressions associated with the new unique reach
        int32 new_unique_reach_impressions = 5
            [(google.api.field_behavior) = IMMUTABLE];
      }
      // The results for each unit in the reporting_unit
      map<string, ComponentMetricResult> components = 2
          [(google.api.field_behavior) = IMMUTABLE];

      // Stores results for the intersection of the components of the
      // Reporting Unit
      message IntersectionResult {
        // The reporting unit components that this overlap corresponds to.
        repeated string components = 1
            [(google.api.field_behavior) = IMMUTABLE];
        // Results for the intersection of the components
        BasicMetricResult metrics = 2 [(google.api.field_behavior) = IMMUTABLE];
      }
      // The results for the requested intersections
      // Phase III
      repeated IntersectionResult intersection = 3
          [(google.api.field_behavior) = IMMUTABLE];
    }
  }

  // A single result and its metadata.
  message Result {
    // The result metadata
    ResultMetadata metadata = 1 [(google.api.field_behavior) = IMMUTABLE];
    // The result value
    ResultValue value = 2 [(google.api.field_behavior) = IMMUTABLE];
  }
  // The result for the page. There is one result per applicable qualification
  // filter.
  repeated Result results = 2 [(google.api.field_behavior) = IMMUTABLE];
}