/ 
Bio-RNA-Barriers-0.03
River stage zero No dependents
/ Bio::RNA::Barriers::Minimum

NAME

Bio::RNA::Barriers::Minimum - Store a single local minimum (macrostate) from the output of Barriers

SYNOPSIS

use Bio::RNA::Barriers;

my $min_string = '...';            # single line from .bar file
my $min = Bio::RNA::Barriers::Minimum->new($min_string);
# my $min2 = $results->get_min(3)  # usually used like this

print "$min\n";                    # prints minimum as in the results file

if ($min->has_bsize and $min->is_connected)
    print "Minimum contributes an energy of ", $min->grad_basin_energy(),
          " to the partition function."

DESCRIPTION

Objects of this class repesent the individual local minima (macrostates) from the results file of Barriers. The construction is usually done automatically by the results objects (cf. Bio::RNA::Barriers::Results). The methods can be used for various queries.

METHODS

$min->new($results_file_line)

Construct a minimum object from a single line of the Barriers results file.

$min->ancestors()

Determine all ancestor minima of this minimum, i.e. this minimum's father, grand father, grand grand father etc. in this order. Returns a list of all ancestors (may be empty if min is disconnected).

$min->has_bsize()

Boolean. True iff the minimum provides information about the basin size as computed by the Barriers option --bsize.

$min->merged_struct_count()

Given is the number of structures in the current basin (including merged ones) at the time of merging. For minimum 1, this is close to the total number of input structures (except for disconnected structures and other missing ones (???)).

This attribute is only available if Barriers was used with the --bsize option. Use $min->has_bsize() to query this.

$min->father_struct_count()

The number of structures in the basin that we merge into (father basin) at the time of merging.

This attribute is only available if Barriers was used with the --bsize option. Use $min->has_bsize() to query this.

$min->merged_basin_energy()

The free energy of (the partition function of) the basin -- including all merged basins -- at the time this basin is merged. For minimum 1, this corresponds to the ensemble's free energy as far as it was enumerated by RNAsubopt (excluding disconnected structures).

This attribute is only available if Barriers was used with the --bsize option. Use $min->has_bsize() to query this.

$min->grad_struct_count()

The number of structures only in this gradient basin, excluding merged basins.

Open questions: What about --minh merging? Why doesn't this column sum up to exactly to the total number of structs if --max==Inf (some are missing)? Issues due to degenerate energies?

This attribute is only available if Barriers was used with the --bsize option. Use $min->has_bsize() to query this.

$min->grad_basin_energy()

Free energy of the basin without any merged basins. Summing up the partition functions corresponding to these energies, one obtains a free energy almost equal to the ensemble energy (up to rounding errors due to 6 digit precision, and of course up to the enumeration threshold used for RNAsubopt).

This attribute is only available if Barriers was used with the --bsize option. Use $min->has_bsize() to query this.

$min->is_global_min()

Returns true iff this is the global minimum (i.e. basin 1).

$min->index()

1-based index of the minimum (as is the Barriers file).

$min->struct()

Returns the dot-bracket structure string of the minimum.

$min->mfe()

Local minimum free energy of the basin (i.e. the minimum's energy).

$min->father_index()

Returns the index of the father minimum (i.e. the one this minimum has been merged to).

$min->barrier_height()

Returns the barrier height (relative energy difference of the saddle point to the local minimum). For the absolute energy of the saddle point, see saddle_height().

$min->saddle_height()

Absolute energy of the lowest structure connecting this basin to another one. The barrier height, in contrast, is the relative energy of the same structure w.r.t. to the basin's (local) mfe.

Beware: if the basin does not have a father (father == 0), then the reported saddle height is given with respect to the global exploration threshold. This is strange but consistent with original Barriers files.

$min->global_saddle_height()

Saddle height as described for saddle_height(), but not with respect to any neighbor minimum, but to the global mfe structure (basin 1).

$min->saddle_struct()

Returns the saddle structure via which it was merged to its father minimum. If this attribute was not set (i.e. Barriers was run without the --saddle option), it croaks when accessed.

Use the has_saddle() predicate to query the status of this attribute.

$min->has_saddle_struct()

Predicate for the saddle attribute. True iff the minimum provides the saddle structure via which it was merged to its father minimum, as computed by the Barriers option --saddle. It can be queried via the saddle_struct method.

$min->father()

Returns (a reference to) the father minimum object.

$min->has_father()

Returns true iff the minimum has a father minimum it has been merged to.

$min->is_connected()

Boolean. True iff the minimum is connected to basin 1 (the mfe basin).

$min->ancestors()

Determine all ancestor minima of this minimum, i.e. this minimum's father, grand father, grand grand father etc. in this order.

$min->stringify()

Stringify minimum to equal an entry line in the barriers output file. Format strings are taken from Barriers' C source code.

$min->brief()

Stringification method returning a more brief representation of the minimum containing only the index, min struct, its energy, the father's index, and the barrier height. This equals the output of Barriers if neither --bsize nor --saddle is given.

AUTHOR

Felix Kuehnl, <felix at bioinf.uni-leipzig.de>

BUGS

Please report any bugs or feature requests by raising an issue at https://github.com/xileF1337/Bio-RNA-Barriers/issues.

You can also do so by mailing to bug-bio-rna-barmap at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Bio-RNA-BarMap. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Bio::RNA::Barriers

You can also look for information at the official Barriers website:

https://www.tbi.univie.ac.at/RNA/Barriers/

LICENSE AND COPYRIGHT

Copyright 2019-2021 Felix Kuehnl.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.