decidim-stratified_sortitions 0.0.1

data/app/services/decidim/stratified_sortitions/leximin/panel_generator.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    module Leximin
+      # Generates feasible panels using Integer Linear Programming (ILP).
+      #
+      # Uses the COIN-OR CBC solver to find panels that satisfy:
+      # - Exactly k volunteers selected (panel size)
+      # - Quota constraints for each category (min/max)
+      #
+      # For column generation, it can also find panels that improve the
+      # current LEXIMIN objective using dual prices.
+      #
+      class PanelGenerator
+        class CbcNotAvailableError < StandardError; end
+
+        def initialize(constraint_builder)
+          @cb = constraint_builder
+          require_cbc!
+        end
+
+        private
+
+        def require_cbc!
+          require "ruby-cbc"
+        rescue LoadError
+          raise CbcNotAvailableError,
+                "The CBC solver is required for LEXIMIN selection. " \
+                "Install the gem with: bundle add ruby-cbc\n" \
+                "And system libraries: sudo apt install coinor-cbc coinor-libcbc-dev"
+        end
+
+        public
+
+        # Find any feasible panel satisfying all constraints
+        #
+        # @return [Array<Integer>, nil] Array of volunteer IDs or nil if infeasible
+        def find_feasible_panel
+          solve_panel_ilp(nil)
+        end
+
+        # Find a panel that improves the LEXIMIN objective
+        #
+        # Uses dual prices from the master problem to find a panel with
+        # positive reduced cost (improving the objective).
+        #
+        # @param dual_prices [Hash{Integer => Float}] dual prices for each volunteer
+        # @return [Array<Integer>, nil] Array of volunteer IDs or nil if no improving panel
+        def find_improving_panel(dual_prices)
+          return find_feasible_panel if dual_prices.blank?
+
+          solve_panel_ilp(dual_prices)
+        end
+
+        private
+
+        # Solve the panel selection ILP
+        #
+        # Variables: x_i ∈ {0,1} for each volunteer i
+        #
+        # Constraints:
+        #   ∑_i x_i = k (panel size)
+        #   ℓ_j ≤ ∑_{i ∈ C_j} x_i ≤ u_j for each category j
+        #
+        # Objective:
+        #   - If dual_prices nil: any feasible solution (maximize constant)
+        #   - If dual_prices given: maximize ∑_i π_i * x_i (reduced cost)
+        #
+        # @param dual_prices [Hash, nil]
+        # @return [Array<Integer>, nil]
+        def solve_panel_ilp(dual_prices) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+          return nil if @cb.num_volunteers.zero?
+
+          model = Cbc::Model.new
+
+          # Create binary variables for each volunteer
+          x = @cb.volunteer_ids.map do |vid|
+            model.bin_var(name: "x_#{vid}")
+          end
+
+          # Constraint: exactly k volunteers selected
+          model.enforce(sum_vars(x) == @cb.panel_size)
+
+          # Quota constraints for each category
+          @cb.category_ids.each do |cat_id|
+            quota = @cb.quotas[cat_id]
+            volunteers_in_cat = @cb.category_volunteers[cat_id]
+
+            next if volunteers_in_cat.empty?
+
+            # Sum of x_i for volunteers in this category
+            cat_vars = volunteers_in_cat.map do |vid|
+              idx = @cb.volunteer_index(vid)
+              x[idx]
+            end.compact
+
+            next if cat_vars.empty?
+
+            cat_sum = sum_vars(cat_vars)
+
+            # min <= sum <= max
+            model.enforce(cat_sum >= quota[:min]) if (quota[:min]).positive?
+            model.enforce(cat_sum <= quota[:max]) if quota[:max] < @cb.panel_size
+          end
+
+          # Objective function
+          if dual_prices.blank?
+            # Just find any feasible solution - maximize sum (constant effect)
+            model.maximize(sum_vars(x))
+          else
+            # Maximize reduced cost: ∑_i π_i * x_i
+            objective_terms = @cb.volunteer_ids.map.with_index do |vid, idx|
+              price = dual_prices[vid] || 0.0
+              x[idx] * price
+            end
+            model.maximize(sum_vars(objective_terms))
+          end
+
+          # Solve
+          problem = model.to_problem
+          problem.solve
+
+          return nil unless problem.proven_optimal?
+
+          # Check if reduced cost is positive (improving)
+          if dual_prices.present?
+            obj_value = problem.objective_value
+            return nil if obj_value <= LeximinSelector::CONVERGENCE_THRESHOLD
+          end
+
+          # Extract selected volunteer IDs
+          selected = []
+          @cb.volunteer_ids.each_with_index do |vid, idx|
+            selected << vid if problem.value_of(x[idx]) > 0.5
+          end
+
+          selected.empty? ? nil : selected
+        end
+
+        def sum_vars(vars)
+          return 0 if vars.empty?
+
+          vars.reduce(:+)
+        end
+      end
+    end
+  end
+end

