Public Member Functions
public	hive_dba ()

public	display_name ()

public	unambig_key ()

public	collection_of ()

public	find_by_query ()

public	test_connections ()

public	new ()

public	invalidate_collections ()

public	save_collections ()

public	add_new_or_update ()

public	get_source_analyses ()

protected	_meta_value_by_key ()

public	hive_use_param_stack ()

public	hive_pipeline_name ()

public	hive_auto_rebalance_semaphores ()

public	hive_use_triggers ()

public	hive_default_max_retry_count ()

public	list_all_hive_tables ()

public	list_all_hive_views ()

public	hive_sql_schema_version ()

public	params_as_hash ()

public	get_cached_hive_current_load ()

public	invalidate_hive_current_load ()

public	print_diagram ()

public	apply_tweaks ()

Detailed Description

Definition at line 12 of file HivePipeline.pm.

Member Function Documentation

◆ _meta_value_by_key()

protected Bio::EnsEMBL::Hive::HivePipeline::_meta_value_by_key ( )

    Description: getter/setter for a particular meta_value from 'MetaParameters' collection given meta_key

Code:

click to view

◆ add_new_or_update()

public Bio::EnsEMBL::Hive::HivePipeline::add_new_or_update ( )

Undocumented method

Code:

click to view

sub add_new_or_update {
    my $self = shift @_;
    my $type = shift @_;
    # $verbose is an extra optional argument that sits between the type and the object hash
    my $verbose = scalar(@_) % 2 ? shift : 0;
    my $class   = 'Bio::EnsEMBL::Hive::'.$type;
    my $coll    = $self->collection_of( $type );
    my $object;
    my $newly_made = 0;
    if( my $unikey_keys = $class->unikey() ) {
        my %other_pairs = @_;
        my %unikey_pairs;
        @unikey_pairs{ @$unikey_keys} = delete @other_pairs{ @$unikey_keys };
        if( $object = $coll->find_one_by( %unikey_pairs ) ) {
            my $found_display = $verbose && (UNIVERSAL::can($object, 'toString') ? $object->toString : stringify($object));
            if(keys %other_pairs) {
                print "Updating $found_display with (".stringify(\%other_pairs).")\n" if $verbose;
                if( ref($object) eq 'HASH' ) {
                    @$object{ keys %other_pairs } = values %other_pairs;
                } else {
                    while( my ($key, $value) = each %other_pairs ) {
                        $object->$key($value);
                    }
                }
            } else {
                print "Found a matching $found_display\n" if $verbose;
            }
        } elsif( my $dark_coll = $coll->dark_collection) {
            if( my $shadow_object = $dark_coll->find_one_by( %unikey_pairs ) ) {
                $dark_coll->forget( $shadow_object );
                my $found_display = $verbose && (UNIVERSAL::can($shadow_object, 'toString') ? $shadow_object->toString : stringify($shadow_object));
                print "Undeleting $found_display\n" if $verbose;
            }
        }
    } else {
        warn "$class doesn't redefine unikey(), so unique objects cannot be identified";
    }
    unless( $object ) {
        $object = $class->can('new') ? $class->new( @_ ) : { @_ };
        $newly_made = 1;
        $coll->add( $object );
        $object->hive_pipeline($self) if UNIVERSAL::can($object, 'hive_pipeline');
        my $found_display = $verbose && (UNIVERSAL::can($object, 'toString') ? $object->toString : 'naked entry '.stringify($object));
        print "Created a new $found_display\n" if $verbose;
    }
    return ($object, $newly_made);
}

◆ apply_tweaks()

public Bio::EnsEMBL::Hive::HivePipeline::apply_tweaks ( )

    Description: changes attributes of Analyses|ResourceClasses|ResourceDescriptions or values of pipeline/analysis parameters

Code:

click to view

