distance_to_nearest     package:genomeIntervals     R Documentation

_D_i_s_t_a_n_c_e _i_n _b_a_s_e_s _t_o _t_h_e _c_l_o_s_e_s_t _i_n_t_e_r_v_a_l(_s)

_D_e_s_c_r_i_p_t_i_o_n:

     Given two objects, 'from' and 'to', compute the distance in bases
     of each 'from' interval to the nearest 'to' interval(s). The
     distance between a base and the next inter-bases on either side
     values 0.5. Thus, base - base and inter-base - inter-base
     intervals distances are integer, whereas base - inter-base
     intervals distances are half-integers.

_U_s_a_g_e:

     ## S4 method for signature 'Genome_intervals,
     ##   Genome_intervals':
     distance_to_nearest(from, to)
     ## S4 method for signature 'Genome_intervals_stranded,
     ##   Genome_intervals_stranded':
     distance_to_nearest(from, to)

_A_r_g_u_m_e_n_t_s:

    from: A 'Genome_intervals' or 'Genome_intervals_stranded' object.

      to: A 'Genome_intervals' or 'Genome_intervals ' object. 

_D_e_t_a_i_l_s:

     A wrapper calling 'intervals::distance_to_nearest' by 'seq_name'
     and by 'strand' (if both 'from' and 'to' are
     'Genome_intervals_stranded' objects). Thus, if both are stranded,
     distances are computed over each strand separately. One object
     must be coerced to 'Genome_intervals' if this is not wished.

_V_a_l_u_e:

     A numeric vector of distances with one element for each row of
     'from'.

_S_e_e _A_l_s_o:

     'intervals::distance_to_nearest'

_E_x_a_m_p_l_e_s:

     ## load toy examples
     data(gen_ints)           
      
     ## i in close_intervals notation
     close_intervals(i)
      
     ## j in close_intervals notation
     close_intervals(j)
      
     ## distances from i to j 
     dn = distance_to_nearest(i,j)
     dn

     ## distance == 0 if and only if the interval overlaps another one:
     io = interval_overlap(i,j)
     if( any( ( sapply(io, length) >0 )  != (!is.na(dn) & dn ==0) ) )
             stop("The property 'distance == 0 if and only if the interval overlaps another one' is not followed for at least one instance.")
      
     ## distances without strand-specificity
     distance_to_nearest( 
                     as(i,"Genome_intervals"),
                     as(j,"Genome_intervals") 
     )       