data/app/services/decidim/stratified_sortitions/leximin/panel_sampler.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    module Leximin
+      # Samples a single panel from the LEXIMIN distribution.
+      #
+      # Given a set of panels and their probabilities (from LeximinSelector),
+      # this service selects one panel according to the probability distribution.
+      #
+      # The sampling is cryptographically secure using SecureRandom.
+      #
+      # @example
+      #   leximin_result = LeximinSelector.new(stratified_sortition).call
+      #   sampler = PanelSampler.new(leximin_result.panels, leximin_result.probabilities)
+      #   selected_panel = sampler.sample
+      #   # => [participant_id_1, participant_id_2, ...]
+      #
+      class PanelSampler
+        # Result object for sampling operation
+        Result = Struct.new(:selected_panel, :selected_index, :random_value, :success, :error, keyword_init: true) do
+          def success?
+            success
+          end
+        end
+
+        def initialize(panels, probabilities, random_seed: nil)
+          @panels = panels
+          @probabilities = normalize_probabilities(probabilities)
+          @random_seed = random_seed
+        end
+
+        # Sample a panel according to the probability distribution
+        #
+        # @return [Result] containing the selected panel and metadata
+        def sample
+          return error_result("No hi ha panels disponibles per mostrejar") if @panels.empty?
+          return error_result("Les probabilitats no coincideixen amb el nombre de panels") if @panels.size != @probabilities.size
+
+          # Generate random value in [0, 1)
+          random_value = generate_random_value
+
+          # Select panel using cumulative distribution
+          selected_index = select_panel_index(random_value)
+
+          Result.new(
+            selected_panel: @panels[selected_index],
+            selected_index:,
+            random_value:,
+            success: true,
+            error: nil
+          )
+        rescue StandardError => e
+          error_result("Error en el mostreig: #{e.message}")
+        end
+
+        # Sample multiple panels (with replacement)
+        #
+        # @param count [Integer] number of panels to sample
+        # @return [Array<Result>] array of sampling results
+        def sample_multiple(count)
+          Array.new(count) { sample }
+        end
+
+        # Get the cumulative distribution function
+        #
+        # @return [Array<Float>] cumulative probabilities
+        def cumulative_distribution
+          cumsum = 0.0
+          @probabilities.map { |p| cumsum += p }
+        end
+
+        private
+
+        def normalize_probabilities(probs)
+          return [] if probs.blank?
+
+          total = probs.sum.to_f
+          return probs if (total - 1.0).abs < 1e-9
+
+          # Normalize to sum to 1
+          if total.positive?
+            probs.map { |p| p / total }
+          else
+            # Uniform distribution if all zeros
+            uniform = 1.0 / probs.size
+            Array.new(probs.size, uniform)
+          end
+        end
+
+        def generate_random_value
+          if @random_seed
+            # Deterministic for testing
+            Random.new(@random_seed).rand
+          else
+            # Cryptographically secure random
+            SecureRandom.random_number
+          end
+        end
+
+        def select_panel_index(random_value)
+          cumsum = 0.0
+
+          @probabilities.each_with_index do |prob, idx|
+            cumsum += prob
+            return idx if random_value < cumsum
+          end
+
+          # Edge case: return last panel (handles floating point errors)
+          @panels.size - 1
+        end
+
+        def error_result(message)
+          Result.new(
+            selected_panel: [],
+            selected_index: nil,
+            random_value: nil,
+            success: false,
+            error: message
+          )
+        end
+      end
+    end
+  end
+end

