# Metrics

Metrics calculations must be executed everyday. Some `rake task` have been added to perform it.

- To execute all metrics at once. Related to previous date from *today*

  ```ruby
  bundle exec rake decidim:metrics:all
  ```

- To execute an specific metric. Related to previous date from *today*

  ```ruby
  bundle exec rake decidim:metrics:one["<metric name>"]
  ```

- To execute metrics for a given date (all or an specific one)

  ```ruby
  bundle exec rake decidim:metrics:all["YYYY-MM-DD"]
  bundle exec rake decidim:metrics:one["<metric name>","YYYY-MM-DD"]
  ```

- It is possible to rebuild one or all metrics since some specific day. This is useful in case current metrics are no generated or corrupt. **Depending on the size of the database this can take a long time!**. The command will execute the same calculations as the commands above for **each** day between *today* and the date specified.

- To rebuild metrics since a given date (all or an specific one)

  ```ruby
  bundle exec rake decidim:metrics:rebuild["YYYY-MM-DD"]
  bundle exec rake decidim:metrics:rebuild["<metric name>","YYYY-MM-DD"]
  ```

## Available metrics

- Use the command `decidim:metrics:list` to list all available metrics using the console:

```ruby
bundle exec rake decidim:metrics:list
```

Currently, available metrics are:

- **users**, created `Users`
- **proposals**, published, not withdrawn and not *hidden* `Proposals`
- **accepted_proposals**, accepted `Proposals`
- **supports**, supports given to `Proposals`
- **assemblies**, published `Assemblies`
- **participatory_processes**, published `ParticipatoryProcesses`
- **results**, `Results` in `Accountability`
- **comments**, `Comments` generated by users, related to public elements and not *hidden*
- **meetings**, public `Meetings`

Only available for `ParticipatorySpaces` (restricted to `ParticipatoryProcesses`)

- **participants**, unique users who make at least one of the following actions:
  - Answer a survey
  - Create a debate
  - Create a proposal
  - Endorse a proposal
  - Leave a comment
  - Support a proposal
  - Vote a participatory budgeting project
- **followers**, unique users who follow any participatory element in a `ParticipatorySpace`
- **endorsements**, number of `Endorsements` in `Proposals`, within a `ParticipatorySpace`
- **debates**, number of `Debates` within a `ParticipatorySpace`
- **survey_answers**, number of answered `Surveys` by users within a `ParticipatorySpace`

## Configuration

- A **crontab** line must be added to your server to maintain them updated daily. You could use [Whenever](https://github.com/javan/whenever) to manage it directly from the APP. You probably want to schedule a `bundle exec rake decidim:metrics:all` every night.
- An **ActiveJob** queue, like [Sidekiq](https://github.com/mperham/sidekiq) or [DelayedJob](https://github.com/collectiveidea/delayed_job/)

## Persistence

The metrics module percomutes calculations and persists them into
`decidim_metrics` database table. So this module only uses one single table to
persist metrics from all times and types.

The `decidim_metrics` table has the following fields:

- `day`: the day for which the metric has been computed.
- `metric_type`: the type of the metric. One of: users, proposals, accepted_proposals, supports, assemblies.
- `cumulative`: quantity accumulated to day ”day”.
- `quantity`:  quantity for the current day, ”day”.
- `decidim_organization_id`: the FK to the organization to which this Metric belongs to.
- `participatory_space_type` + `participatory_space_id`: the FK to the participatory space to which this Metric belongs to, if any.
- `related_object_type` + `related_object_id`: the FK to the object to which this Metric belongs to, if any.
- `decidim_category_id`: the FK to the category for this Metric, if any.

Relations around `decidim_metrics` table:

```ascii
                                                    +------------------------+
+--------------+                                    | ParticipatoryProcesses |
| Organization |                               +----+------------------------+
+------+-------+                               |
       |            +--------------------+     |    +------------+
       |            |                    |     +----+ Assemblies |
       |     +----->+ ParticipatorySpace +<----+    +------------+
       |     |      |                    |     |    +-------------+
       |     |      +--------------------+     +----+ Initiatives |
       |     |                                 |    +-------------+
       |     |                                 |
       |     |                                 |    +---------------+
 +-----+-------+---+                           +----+ Consultations |
 |                 |                                +---------------+
 | decidim_metrics |
 |                 |
 +--------+--------+       +----------------+
          |                | related_object |
          +--------------->+                |
                           | [polymorphic]  |
                           +----------------+
```