The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Bio-RNA-Barriers-0.03
River stage zero No dependents
++
/ Bio::RNA::Barriers::RateMatrix

NAME

Bio::RNA::Barriers::RateMatrix - Store and manipulate a Barriers transition rate matrix.

SYNOPSIS

    use Bio::RNA::Barriers;

    # Functional interface using plain Perl lists to store the matrix.
    my $list_mat
        = Bio::RNA::Barriers::RateMatrix->read_text_rate_matrix($input_handle);
    $list_mat
        = Bio::RNA::Barriers::RateMatrix->read_bin_rate_matrix($input_handle);

    # Read a binary rate matrix directly from file. Binary matrices are more
    # precise and smaller than text matrices.
    my $rate_matrix = Bio::RNA::Barriers::RateMatrix->new(
        file_name => '/path/to/rates.bin',
        file_type => 'BIN',
    );

    # Read a text rate matrix from an opened handle.
    open my $rate_matrix_fh_txt, '<', '/path/to/rates.out';
    my $rate_matrix = Bio::RNA::Barriers::RateMatrix->new(
        file_handle => $rate_matrix_fh_txt,
        file_type   => 'TXT',
    );

    # Print matrix, dimension, and a single rate.
    print "$rate_matrix";
    print 'Dimension of rate matrix is ', $rate_matrix->dim, "\n";
    print 'Rate from state 1 to state 3 is ',
          $rate_matrix->rate_from_to(1, 3),
          "\n";

    # Remove entries for a list of states {1, 3, 5} (1-based as in bar file).
    $rate_matrix->remove_states(1, 5, 5, 3);    # de-dupes automatically
    # Note: former state 2 is now state 1 etc.

    # Keep only states {1, 2, 3}, remove all others. Can also de-dupe.
    $rate_matrix->keep_states(1..3);

    # Write binary matrix to file.
    open my $out_fh_bin, '>', '/path/to/output/rates.bin';
    $rate_matrix->print_as_bin($out_fh_bin);

DESCRIPTION

Parse, modify and print/write rate matrix files written by Barriers, both in text and binary format.

METHODS

Bio::RNA::Barriers::RateMatrix->new(arg_name => $arg, ...)

Constructor. Reads a rate matrix from a file / handle and creates a new rate matrix object.

Arguments:
file_name | file_handle

Source of the data to read. Pass either or both.

file_type

Specifies whether the input data is in binary or text format. Must be either 'TXT' or 'BIN'.

splice_on_parsing (optional)

Array ref of integers denoting states for which the transition rates should be parsed. All other states are skipped. This dramatically improves the performance and memory efficiency for large matrices if only a few states are relevant (e.g. only connected states).

$mat->file_name()

File from which the data was read. May be undef if it was read from a file handle.

$mat->file_type()

Specifies whether the input data is in binary or text format. Must be either 'TXT' or 'BIN'.

Bio::RNA::RateMatrix->read_text_rate_matrix($input_matrix_filehandle)

Class method. Reads a rate matrix in text format from the passed file handle and constructs a matrix (2-dim array) from it. Returns an array reference containing the parsed rate matrix.

Use this function if you do not want to use the object-oriented interface.

Bio::RNA::RateMatrix->read_bin_rate_matrix($input_matrix_filehandle)

Class method. Reads a rate matrix in binary format from the passed file handle and constructs a matrix (2-dim array) from it. Returns an array reference containing the parsed rate matrix.

Use this function if you do not want to use the object-oriented interface.

$mat->dim()

Get the dimension (= number of rows = number of columns) of the matrix.

$mat->rate_from_to($i, $j)

Get the rate from state i to state j. States are 1-based (first state = state 1) just as in the results file.

$mat->remove_states(@indices)

Remove the passed states from this rate matrix. States are 1-based (first state = state 1) just as in the results file.

$mat->connected_states()

Returns a sorted list of all states connected to the (mfe) state 1. Assumes a symmetric transition matrix (only checks path from state 1 to the other states). Quadratic runtime.

$mat->keep_connected()

Only keep the states connected to the mfe (as determined by connected_states()).

$mat->keep_states(@indices)

Remove all but the passed states from this rate matrix. States are 1-based (first state = state 1) just as in the results file. @indices may be unordered and contain duplicates.

$mat->splice(@indices)

Only keep the passed states and reorder them to match the order of @indices. In particular, the same state can be passed multiple times and will then be deep-copied. @indices may be unordered and contain duplicates.

$mat->print_as_text($out_handle)

Print this matrix as text, either to the passed handle, or to STDOUT if $out_handle is not provided.

$mat->print_as_bin()

Print this matrix as binary data, either to the passed handle, or to STDOUT if $out_handle is not provided.

Data format: matrix dimension as integer, then column by column as double.

$mat->serialize()

Return string containing binary representation of the matrix (cf. print_as_bin).

$mat->stringify()

Returns a string containing the text representation of the matrix. The overloaded double-quote operator calls this method.

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/.