data/app/services/decidim/stratified_sortitions/leximin_selector.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Decidim
+  module StratifiedSortitions
+    # LEXIMIN Selector Service
+    #
+    # Implements the LEXIMIN fair selection algorithm using column generation.
+    # Based on "Fair algorithms for selecting citizens' assemblies" paper.
+    #
+    # The algorithm finds an optimal portfolio of panels (feasible selections)
+    # and computes a probability distribution over them that maximizes fairness
+    # in selection probabilities using the leximin criterion.
+    #
+    # @example
+    #   result = LeximinSelector.new(stratified_sortition).call
+    #   if result.success?
+    #     result.panels        # Array of panels (each panel is array of participant IDs)
+    #     result.probabilities # Probability for each panel
+    #   else
+    #     result.error         # Error message
+    #   end
+    #
+    class LeximinSelector
+      # Maximum number of column generation iterations
+      MAX_ITERATIONS = 1000
+
+      # Convergence threshold for reduced cost
+      CONVERGENCE_THRESHOLD = 1e-6
+
+      # Result object returned by the algorithm
+      Result = Struct.new(:panels, :probabilities, :selection_probabilities, :iterations, :converged, :success, :error, keyword_init: true) do
+        def success?
+          success
+        end
+      end
+
+      def initialize(stratified_sortition)
+        @stratified_sortition = stratified_sortition
+        @constraint_builder = Leximin::ConstraintBuilder.new(stratified_sortition)
+      end
+
+      # Execute the LEXIMIN algorithm
+      #
+      # @return [Result] containing panels, probabilities, and success status
+      def call
+        # Step 1: Check feasibility
+        feasibility = Leximin::FeasibilityChecker.new(@constraint_builder).check
+        unless feasibility[:feasible]
+          return Result.new(
+            panels: [],
+            probabilities: [],
+            selection_probabilities: {},
+            success: false,
+            error: feasibility[:errors].join("; ")
+          )
+        end
+
+        # Step 2: Initialize with one feasible panel
+        panel_generator = Leximin::PanelGenerator.new(@constraint_builder)
+        initial_panel = panel_generator.find_feasible_panel
+        return infeasible_result(I18n.t("decidim.stratified_sortitions.errors.leximin.no_feasible_panel")) if initial_panel.nil?
+
+        panels = [initial_panel]
+
+        # Step 3: Column generation loop
+        distribution_solver = Leximin::DistributionSolver.new(@constraint_builder)
+
+        MAX_ITERATIONS.times do
+          # Compute optimal distribution over current panels
+          distribution = distribution_solver.compute(panels)
+
+          # Try to find a new panel that improves the objective
+          new_panel = panel_generator.find_improving_panel(distribution[:dual_prices])
+
+          # Check convergence: no improving panel found
+          break if new_panel.nil? || panels_include?(panels, new_panel)
+
+          panels << new_panel
+        end
+
+        # Step 4: Compute final distribution
+        final_distribution = distribution_solver.compute(panels)
+
+        # Step 5: Compute selection probabilities for each volunteer
+        selection_probs = compute_selection_probabilities(panels, final_distribution[:probabilities])
+
+        Result.new(
+          panels:,
+          probabilities: final_distribution[:probabilities],
+          selection_probabilities: selection_probs,
+          success: true,
+          error: nil
+        )
+      rescue StandardError => e
+        Rails.logger.debug { "LEXIMIN Selector error: #{e.message}\n#{e.backtrace.join("\n")}" }
+        Result.new(
+          panels: [],
+          probabilities: [],
+          selection_probabilities: {},
+          success: false,
+          error: I18n.t("decidim.stratified_sortitions.errors.leximin.internal_error", error: e.message)
+        )
+      end
+
+      private
+
+      def infeasible_result(message)
+        Result.new(
+          panels: [],
+          probabilities: [],
+          selection_probabilities: {},
+          success: false,
+          error: message
+        )
+      end
+
+      def panels_include?(panels, new_panel)
+        new_panel_set = Set.new(new_panel)
+        panels.any? { |p| Set.new(p) == new_panel_set }
+      end
+
+      def compute_selection_probabilities(panels, probabilities)
+        selection_probs = Hash.new(0.0)
+
+        panels.each_with_index do |panel, idx|
+          prob = probabilities[idx] || 0.0
+          panel.each do |volunteer_id|
+            selection_probs[volunteer_id] += prob
+          end
+        end
+
+        selection_probs
+      end
+    end
+  end
+end