sub apply_tweaks {
    my $self    = shift @_;
    my $tweaks  = shift @_;
    my $need_write = 0;
    foreach my $tweak (@$tweaks) {
        print "\nTweak.Request\t$tweak\n";
        if($tweak=~/^pipeline\.param\[(\w+)\](\?|#|=(.+))$/) {
            my ($param_name, $operator, $new_value_str) = ($1, $2, $3);
            my $pwp_collection  = $self->collection_of( 'PipelineWideParameters' );
            my $hash_pair       = $pwp_collection->find_one_by('param_name', $param_name);
            if($operator eq '?') {
                print "Tweak.Show    \tpipeline.param[$param_name] ::\t"
                     . ($hash_pair ? $hash_pair->{'param_value'} : '(missing_value)') . "\n";
            } elsif($operator eq '#') {
                if ($hash_pair) {
                    $need_write = 1;
                    $pwp_collection->forget_and_mark_for_deletion( $hash_pair );
                    print "Tweak.Deleting\tpipeline.param[$param_name] ::\t".stringify($hash_pair->{'param_value'})." --> (missing value)\n";
                } else {
                    print "Tweak.Deleting\tpipeline.param[$param_name] skipped (does not exist)\n";
                }
            } else {
                $need_write = 1;
                my $new_value = destringify( $new_value_str );
                $new_value_str = stringify($new_value);
                if($hash_pair) {
                    print "Tweak.Changing\tpipeline.param[$param_name] ::\t$hash_pair->{'param_value'} --> $new_value_str\n";
                    $hash_pair->{'param_value'} = $new_value_str;
                } else {
                    print "Tweak.Adding  \tpipeline.param[$param_name] ::\t(missing value) --> $new_value_str\n";
                    $self->add_new_or_update( 'PipelineWideParameters',
                        'param_name'    => $param_name,
                        'param_value'   => $new_value_str,
                    );
                }
            }
        } elsif($tweak=~/^pipeline\.(\w+)(\?|=(.+))$/) {
            my ($attrib_name, $operator, $new_value_str) = ($1, $2, $3);
            if($self->can($attrib_name)) {
                my $old_value = stringify( $self->$attrib_name() );
                if($operator eq '?') {
                    print "Tweak.Show    \tpipeline.$attrib_name ::\t$old_value\n";
                } else {
                    print "Tweak.Changing\tpipeline.$attrib_name ::\t$old_value --> $new_value_str\n";
                    $self->$attrib_name( $new_value_str );
                    $need_write = 1;
                }
            } else {
                print "Tweak.Error   \tCould not find the pipeline-wide '$attrib_name' method\n";
            }
        } elsif($tweak=~/^analysis\[([^\]]+)\]\.param\[(\w+)\](\?|#|=(.+))$/) {
            my ($analyses_pattern, $param_name, $operator, $new_value_str) = ($1, $2, $3, $4);
            my $analyses = $self->collection_of( 'Analysis' )->find_all_by_pattern( $analyses_pattern );
            print "Tweak.Found   \t".scalar(@$analyses)." analyses matching the pattern '$analyses_pattern'\n";
            my $new_value = destringify( $new_value_str );
            $new_value_str = stringify( $new_value );
            foreach my $analysis (@$analyses) {
                my $analysis_name = $analysis->logic_name;
                my $old_value = $analysis->parameters;
                my $param_hash  = destringify( $old_value );
                if($operator eq '?') {
                    print "Tweak.Show    \tanalysis[$analysis_name].param[$param_name] ::\t"
                        . (exists($param_hash->{ $param_name }) ? stringify($param_hash->{ $param_name }) : '(missing value)')
                        ."\n";
                } elsif($operator eq '#') {
                    print "Tweak.Deleting\tanalysis[$analysis_name].param[$param_name] ::\t".stringify($param_hash->{ $param_name })." --> (missing value)\n";
                    delete $param_hash->{ $param_name };
                    $analysis->parameters( stringify($param_hash) );
                    $need_write = 1;
                } else {
                    if(exists($param_hash->{ $param_name })) {
                        print "Tweak.Changing\tanalysis[$analysis_name].param[$param_name] ::\t".stringify($param_hash->{ $param_name })." --> $new_value_str\n";
                    } else {
                        print "Tweak.Adding  \tanalysis[$analysis_name].param[$param_name] ::\t(missing value) --> $new_value_str\n";
                    }
                    $param_hash->{ $param_name } = $new_value;
                    $analysis->parameters( stringify($param_hash) );
                    $need_write = 1;
                }
            }
        } elsif($tweak=~/^analysis\[([^\]]+)\]\.(wait_for|flow_into)(\?|#|\+?=(.+))$/) {
            my ($analyses_pattern, $attrib_name, $operation, $new_value_str) = ($1, $2, $3, $4);
            $operation=~/^(\?|#|\+?=)/;
            my $operator = $1;
            my $analyses = $self->collection_of( 'Analysis' )->find_all_by_pattern( $analyses_pattern );
            print "Tweak.Found   \t".scalar(@$analyses)." analyses matching the pattern '$analyses_pattern'\n";
            my $new_value = destringify( $new_value_str );
            foreach my $analysis (@$analyses) {
                my $analysis_name = $analysis->logic_name;
                if( $attrib_name eq 'wait_for' ) {
                    my $cr_collection   = $self->collection_of( 'AnalysisCtrlRule' );
                    my $acr_collection  = $analysis->control_rules_collection;
                    if($operator eq '?') {
                        print "Tweak.Show    \tanalysis[$analysis_name].wait_for ::\t[".join(', ', map { $_->condition_analysis_url } @$acr_collection )."]\n";
                    }
                    if($operator eq '#' or $operator eq '=') {     # delete the existing rules
                        foreach my $c_rule ( @$acr_collection ) {
                            $cr_collection->forget_and_mark_for_deletion( $c_rule );
                            $need_write = 1;
                            print "Tweak.Deleting\t".$c_rule->toString." --> (missing value)\n";
                        }
                    }
                    if($operator eq '=' or $operator eq '+=') {     # create new rules
                        Bio::EnsEMBL::Hive::Utils::PCL::parse_wait_for($self, $analysis, $new_value);
                        foreach my $c_rule ( @{$analysis->control_rules_collection} ) {
                            print "Tweak.Adding\t".$c_rule->toString."\n";
                        }
                        $need_write = 1;
                    }
                } elsif( $attrib_name eq 'flow_into' ) {
                    if($operator eq '?') {
                        # FIXME: should not recurse
                        $analysis->print_diagram_node($self, '', {});
                    }
                    if($operator eq '#' or $operator eq '=') {     # delete the existing rules
                        my $dfr_collection = $self->collection_of( 'DataflowRule' );
                        my $dft_collection = $self->collection_of( 'DataflowTarget' );
                        foreach my $group ( @{$analysis->get_grouped_dataflow_rules} ) {
                            my ($funnel_dfr, $fan_dfrs, $funnel_df_targets) = @$group;
                            foreach my $df_rule (@$fan_dfrs, $funnel_dfr) {
                                foreach my $df_target ( @{$df_rule->get_my_targets} ) {
                                    $dft_collection->forget_and_mark_for_deletion( $df_target );
                                    print "Tweak.Deleting\t".$df_target->toString." --> (missing value)\n";
                                }
                                $dfr_collection->forget_and_mark_for_deletion( $df_rule );
                                $need_write = 1;
                                print "Tweak.Deleting\t".$df_rule->toString." --> (missing value)\n";
                            }
                        }
                    }
                    if($operator eq '=' or $operator eq '+=') {     # create new rules
                        $need_write = 1;
                        Bio::EnsEMBL::Hive::Utils::PCL::parse_flow_into($self, $analysis, $new_value );
                    }
                }
            }
        } elsif($tweak=~/^analysis\[([^\]]+)\]\.(\w+)(\?|#|=(.+))$/) {
            my ($analyses_pattern, $attrib_name, $operator, $new_value_str) = ($1, $2, $3, $4);
            my $analyses = $self->collection_of( 'Analysis' )->find_all_by_pattern( $analyses_pattern );
            print "Tweak.Found   \t".scalar(@$analyses)." analyses matching the pattern '$analyses_pattern'\n";
            my $new_value = destringify( $new_value_str );
            foreach my $analysis (@$analyses) {
                my $analysis_name = $analysis->logic_name;
                if( $attrib_name eq 'resource_class' ) {
                    if($operator eq '?') {
                        my $old_value = $analysis->resource_class;
                        print "Tweak.Show    \tanalysis[$analysis_name].resource_class ::\t".$old_value->name."\n";
                    } elsif($operator eq '#') {
                        print "Tweak.Error   \tDeleting of an Analysis' resource-class is not supported\n";
                    } else {
                        my $old_value = $analysis->resource_class;
                        print "Tweak.Changing\tanalysis[$analysis_name].resource_class ::\t".$old_value->name." --> $new_value_str\n";
                        my $resource_class;
                        if($resource_class = $self->collection_of( 'ResourceClass' )->find_one_by( 'name', $new_value )) {
                            print "Tweak.Found   \tresource_class[$new_value_str]\n";
                            $analysis->resource_class( $resource_class );
                            $need_write = 1;
                        } else {
                            print "Tweak.Error   \t'$new_value_str' is not a known resource-class\n";
                        }
                    }
                } elsif( $attrib_name eq 'is_excluded' ) {
                    my $analysis_stats = $analysis->stats();
                    if($operator eq '?') {
                        print "Tweak.Show    \tanalysis[$analysis_name].is_excluded ::\t".$analysis_stats->is_excluded()."\n";
                    } elsif($operator eq '#') {
                        print "Tweak.Error   \tDeleting of excluded status is not supported\n";
                    } else {
                        if(!($new_value =~ /^[01]$/)) {
                            print "Tweak.Error    \tis_excluded can only be 0 (no) or 1 (yes)\n";
                        } elsif ($new_value == $analysis_stats->is_excluded()) {
                            print "Tweak.Info    \tanalysis[$analysis_name].is_excluded is already $new_value, leaving as is\n";
                        } else {
                           print "Tweak.Changing\tanalysis[$analysis_name].is_excluded ::\t" .
                               $analysis_stats->is_excluded() . " --> $new_value_str\n";
                           $analysis_stats->is_excluded($new_value);
                           $need_write = 1;
                        }
                    }
                } elsif( $attrib_name eq 'dbID' ) {
                    print "Tweak.Error   \tChanging the dbID of an Analysis is not supported\n";
                } elsif($analysis->can($attrib_name)) {
                    my $old_value = stringify($analysis->$attrib_name());
                    if($operator eq '?') {
                        print "Tweak.Show    \tanalysis[$analysis_name].$attrib_name ::\t$old_value\n";
                    } elsif($operator eq '#') {
                        print "Tweak.Error   \tDeleting of Analysis attributes is not supported\n";
                    } else {
                        print "Tweak.Changing\tanalysis[$analysis_name].$attrib_name ::\t$old_value --> ".stringify($new_value)."\n";
                        $analysis->$attrib_name( $new_value );
                        $need_write = 1;
                    }
                } else {
                    print "Tweak.Error   \tAnalysis does not support '$attrib_name' attribute\n";
                }
            }
        } elsif($tweak=~/^resource_class\[([^\]]+)\]\.(\w+)(\?|=(.+))$/) {
            my ($rc_pattern, $meadow_type, $operator, $new_value_str) = ($1, $2, $3, $4);
            my $resource_classes = $self->collection_of( 'ResourceClass' )->find_all_by_pattern( $rc_pattern );
            print "Tweak.Found   \t".scalar(@$resource_classes)." resource_classes matching the pattern '$rc_pattern'\n";
            if($operator eq '?') {
                foreach my $rc (@$resource_classes) {
                    my $rc_name = $rc->name;
                    if(my $rd = $self->collection_of( 'ResourceDescription' )->find_one_by('resource_class', $rc, 'meadow_type', $meadow_type)) {
                        my ($submission_cmd_args, $worker_cmd_args) = ($rd->submission_cmd_args, $rd->worker_cmd_args);
                        print "Tweak.Show    \tresource_class[$rc_name].$meadow_type ::\t".stringify([$submission_cmd_args, $worker_cmd_args])."\n";
                    } else {
                        print "Tweak.Show    \tresource_class[$rc_name].$meadow_type ::\t(missing values)\n";
                    }
                }
            } else {
                # Auto-vivification of the ResourceClass
                unless (@$resource_classes) {
                    print "Tweak.Adding  \tresource_class[$rc_pattern]\n";
                    my ($resource_class) = $self->add_new_or_update( 'ResourceClass',   # NB: add_new_or_update returns a list
                        'name'  => $rc_pattern,
                    );
                    push @$resource_classes, $resource_class;
                    $need_write = 1;
                }
                my $new_value = destringify( $new_value_str );
                my ($new_submission_cmd_args, $new_worker_cmd_args) = (ref($new_value) eq 'ARRAY') ? @$new_value : ($new_value, '');
                foreach my $rc (@$resource_classes) {
                    my $rc_name = $rc->name;
                    if(my $rd = $self->collection_of( 'ResourceDescription' )->find_one_by('resource_class', $rc, 'meadow_type', $meadow_type)) {
                        my ($submission_cmd_args, $worker_cmd_args) = ($rd->submission_cmd_args, $rd->worker_cmd_args);
                        print "Tweak.Changing\tresource_class[$rc_name].$meadow_type :: "
                                .stringify([$submission_cmd_args, $worker_cmd_args])." --> "
                                .stringify([$new_submission_cmd_args, $new_worker_cmd_args])."\n";
                        $rd->submission_cmd_args(   $new_submission_cmd_args );
                        $rd->worker_cmd_args(       $new_worker_cmd_args     );
                    } else {
                        print "Tweak.Adding  \tresource_class[$rc_name].$meadow_type :: (missing values) --> "
                                .stringify([$new_submission_cmd_args, $new_worker_cmd_args])."\n";
                        my ($rd) = $self->add_new_or_update( 'ResourceDescription',   # NB: add_new_or_update returns a list
                            'resource_class'        => $rc,
                            'meadow_type'           => $meadow_type,
                            'submission_cmd_args'   => $new_submission_cmd_args,
                            'worker_cmd_args'       => $new_worker_cmd_args,
                        );
                    }
                    $need_write = 1;
                }
            }
        } else {
            print "Tweak.Error   \tFailed to parse the tweak\n";
        }
    }
    return $need_write;
}

◆ collection_of()

public Bio::EnsEMBL::Hive::HivePipeline::collection_of ( )

Undocumented method

Code:

click to view

◆ display_name()

public Bio::EnsEMBL::Hive::HivePipeline::display_name ( )

Undocumented method

Code:

click to view

◆ find_by_query()

public Bio::EnsEMBL::Hive::HivePipeline::find_by_query ( )

Undocumented method

Code:

click to view

sub find_by_query {
    my $self            = shift @_;
    my $query_params    = shift @_;
    my $no_die          = shift @_;
    if(my $object_type = delete $query_params->{'object_type'}) {
        my $object;
        if($object_type eq 'Accumulator' or $object_type eq 'NakedTable') {
            unless($object = $self->collection_of($object_type)->find_one_by( %$query_params )) {
                my @specific_adaptor_params = ($object_type eq 'NakedTable')
                    ? ('table_name' => $query_params->{'table_name'},
                        $query_params->{'insertion_method'}
                            ? ('insertion_method' => $query_params->{'insertion_method'})
                            : ()
                      )
                    : ();
                ($object) = $self->add_new_or_update( $object_type, # NB: add_new_or_update returns a list
                    %$query_params,
                    $self->hive_dba ? ('adaptor' => $self->hive_dba->get_adaptor($object_type, @specific_adaptor_params)) : (),
                );
            }
        } elsif($object_type eq 'AnalysisJob' or $object_type eq 'Semaphore') {
            my $id_name = { 'AnalysisJob' => 'job_id', 'Semaphore' => 'semaphore_id' }->{$object_type};
            my $dbID    = $query_params->{$id_name};
            my $coll    = $self->collection_of($object_type);
            unless($object = $coll->find_one_by( 'dbID' => $dbID )) {
                my $adaptor = $self->hive_dba->get_adaptor( $object_type );
                if( $object = $adaptor->fetch_by_dbID( $dbID ) ) {
                    $coll->add( $object );
                }
            }
        } else {
            $object = $self->collection_of($object_type)->find_one_by( %$query_params );
        }
        return $object if $object || $no_die;
        throw("Could not find an '$object_type' object from query ".stringify($query_params)." in ".$self->display_name);
    } else {
        throw("Could not find or guess the object_type from the query ".stringify($query_params)." , so could not find the object");
    }
}

◆ get_cached_hive_current_load()

public Bio::EnsEMBL::Hive::HivePipeline::get_cached_hive_current_load ( )

    Description: Proxy for RoleAdaptor::get_hive_current_load() that caches the last value.

Code:

click to view

◆ get_source_analyses()

public Bio::EnsEMBL::Hive::HivePipeline::get_source_analyses ( )

    Description: returns a listref of analyses that do not have local inflow ("source analyses")

Code:

click to view

◆ hive_auto_rebalance_semaphores()

public Bio::EnsEMBL::Hive::HivePipeline::hive_auto_rebalance_semaphores ( )

    Description: getter/setter via MetaParameters. Defines whether beekeeper should attempt to rebalance semaphores on each iteration.

Code:

click to view

◆ hive_dba()

public Bio::EnsEMBL::Hive::HivePipeline::hive_dba ( )

Undocumented method

Code:

click to view

◆ hive_default_max_retry_count()

public Bio::EnsEMBL::Hive::HivePipeline::hive_default_max_retry_count ( )

    Description: getter/setter via MetaParameters. Defines the default value for analysis_base.max_retry_count

Code:

click to view

◆ hive_pipeline_name()

public Bio::EnsEMBL::Hive::HivePipeline::hive_pipeline_name ( )

    Description: getter/setter via MetaParameters. Defines the symbolic name of the pipeline.

Code:

click to view

◆ hive_sql_schema_version()

public Bio::EnsEMBL::Hive::HivePipeline::hive_sql_schema_version ( )

    Description: getter via MetaParameters. Defines the Hive SQL schema version of the database if it has been stored

Code:

click to view

◆ hive_use_param_stack()

public Bio::EnsEMBL::Hive::HivePipeline::hive_use_param_stack ( )

    Description: getter/setter via MetaParameters. Defines which one of two modes of parameter propagation is used in this pipeline

Code:

click to view

◆ hive_use_triggers()

public Bio::EnsEMBL::Hive::HivePipeline::hive_use_triggers ( )

    Description: getter via MetaParameters. Defines whether SQL triggers are used to automatically update AnalysisStats counters

Code:

click to view

◆ invalidate_collections()

public Bio::EnsEMBL::Hive::HivePipeline::invalidate_collections ( )

Undocumented method

Code:

click to view

◆ invalidate_hive_current_load()

public Bio::EnsEMBL::Hive::HivePipeline::invalidate_hive_current_load ( )

    Description: Method that forces the next get_cached_hive_current_load() call to fetch a fresh value from the database

Code:

click to view

◆ list_all_hive_tables()

public Bio::EnsEMBL::Hive::HivePipeline::list_all_hive_tables ( )

    Description: getter via MetaParameters. Lists the (MySQL) table names used by the HivePipeline

Code:

click to view

◆ list_all_hive_views()

public Bio::EnsEMBL::Hive::HivePipeline::list_all_hive_views ( )

    Description: getter via MetaParameters. Lists the (MySQL) view names used by the HivePipeline

Code:

click to view

◆ new()

public Bio::EnsEMBL::Hive::HivePipeline::new ( )

Undocumented method

Code:

click to view

◆ params_as_hash()

public Bio::EnsEMBL::Hive::HivePipeline::params_as_hash ( )

    Description: returns the destringified contents of the 'PipelineWideParameters' collection as a hash

Code:

click to view

◆ print_diagram()

public Bio::EnsEMBL::Hive::HivePipeline::print_diagram ( )

    Description: prints a "Unicode art" textual representation of the pipeline's flow diagram

Code:

click to view

◆ save_collections()

public Bio::EnsEMBL::Hive::HivePipeline::save_collections ( )

Undocumented method

Code:

click to view

◆ test_connections()

public Bio::EnsEMBL::Hive::HivePipeline::test_connections ( )

Undocumented method

Code:

click to view

◆ unambig_key()

public Bio::EnsEMBL::Hive::HivePipeline::unambig_key ( )

Undocumented method

Code:

click to view

The documentation for this class was generated from the following file:

modules/Bio/EnsEMBL/Hive/HivePipeline.pm

Public Member Functions

Detailed Description

Member Function Documentation

◆ _meta_value_by_key()

◆ add_new_or_update()

◆ apply_tweaks()

◆ collection_of()

◆ display_name()

◆ find_by_query()

◆ get_cached_hive_current_load()

◆ get_source_analyses()

◆ hive_auto_rebalance_semaphores()

◆ hive_dba()

◆ hive_default_max_retry_count()

◆ hive_pipeline_name()

◆ hive_sql_schema_version()

◆ hive_use_param_stack()

◆ hive_use_triggers()

◆ invalidate_collections()

◆ invalidate_hive_current_load()

◆ list_all_hive_tables()

◆ list_all_hive_views()

◆ new()

◆ params_as_hash()

◆ print_diagram()

◆ save_collections()

◆ test_connections()

◆ unambig_key()