# KPIs Readme

## Purpose

The `\kpis` folder is dedicated to KPIs modelisation, which include mostly any relevant dimension and measure and time aggregation needed for transforming data into business metrics.

## Convention

### Model names

- Any model within the folder `intermediate\kpis` needs to follow this convention: `int_kpis__{structure_type}_{time_dimension}_{relevant_entity_name}`.
- Structure types can be the following:
    - `lifecycle`: any modelisation that classifies certain behavior on a given entity that can vary over time. For instance, the listing lifecycle in terms of booking creation could categorise the lifecycle of the listing based on whether a listing being new, active, never booked, inactive, etc.
    - `dimension`: any modelisation that allows to segment or categorise data, so it can provide descriptive context for the measures. Segments resulting from lifecycles would likely have an equivalent dimension model. 
    - `metric`: any model that computes a given metric per different dimensions that is not aggregated. This means that each dimension will have a dedicated column within the model.
    - `aggregated`: a model that aggregates the data into a 1) date range, 2) a dimension and 3) a dimension value for any given metric. These will always depend on metrics models. 
    
- Time dimension can be the following:
    - `daily`: if the time granularity is daily
    - `monthly`: if the time granularity is monthly, meaning metrics are aggregated to the month
    - `mtd`: if the time granularity is month-to-date, meaning metrics are cumulative to a certain date of the current month and so it's the case for the same days on the month of the previous days.
    - others.
- Relevant entitity needs to easily and uniquely identify the entity being modelled, such as Created Bookings. 
- The only exception is `int_kpis__dimension_dates`, that even though is granular at daily level, it's simplified on purpose.

### Logic 
- The model that contains the deepest granularity for each entity should be the one handling the data gathering to compute raw metrics and dimensions. Likely, this model will be in the form of `int_kpis__metric_daily_{relevant_entity_name}`. In this case, joins outside of the `kpis` folder are accepted and expected. 
- Downstream models, indistinctly of these being `metric` or `aggregated` models, should not join with other models outside of the `kpis` folder.
- Downstream models could eventually join with other models within the `kpis` folder in order to create weighted or converted metrics.