data/app/services/decidim/stratified_sortitions/sortition_results_exporter.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "csv"
+require "rubyXL"
+require "rubyXL/convenience_methods/cell"
+require "rubyXL/convenience_methods/font"
+require "rubyXL/convenience_methods/workbook"
+require "rubyXL/convenience_methods/worksheet"
+
+module Decidim
+  module StratifiedSortitions
+    # Custom exporter for sortition results that produces a layout with:
+    #   Row 1: Metadata headers
+    #   Row 2: Metadata values
+    #   Row 3: Blank
+    #   Row 4: Participant headers
+    #   Row 5+: Participant data
+    class SortitionResultsExporter
+      def initialize(stratified_sortition)
+        @stratified_sortition = stratified_sortition
+        @portfolio = stratified_sortition.panel_portfolio
+        @audit_log = @portfolio.audit_log
+        @strata = stratified_sortition.strata.order(:position)
+        @participants = SampleParticipant
+                        .where(id: @portfolio.selected_panel)
+                        .includes(sample_participant_strata: [:decidim_stratified_sortitions_stratum, :decidim_stratified_sortitions_substratum])
+                        .order(:id)
+        @total_participants = stratified_sortition.sample_participants.count
+      end
+
+      def export_csv(col_sep = Decidim.default_csv_col_sep)
+        data = ::CSV.generate(col_sep:) do |csv|
+          csv << metadata_headers
+          csv << metadata_values
+          csv << [] # blank row
+          csv << participant_headers
+          @participants.each { |p| csv << participant_row(p) }
+        end
+        Decidim::Exporters::ExportData.new(data, "csv")
+      end
+
+      def export_excel
+        workbook = RubyXL::Workbook.new
+        worksheet = workbook[0]
+
+        # Row 0: metadata headers
+        metadata_headers.each_with_index do |header, col|
+          worksheet.add_cell(0, col, header)
+          worksheet.change_column_width(col, 20)
+        end
+        style_header_row(worksheet, 0, metadata_headers.size)
+
+        # Row 1: metadata values
+        metadata_values.each_with_index { |val, col| worksheet.add_cell(1, col, val) }
+
+        # Row 2: blank
+        # Row 3: participant headers
+        participant_headers.each_with_index do |header, col|
+          worksheet.add_cell(3, col, header)
+          current_width = worksheet.get_column_width(col)
+          worksheet.change_column_width(col, 20) if current_width.nil? || current_width < 20
+        end
+        style_header_row(worksheet, 3, participant_headers.size)
+
+        # Row 4+: participant data
+        @participants.each_with_index do |participant, idx|
+          participant_row(participant).each_with_index do |val, col|
+            worksheet.add_cell(4 + idx, col, val)
+          end
+        end
+
+        Decidim::Exporters::ExportData.new(workbook.stream.string, "xlsx")
+      end
+
+      def export_json
+        data = {
+          metadata: metadata_headers.zip(metadata_values).to_h,
+          participants: @participants.map do |p|
+            participant_headers.zip(participant_row(p)).to_h
+          end,
+        }
+        Decidim::Exporters::ExportData.new(JSON.pretty_generate(data), "json")
+      end
+
+      private
+
+      def i18n_scope
+        "decidim.stratified_sortitions.admin.stratified_sortitions.execute"
+      end
+
+      def metadata_headers
+        @metadata_headers ||= [
+          I18n.t("algorithm", scope: i18n_scope),
+          I18n.t("total_participants", scope: i18n_scope),
+          I18n.t("generated_at", scope: i18n_scope),
+          I18n.t("generation_time", scope: i18n_scope),
+          I18n.t("num_panels", scope: i18n_scope),
+          I18n.t("selected_at", scope: i18n_scope),
+          I18n.t("random_value_used", scope: i18n_scope),
+          I18n.t("selected_panel_probability", scope: i18n_scope),
+        ]
+      end
+
+      def metadata_values
+        @metadata_values ||= [
+          "#{@audit_log[:algorithm]} v#{@audit_log[:version]}",
+          @total_participants,
+          @portfolio.generated_at,
+          @portfolio.generation_time_seconds,
+          @portfolio.num_panels,
+          @portfolio.selected_at,
+          @portfolio.random_value_used,
+          format_percentage(@portfolio.selected_panel_probability),
+        ]
+      end
+
+      def participant_headers
+        @participant_headers ||= begin
+          template_scope = "decidim.stratified_sortitions.admin.samples.template"
+          headers = [
+            I18n.t("personal_data_1", scope: template_scope),
+            I18n.t("personal_data_2", scope: template_scope),
+            I18n.t("personal_data_3", scope: template_scope),
+            I18n.t("personal_data_4", scope: template_scope),
+          ]
+          @strata.each do |stratum|
+            stratum_name = stratum.name.values.compact.first || stratum.id.to_s
+            headers << stratum_name
+          end
+          headers
+        end
+      end
+
+      def participant_row(participant)
+        row = [
+          participant.personal_data_1,
+          participant.personal_data_2,
+          participant.personal_data_3,
+          participant.personal_data_4,
+        ]
+        @strata.each do |stratum|
+          ps = participant.sample_participant_strata.find { |s| s.decidim_stratified_sortitions_stratum_id == stratum.id }
+          substratum_name = ps&.decidim_stratified_sortitions_substratum&.name&.values&.compact&.first
+          row << (substratum_name || "-")
+        end
+        row
+      end
+
+      def style_header_row(worksheet, row_index, _col_count)
+        worksheet.change_row_fill(row_index, "c0c0c0")
+        worksheet.change_row_bold(row_index, true)
+        worksheet.change_row_horizontal_alignment(row_index, "center")
+      end
+
+      def format_percentage(value)
+        pct = value.to_f * 100
+        "#{format("%.2f", pct)}%"
+      end
+    end
+  end
+end

