Class: CaTissue::Specimen

Inherits:
Object
  • Object
show all
Includes:
Collectible, Storable, Jinx::Unique
Defined in:
lib/catissue/domain/specimen.rb,
lib/catissue/migration/unique.rb,
lib/catissue/migration/migratable.rb,
lib/catissue/domain/specimen/pathology/details.rb,
lib/catissue/domain/specimen/pathology/invasion.rb,
lib/catissue/domain/specimen/pathology/gleason_score.rb,
lib/catissue/domain/specimen/pathology/histologic_type.rb,
lib/catissue/domain/specimen/pathology/histologic_grade.rb,
lib/catissue/domain/specimen/pathology/specimen_details.rb,
lib/catissue/domain/specimen/pathology/specimen_invasion.rb,
lib/catissue/domain/specimen/pathology/additional_finding.rb,
lib/catissue/domain/specimen/pathology/histologic_variant_type.rb,
lib/catissue/domain/specimen/pathology/specimen_histologic_type.rb,
lib/catissue/domain/specimen/pathology/specimen_histologic_grade.rb,
lib/catissue/domain/specimen/pathology/specimen_additional_finding.rb,
lib/catissue/domain/specimen/pathology/prostate_specimen_gleason_score.rb,
lib/catissue/domain/specimen/pathology/specimen_histologic_variant_type.rb,
lib/catissue/domain/specimen/pathology/prostate_specimen_pathology_annotation.rb,
lib/catissue/domain/specimen/pathology/specimen_base_solid_tissue_pathology_annotation.rb

Overview

The Specimen domain class.

Defined Under Namespace

Modules: Pathology

Constant Summary

Constants included from Storable

CaTissue::Storable::Position

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Collectible

#collect, #collectible_event_parameters, #collection_event_parameters, #collection_timestamp, #collector, #received?, #received_event_parameters, #receiver

Methods included from Storable

#container, #move_to

Constructor Details

#initialize ⇒ Specimen

Returns a new instance of Specimen.



140
141
142
143
144
 
# File 'lib/catissue/domain/specimen.rb', line 140

def initialize
  super
  # work around caTissue Bug #64
  self.consent_tier_statuses ||= Java::JavaUtil::LinkedHashSet.new
end

Class Method Details

.create_specimen(params) ⇒ Object

Creates a new Specimen or CaTissue::SpecimenRequirement from the given symbol => value parameter hash.

The default class is inferred from the :class parameter, if given, or inherited from this parent specimen otherwise. The inferred class is the camel-case parameter value with Specimen appended, e.g. :tissue => TissueSpecimen. This class name is resolved to a class in the CaTissue module context.

The supported :type parameter value includes the permissible caTissue specimen type String values as well as the shortcut tissue type symbols :fresh, :fixed and :frozen.

If a SpecimenRequirement parameter is provided, then that SpecimenRequirement’s attribute values are merged into the new Specimen after the other parameters are merged. Thus, params takes precedence over the SpecimenRequirement.

If the :count parameter is set to a number greater than one, then the specimen is aliquoted into the specified number of samples.

This method is a convenience method to create either a Specimen or CaTissue::SpecimenRequirement. Although CaTissue::SpecimenRequirement is a direct CaTissue::AbstractSpecimen subclass rather than a Specimen subclass, the create functionality overlaps and Specimen is the friendlier class to define this utility method as opposed to the more obscure CaTissue::AbstractSpecimen.

Parameters:

  • params (<{Symbol => Object}>) —

    the create parameter hash. Besides the listed params options, this hash can include additional target Specimen attribute => value entries for any supported Specimen Java property attribute

Options Hash (params):

  • :class (Symbol, String, Class) —

    the required target specimen class, e.g. :molecular, TissueSpecimen or CaTissue::TissueSpecimen

  • :type (Symbol, String, Class) —

    the optional target specimen type symbol or string, e.g. :frozen or Frozen Tissue Block

  • :quantity (Numeric) —

    the optional target specimen intial quantity

  • :requirement (CaTissue::SpecimenRequirement) —

    the optional requirement with additional target attribute values

Raises:

  • (ArgumentError) —

    if the specimen class option is not recognized



281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
 
# File 'lib/catissue/domain/specimen.rb', line 281

