DPL-916 PBMC Donor Pooling create plate

app/models/labware_creators/donor_pooling_plate.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+module LabwareCreators
+  # This labware creator receives barcodes for a configured number of source
+  # plates from the user. It pools samples from the passed wells into a
+  # destination plate. It's used for scRNA Donor Pooling to create 'LRC PBMC
+  # Pools' plates from 'LRC PBMC Defrost PBS' plates.
+  #
+  # The creator imposes restrictions:
+  # - It doesn't allow combining samples from different studies or projects.
+  # - It doesn't allow samples with the same donor_id in the same pool.
+  #
+  # The number of pools is determined by a lookup table based on sample count.
+  # Tag depth index is added to aliquot attributes to avoid tag clashes.
+  class DonorPoolingPlate < Base
+    include LabwareCreators::CustomPage
+    include SupportParent::PlateOnly
+
+    # The name of the template that will be used for rendering the barcode
+    # input page.
+    self.page = 'donor_pooling_plate'
+
+    # Add the :barcodes attribute to the list of attributes for this class.
+    # The :barcodes attribute is initialized as an empty array.
+    self.attributes += [{ barcodes: [] }]
+
+    # Define related objects to be included when retrieving source plates using
+    # the Sequencescape::API::V2.Plate.find_all method. The 'includes' argument
+    # of the method is expected to be an array of strings.
+    SOURCE_PLATE_INCLUDES = %w[
+      purpose
+      wells.aliquots.study
+      wells.aliquots.project
+      wells.aliquots.request
+      wells.aliquots.sample.sample_metadata
+      wells.requests_as_source
+    ].freeze
+
+    # The default number of pools to be created if the count is not found in
+    # the lookup table. For scRNA Donor Pooling, until a new CSV file is
+    # provided, a copy of Cardinal pooling config is used, which goes up to 96
+    # samples. From 97 to 160 samples, the number of pools to create is 16.
+    DEFAULT_NUMBER_OF_POOLS = 16
+
+    # Returns the number of source plates from the purpose configuration.
+    #
+    # @return [Integer] The number of source plates.
+    def number_of_source_plates
+      @number_of_source_plates ||= purpose_config.dig(:creator_class, :args, :number_of_source_plates)
+    end
+
+    # Returns the WellFilter instance associated with this creator. The filter
+    # uses the callback method 'labware_wells' to get the list of wells to
+    # filter, which specifies wells in 'passed' state from the source plates.
+    # The 'source_wells_for_pooling' method is used to get the filtered wells.
+    #
+    # @return [WellFilter] The WellFilter instance.
+    def well_filter
+      @well_filter ||= WellFilter.new(creator: self)
+    end
+
+    # Reurns all passed wells from the source plates in column order.
+    #
+    # @return [Array<Well>] An array of passed wells.
+    def labware_wells
+      source_plates.flat_map { |plate| plate.wells_in_columns.select(&:passed?) }
+    end
+
+    # Returns all source plates associated with the minimal barcodes.
+    #
+    # @return [Array<Plate>] An array of source plates.
+    def source_plates
+      @source_plates ||=
+        Sequencescape::Api::V2::Plate.find_all({ barcode: minimal_barcodes }, includes: SOURCE_PLATE_INCLUDES)
+    end
+
+    # Returns the source wells for pooling. The wells are filtered using the
+    # well_filter.
+    #
+    # @return [Array<Well>] An array of source wells for pooling.
+    def source_wells_for_pooling
+      well_filter.filtered.map(&:first) # The first element is the well.
+    end
+
+    # Returns the pools for the destination plate.
+    #
+    # @return [Array<Pool>] An array of pools.
+    def pools
+      @pools ||= build_pools
+    end
+
+    # Sets the barcodes and minimal_barcodes instance variables. The
+    # minimal_barcodes are derived from the barcodes by removing any blank
+    # values and stripping whitespace from the remaining values.
+    #
+    # @param barcodes [Array<String>] An array of barcodes.
+    def barcodes=(barcodes)
+      @barcodes = barcodes
+      @minimal_barcodes = barcodes.compact_blank.map(&:strip)
+    end
+
+    # Returns the number of pools based on the sample count from the lookup
+    # table. If the count is not found in the table, the default number of
+    # pools is returned.
+    #
+    # @return [Integer] The number of pools.
+    def number_of_pools
+      Rails.application.config.scrna_core_donor_pooling.fetch(source_wells_for_pooling.count, DEFAULT_NUMBER_OF_POOLS)
+    end
+
+    # Creates transfer requests from source wells to the destination plate in
+    # Sequencescape.
+    #
+    # @param dest_uuid [String] The UUID of the destination plate.
+    # @return [Boolean] Returns true if no exception is raised.
+    def transfer_material_from_parent!(dest_uuid)
+      dest_plate = Sequencescape::Api::V2::Plate.find_by(uuid: dest_uuid)
+      api.transfer_request_collection.create!(
+        user: user_uuid,
+        transfer_requests: transfer_request_attributes(dest_plate)
+      )
+      true
+    end
+
+    # Generates the attributes for transfer requests from the source wells to the
+    # destination plate.
+    #
+    # @param dest_plate [Sequencescape::Api::V2::Plate] The destination plate.
+    # @return [Array<Hash>] An array of hashes, each representing the attributes
+    #   for a transfer request.
+    def transfer_request_attributes(dest_plate)
+      well_filter.filtered.filter_map do |source_well, additional_parameters|
+        request_hash(source_well, dest_plate, additional_parameters)
+      end
+    end
+
+    # Returns the well from a plate that matches the specified location. If no
+    # well is found at the specified location, nil is returned. Used by the
+    # 'request_hash' method to find the destination well.
+    #
+    # @param plate [Sequencescape::Api::V2::Plate] The destination plate.
+    # @param well_location [String] The location to match.
+    # @return [Sequencescape::Api::V2::Well, nil] The well at the specified location,
+    #   or nil if no well is found.
+    def get_well_for_plate_location(plate, well_location)
+      plate.wells.detect { |well| well.location == well_location }
+    end
+
+    # Generates a hash representing a transfer request from a source well to a
+    # destination well. Additional parameters generated by the well filter are
+    # merged into the request hash, i.e.'outer_request' and 'submission_id'.
+    # tag_depth is added to the aliquot attributes.
+    #
+    # @param source_well [Sequencescape::Api::V2::Well] The source well.
+    # @param dest_plate [Sequencescape::Api::V2::Plate] The destination plate.
+    # @param additional_parameters [Hash] Additional parameters to include.
+    # @return [Hash] A hash representing a transfer request.
+    def request_hash(source_well, dest_plate, additional_parameters)
+      dest_location = transfer_hash[source_well][:dest_locn]
+      {
+        'source_asset' => source_well.uuid,
+        'target_asset' => get_well_for_plate_location(dest_plate, dest_location)&.uuid,
+        :aliquot_attributes => {
+          'tag_depth' => tag_depth(source_well)
+        }
+      }.merge(additional_parameters)
+    end
+
+    # Returns a hash representing the transfer from source wells to destination
+    # locations. The hash is build using the 'build_transfer_hash' method.
+    #
+    # @return [Hash] A hash where each key is a source well and each value is a
+    #   hash with a single key-value pair: { dest_locn: destination_location }.
+    def transfer_hash
+      @transfer_hash ||= build_transfer_hash
+    end
+
+    # Builds a mapping between each source well to a destination location.
+    #
+    # @return [Hash] A hash where each key is a source well and each value is a
+    #   hash with a single key-value pair: { dest_locn: destination_location }.
+    def build_transfer_hash
+      pools
+        .each_with_index
+        .with_object({}) do |(pool, index), result|
+          dest_location = WellHelpers.well_at_column_index(index) # column order, 96 wells
+          pool.each { |source_well| result[source_well] = { dest_locn: dest_location } }
+        end
+    end
+
+    # Returns the tag depth for the given source well. The tag depth is the
+    # position of the well in its pool. It is used used as an aliquot attribute
+    # in the transfer request. It is recorded in Sequencescape to avoid tag
+    # clashes.
+    #
+    # @param source_well [Well] The source well for which to retrieve the tag depth.
+    # @return [String] The tag depth as a string, or nil if the well is not in a pool.
+    def tag_depth(source_well)
+      pools.each do |pool|
+        return (pool.index(source_well) + 1).to_s if pool.index(source_well)
+        # index + 1 incase of 0th index
+      end
+    end
+
+    # Builds the pools for the destination plate. The wells are first grouped
+    # by study and project, then split by donor_ids, and finally distributed
+    # across pools.
+    #
+    # @return [Array<Array<Well>>] An array of well groups distributed across pools.
+    def build_pools
+      groups = group_by_study_and_project
+      groups = split_groups_by_donor_ids(groups)
+      distribute_samples_across_pools(groups)
+    end
+
+    # Groups source wells for pooling by study and project. Wells are grouped
+    # based on the study and project of the first aliquot in each well. Returns
+    # an array of groups, where each group is an array of wells with the same
+    # study and project.
+    #
+    # @return [Array<Array<Well>>] An array of well groups.
+    def group_by_study_and_project
+      source_wells_for_pooling.group_by { |well| [well.aliquots.first.study.id, well.aliquots.first.project.id] }.values
+    end
+
+    # Splits groups ensuring unique donor_ids within each group. Iterates over
+    # each group, creating subgroups with wells from a unique donor. The first
+    # occurrences of unique donor_ids are grouped, then the second occurrences,
+    # and so on. This prevents combining samples with the same donor_id.
+    #
+    # @param groups [Array<Array<Well>>] Array of well groups to be split.
+    # @return [Array<Array<Well>>] Array of subgroups split by donor ID.
+    def split_groups_by_donor_ids(groups)
+      groups.flat_map { |group| split_single_group_by_donor_ids(group) }
+    end
+
+    # Splits a single group of wells by donor_ids. Used by the
+    # 'split_groups_by_donor_ids' method.
+    #
+    # @param group [Array<Well>] The group of wells to split.
+    # @return [Array<Array<Well>>] An array of subgroups, each containing wells
+    #   from a unique donor.
+    def split_single_group_by_donor_ids(group)
+      output = []
+      while group.any?
+        subgroup = []
+        unique_donor_ids(group).each do |donor_id|
+          index = group.index { |well| well.aliquots.sample.sample_metadata.donor_id == donor_id }
+          subgroup << group.delete_at(index)
+        end
+        output << subgroup
+      end
+      output
+    end
+
+    # Returns the unique donor_ids from a group of wells. Used by the
+    # 'split_single_group_by_donor_ids' method.
+    #
+    # @param group [Array<Well>] The group of wells from which to retrieve donor_ids.
+    # @return [Array<String>] An array of unique donor_ids.
+    def unique_donor_ids(group)
+      group.map { |well| well.aliquots.sample.sample_metadata.donor_id }.uniq
+    end
+
+    # Distributes samples across pools based on group sizes. It sorts the groups
+    # by size and splits the largest group into two until the number of groups
+    # equals the number of pools or until all groups have a size of 1.
+    #
+    # @param groups [Array<Array<Well>>] Array of well groups to be distributed.
+    # @return [Array<Array<Well>>] Array of distributed groups.
+    def distribute_samples_across_pools(groups)
+      groups.sort_by!(&:size)
+      while groups.any? && groups.last.size > 1 && groups.size < number_of_pools
+        splits = (largest = groups.pop).each_slice(largest.size / 2).to_a
+        groups.concat(splits).sort_by!(&:size)
+      end
+      groups
+    end
+  end
+end