data/app/views/decidim/admin/components/index.html.erb

@@ -0,0 +1,54 @@
+<% add_decidim_page_title(t("components.title", scope: "decidim.admin")) %>
+<%
+  allowed_emails = ENV.fetch("STRATIFIED_SORTITIONS_ALLOWED_EMAILS", "").split(",").map { |email| email.strip.downcase }.reject(&:blank?)
+  can_see_stratified_sortitions = allowed_emails.include?(current_user&.email.to_s.strip.downcase)
+  @components = if can_see_stratified_sortitions
+                         @components
+                       else
+                         @components.reject { |component| component.manifest_name.to_s == "stratified_sortitions" }
+                       end
+%>
+
+<div class="card">
+  <div class="item_show__header">
+    <h1 class="item_show__header-title">
+      <%= t("components.title", scope: "decidim.admin") %>
+
+      <% if allowed_to?(:create, :component) %>
+      <div class="relative">
+        <button class="button button__sm button__secondary button--title" data-toggle="add-component-dropdown">
+          <%= t "components.index.add", scope: "decidim.admin" %>
+          <%= icon "arrow-down-s-line", class: "dropdown-filter-icon" %>
+        </button>
+        <div class="dropdown-pane" id="add-component-dropdown" data-dropdown data-auto-focus="true" data-close-on-click="true">
+          <ul class="vertical menu add-components font-normal">
+            <% @manifests.each do |manifest| %>
+              <% next if manifest.name.to_s == "stratified_sortitions" && !can_see_stratified_sortitions %>
+              <li>
+                <%= link_to new_component_path(type: manifest.name), class: manifest.name do %>
+                  <%= t("#{manifest.name}.name", scope: "decidim.components") %>
+                <% end %>
+              </li>
+            <% end %>
+          </ul>
+        </div>
+      </div>
+      <% end %>
+    </h1>
+  </div>
+
+  <div class="table-scroll">
+    <table class="table-list">
+      <thead>
+        <th><%= t(".headers.name") %></th>
+        <th><%= t(".headers.type") %></th>
+        <th><%= t(".headers.scope") %></th>
+        <th><%= t(".headers.actions") %></th>
+      </thead>
+
+      <tbody>
+        <%= render partial: "component", collection: @components %>
+      </tbody>
+    </table>
+  </div>
+</div>