def self.create_specimen(params)
  raise ArgumentError.new("Specimen create params argument type unsupported: #{params.class}") unless Hash === params
  # standardize the class, type and quantity params
  spc_cls = params.delete(:class)
  params[:specimen_class] ||= spc_cls if spc_cls
  spc_type = params.delete(:type)
  params[:specimen_type] ||= spc_type if spc_type
  qty = params.delete(:quantity)
  params[:initial_quantity] ||= qty if qty

  # the specimen_class as a Class, Symbol or String
  cls_opt = params[:specimen_class]
  # standardize the specimen_class parameter as a permissible caTissue value
  standardize_class_parameter(params)
  # if the specimen_class was not specified as a Class, then infer the specimen domain class from the
  # parameter prefix and Specimen suffix
  if Class === cls_opt then
    klass = cls_opt
  else
    class_name = params[:specimen_class] + 'Specimen'
    klass = CaTissue.const_get(class_name)
    raise ArgumentError.new("Specimen class #{class_name} is not recognized for parameter #{cls_opt}") if klass.nil?
  end
  
  # add a default available quantity to a Specimen but not a SpecimenRequirement
  params[:available_quantity] ||= params[:initial_quantity] if klass <= self
  # gather the characteristic parameters
  chr_params, spc_params = params.split { |pa, value| CaTissue::SpecimenCharacteristics.property_defined?(pa) }
  unless chr_params.empty? then
    spc_params[:specimen_characteristics] = CaTissue::SpecimenCharacteristics.new(chr_params)
  end  
  # make the specimen
  klass.new(spc_params)
end

Instance Method Details

#barcode=(value) ⇒ Object

Sets the barcode to the given value. This method converts an Integer to a String.



21
22
23
24
 
# File 'lib/catissue/domain/specimen.rb', line 21

def barcode=(value)
  value = value.to_s if Integer === value
  setBarcode(value)
end

#check_in ⇒ CaTissue::CheckInCheckOutEventParameter

Returns a new check-in parameter.

Returns:



170
171
172
 
# File 'lib/catissue/domain/specimen.rb', line 170

def check_in
  CaTissue::CheckInCheckOutEventParameter.new(:specimen => self, :storage_status => Status.CHECKED_IN)
end

#check_out ⇒ CaTissue::CheckInCheckOutEventParameter

Returns a new check-out parameter.

Returns:



165
166
167
 
# File 'lib/catissue/domain/specimen.rb', line 165

def check_out
  CaTissue::CheckInCheckOutEventParameter.new(:specimen => self, :storage_status => Status.CHECKED_OUT)
end

#collected? ⇒ Boolean

Returns whether this Specimen collection status is Collected.

Returns:

  • (Boolean) —

    whether this Specimen collection status is Collected



152
153
154
 
# File 'lib/catissue/domain/specimen.rb', line 152

def collected?
  collection_status == 'Collected'
end

#collection_protocol ⇒ CaTissue::CollectionProtocol

Convenience method which returns the SCG collection protocol.

Returns:



319
320
321
 
# File 'lib/catissue/domain/specimen.rb', line 319

def collection_protocol
  specimen_collection_group.collection_protocol
end

#consent_tier_statuses ⇒ Java::JavaUtil::Set

Returns the statuses.

Returns:

  • (Java::JavaUtil::Set) —

    the statuses



16
17
18
 
# File 'lib/catissue/domain/specimen.rb', line 16

def consent_tier_statuses
  getConsentTierStatusCollection or (self.consent_tier_statuses = Java::JavaUtil::LinkedHashSet.new)
end

#dispose(reason = nil) ⇒ CaTissue::DisposalEventParameters

Permanently dispose of this specimen.

Parameters:

  • reason (String, nil) (defaults to: nil) —

    the optional disposal reason

Returns:



350
351
352
 
# File 'lib/catissue/domain/specimen.rb', line 350

def dispose(reason=nil)
  CaTissue::DisposalEventParameters.new(:specimen => self, :reason => reason)
end

#disposed? ⇒ Boolean

Returns whether this specimen includes a DisposalEventParameters.

Returns:



342
343
344
 
# File 'lib/catissue/domain/specimen.rb', line 342

def disposed?
  specimen_event_parameters.any? { |ep| CaTissue::DisposalEventParameters === ep }
end

#fetch_saved? ⇒ Boolean

Relaxes the CaRuby::Persistable.fetch_saved? condition for a Specimen as follows:

  • If the Specimen available_quantity was updated, then fetch the saved Specimen.

Returns:

  • (Boolean) 


160
161
162
 
# File 'lib/catissue/domain/specimen.rb', line 160

def fetch_saved?
  super and available_quantity_changed?
end

#location ⇒ Object

Returns this Specimen position Location.

Returns:

  • this Specimen position Location



243
244
245
 
# File 'lib/catissue/domain/specimen.rb', line 243