app/views/plate_creation/donor_pooling_plate.html.erb

@@ -0,0 +1,44 @@
+<%= page('donor-pooling-page') do %>
+  <%= content do %>
+    <%= card id: 'main-content' do %>
+      <div>
+        <h3>Instructions</h3>
+        <p>This step uses multiple source plates for pooling together into a destination plate.</p>
+        <p>This process checks that the source plates are compatible and can be used together.</p>
+        <p>Scan the source plate barcodes into the panel on the right of the screen (the order doesn't matter) and click <i>Create Plate</i>.</p>
+      </div>
+    <% end %>
+  <% end %>
+  <%= sidebar do %>
+    <%= card title: 'Add plates to pool', without_block: true do %>
+      <div id="validation_report"></div>
+      <div id="add-plates-instructions-block" class="card-body" >
+        <div class="instructions">
+          <p>Scan in up to <% @labware_creator.number_of_source_plates %> plates.</p>
+        </div>
+      </div>
+    <% end %>
+    <div class="card-body">
+      <%= form_for(
+        @labware_creator,
+        url: limber_plate_children_path(@labware_creator.parent_uuid),
+        as: :plate,
+        html: { method: :post }) do |form| %>
+
+        <%= form.hidden_field :parent_uuid %>
+        <%= form.hidden_field :purpose_uuid %>
+        <% @labware_creator.number_of_source_plates.times do |index| %>
+          <div class="labware-container scan-labware form-group row">
+            <label for="plate[barcodes][<%= index %>]"
+                   class="plate-label col-md-2" >Source Plate <%= index + 1 %></label>
+            <input type="text"
+                   id="plate[barcodes][<%= index %>]"
+                   name="plate[barcodes][]"
+                   class="form-control col-md-8"
+                   required="required"/>
+          </div>
+        <% end %>
+        <%= form.submit 'Create Plate', class: 'btn btn-success btn-lg', id: 'create-labware' %>
+    </div>
+  <% end %>
+<% end %>

config/purposes/scrna_core_cdna_prep.wip.yml

@@ -47,6 +47,12 @@ LRC PBMC Defrost PBS:
 # This plate has come from the LRC PBMC Defrost PBS plate, in SeqOps.
 LRC PBMC Pools:
   :asset_type: plate
+  :creator_class:
+    name: LabwareCreators::DonorPoolingPlate
+    args:
+      number_of_source_plates: 2
+  :state_changer_class: StateChangers::AutomaticPlateStateChanger
+  :work_completion_request_type: 'limber_scrna_core_donor_pooling'
   :stock_plate: false
   :input_plate: false
 # Plate containing pooled PBMCs from different donors.