data/app/views/decidim/stratified_sortitions/admin/import_mailer/import.html.erb

@@ -0,0 +1,22 @@
+<p class="email-instructions">
+  <%= t(".ready") %>
+</p>
+<p class="email-instructions">
+  <ul>
+    <li><strong><%= t(".total_rows") %>:</strong> <%= @sample_import.total_rows %></li>
+    <li><strong><%= t(".imported_rows") %>:</strong> <%= @sample_import.imported_rows %></li>
+    <li><strong><%= t(".failed_rows") %>:</strong> <%= @sample_import.failed_rows %></li>
+  </ul>
+
+  <% if @sample_import.failed_rows.positive? %>
+    <br>
+    <strong><%= t(".see_details") %></strong>
+    <ul>
+      <% @sample_import.import_errors.each do |error| %>
+        <li>
+          <strong><%= t(".participant_id") %> <%= error["row"].values.first %></strong>
+        </li>
+      <% end %>
+    </ul>
+  <% end %>
+</p>

data/app/views/decidim/stratified_sortitions/admin/stratified_sortitions/_confirm_execute_modal.html.erb

@@ -0,0 +1,19 @@
+<%= decidim_modal id: "confirm-execute-modal" do %>
+  <div data-dialog-container>
+    <h2 id="dialog-title-confirm-execute-modal" tabindex="-1" data-dialog-title>
+      <%= t("decidim.stratified_sortitions.admin.stratified_sortitions.execute.confirm_execute_title") %>
+    </h2>
+    <div>
+      <p id="dialog-desc-confirm-execute-modal"><%= t("decidim.stratified_sortitions.admin.stratified_sortitions.execute.confirm_execute_body") %></p>
+    </div>
+  </div>
+  <div data-dialog-actions class="flex flex-col-reverse md:flex-row">
+    <button class="button button__lg button__transparent-secondary w-full md:w-auto" data-dialog-close="confirm-execute-modal">
+      <span><%= t("decidim.stratified_sortitions.admin.stratified_sortitions.execute.confirm_execute_cancel") %></span>
+    </button>
+    <%= button_to t("decidim.stratified_sortitions.admin.stratified_sortitions.execute.confirm_execute_ok"),
+                  execute_stratified_sortition_stratified_sortition_path(stratified_sortition),
+                  method: :post,
+                  class: "button button__lg button__secondary w-full md:w-auto" %>
+  </div>
+<% end %>

data/app/views/decidim/stratified_sortitions/admin/stratified_sortitions/_confirm_participants_modal.html.erb

@@ -0,0 +1,20 @@
+<%= decidim_modal id: "confirm-participants-modal" do %>
+  <div data-dialog-container>
+    <h2 id="dialog-title-confirm-participants-modal" tabindex="-1" data-dialog-title>
+      <%= t("decidim.stratified_sortitions.admin.stratified_sortitions.execute.confirm_participants_title") %>
+    </h2>
+    <div>
+      <p id="dialog-desc-confirm-participants-modal"><%= t("decidim.stratified_sortitions.admin.stratified_sortitions.execute.confirm_participants_body") %></p>
+    </div>
+  </div>
+  <div data-dialog-actions class="flex flex-col-reverse md:flex-row">
+    <button class="button button__lg button__transparent-secondary w-full md:w-auto" data-dialog-close="confirm-participants-modal">
+      <span><%= t("decidim.stratified_sortitions.admin.stratified_sortitions.execute.confirm_participants_cancel") %></span>
+    </button>
+    <button type="button" class="button button__lg button__secondary w-full md:w-auto" id="confirm-show-participants"
+            data-log-url="<%= log_view_participants_stratified_sortition_path(stratified_sortition) %>"
+            data-authenticity-token="<%= form_authenticity_token %>">
+      <span><%= t("decidim.stratified_sortitions.admin.stratified_sortitions.execute.confirm_participants_ok") %></span>
+    </button>
+  </div>
+<% end %>