def location
  position.location if position
end

#match_in_owner_scope(others) ⇒ Object

Returns the Specimen in others which matches this Specimen in the scope of an owner SCG. This method relaxes Jinx::Resource.match_in_owner_scope to include a match on at least one external identifier.



220
221
222
223
224
 
# File 'lib/catissue/domain/specimen.rb', line 220

def match_in_owner_scope(others)
  super or others.detect do |other|
    other.class == self.class and external_identifier_match?(other)
  end
end

#merge_attribute(attribute, newval, matches = nil) ⇒ Object

Overrides CaRuby::Mergable.merge_attribute to work around the caTissue

bugs described in {CaTissue::Specimen.remove_phantom_external_identifier}.



176
177
178
179
180
181
 
# File 'lib/catissue/domain/specimen.rb', line 176

def merge_attribute(attribute, newval, matches=nil)
  if attribute == :external_identifiers and newval then
    CaTissue::Specimen.remove_phantom_external_identifier(newval)
  end
  super
end

#merge_attributes(other, attributes = nil, matches = nil, &filter) ⇒ Object

Override default Jinx::Resource.merge_attributes to ignore a source SpecimenRequirement parent_specimen.



196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
 
# File 'lib/catissue/domain/specimen.rb', line 196

def merge_attributes(other, attributes=nil, matches=nil, &filter)
  case other
  when SpecimenRequirement then
    # merge with the default requirement merge attributes if necessary
    attributes ||= MERGEABLE_RQMT_ATTRS
    super(other, attributes)
    # copy the requirement characteristics
    sc = other.specimen_characteristics
    self.specimen_characteristics ||= sc.copy(MERGEABLE_SPC_CHR_ATTRS) if sc
  when Jinx::Hasher then
    # the requirement template
    rqmt = other[:specimen_requirement] || other[:requirement]
    # merge the attribute => value hash
    super
    # merge the SpecimenRequirement after the hash
    merge_attributes(rqmt) if rqmt
  else super
  end
  self
end

#migrate_initial_quantity(value, row) ⇒ Object

Parses the source field as a UOM::Measurement if it is a string. Otherwises, returns the source value.



64
65
66
 
# File 'lib/catissue/migration/migratable.rb', line 64

def migrate_initial_quantity(value, row)
  standardize_quantity(value)
end

#minimal_match?(other) ⇒ Boolean

Augments AbstractSpecimen#minimal_match? with an additional restriction that the other specimen is in pending state. This ensures that a specimen submitted for create matches its auto-generated counterpart but a new specimen can be created even if it matches an existing specimen on the features described in AbstractSpecimen#minimal_match?.

Returns:

  • (Boolean) 


233
234
235
 
# File 'lib/catissue/domain/specimen.rb', line 233

def minimal_match?(other)
  super and other.collection_status == 'Pending'
end

#pending? ⇒ Boolean

Returns whether this Specimen collection status is Pending.

Returns:

  • (Boolean) —

    whether this Specimen collection status is Pending



147
148
149
 
# File 'lib/catissue/domain/specimen.rb', line 147

def pending?
  collection_status == 'Pending'
end

#position_class ⇒ Object

Returns the SpecimenPosition class which this Specimen’s Storable can occupy.

Returns:

  • the SpecimenPosition class which this Specimen’s Storable can occupy



238
239
240
 
# File 'lib/catissue/domain/specimen.rb', line 238

def position_class
  CaTissue::SpecimenPosition
end

#withdraw_consent(consent_tier = nil) ⇒ Object

Withdraws consent for this Specimen as follows:

  • If a consent tier is provided, then the SCG ConsentTierStatus with the given consent tier is withdrawn.

  • Otherwise, all SCG consents are withdrawn.

Parameters:

  • consent_tier (CaTissue::ConsentTier, nil) (defaults to: nil) —

    the optional consent tier to withdraw

Raises:

  • (Jinx::ValidationError) —

    if there is no SCG consent status for the given consent tier



330
331
332
333
334
335
336
337
338
339
 
# File 'lib/catissue/domain/specimen.rb', line 330

def withdraw_consent(consent_tier=nil)
  if consent_tier.nil? then
    return specimen_collection_group.consent_tier_statuses.each { |cts| withdraw_consent(cts.consent_tier) }
  end
  tgt = consent_tier_statuses.detect { |cts| cts.consent_tier.matches?(consent_tier) }
  if tgt.nil? then
    consent_tier_statuses << tgt = ConsentTierStatus.new(:consent_tier => consent_tier)
  end
  tgt.status = 'Withdrawn'
end