lib/CXGN/Cview/MapOverviews.pm

   1 =head1 NAME
   2
   3 CXGN::Cview::MapOverviews - classes to display different kinds of map overviews.
   4
   5 =head1 SYNOPSYS
   6
   7  my $overview = CXGN::MapOverview::Generic->new(
   8            CXGN::Cview::Map::SGN::Genetic->new($dbh, 9), $args_ref
   9                                                 );
  10  $overview->hilite_markers(@marker_names);
  11  $overview->render_map();
  12  $overview->get_image_html();
  13
  14
  15 =head1 DESCRIPTION
  16
  17 CXGN::Cview::MapOverviews contains a number of classes designed to display map overview images (chromosomes aligned horizontally) for a given map. The base class is an abstract class called CXGN::Cview::MapOverviews and it depends on CXGN::Cview classes for drawing the chromosomes. The subclasses derived from this class are
  18
  19 =over 5
  20
  21 =item *
  22
  23 CXGN::Cview::MapOverviews::Generic, which displays a generic overview for maps of type "genetic", "fish" or "physical" - or any other map that has an appropriate CXGN::Cview::Map object implemented.
  24
  25 =item *
  26
  27 CXGN::Cview::MapOverviews::ProjectStats displays a map showing the progress of the sequencing project. It also uses CXGN::People, to get the BAC statistics associated to the different chromosomes.
  28
  29 =back
  30
  31 =head2 Caching implementation
  32
  33 The caching is implemented using CXGN::Tools::WebImageCache, which implements caching on the file system level. Each subclass of MapOverviews can implement its own get_cache_key() function, which should should be set to a distinct key for each map. MapOverviews::Generic concatenates the map_version_id, the hilited markers, and the package name. For more information, see L<CXGN::Tools::WebImageCache>.
  34
  35 =head2 Resetting the cache
  36
  37 The cache can be reset by deleting the contents of the caching directory. The default value is set using CXGN::VHost properties basepath, tempfiles_subdir and the string "cview", which resolves to "/data/local/website/sgn/documents/tempfiles/cview/" on the current production systems (as of Dec 2006). The class also takes a $reset_cache parameter in the constructor, which will be passed to the CXGN::Tools::WebImageCache constructor. A true value will cause the cache to be considered as expired.
  38
  39 =head1 AUTHORS
  40
  41  Lukas Mueller (lam87@cornell.edu)
  42  John Binns (zombieite@gmail.com)
  43
  44 =cut
  45
  46 package CXGN::Cview::MapOverviews;
  47
  48 use strict;
  49 use warnings;
  50
  51 use File::Spec;
  52 use CXGN::People;
  53 use CXGN::Tools::WebImageCache;
  54 use CXGN::Cview;
  55 use CXGN::Cview::Chromosome;
  56 use CXGN::Cview::Chromosome::PachyteneIdiogram;
  57 use CXGN::Cview::Chromosome::Glyph;
  58 use CXGN::Cview::MapImage;
  59 use CXGN::Cview::Marker;
  60 use CXGN::Cview::Marker::RangeMarker;
  61 use CXGN::Cview::Ruler;
  62 use CXGN::Cview::Chromosome::Physical;
  63 use CXGN::Cview::Label;
  64 use CXGN::Cview::Map::Tools;
  65
  66 use CXGN::Cview::MapOverviews::Generic;
  67 use CXGN::Cview::MapOverviews::Physical;
  68 use CXGN::Cview::MapOverviews::ProjectStats;
  69 use CXGN::Cview::MapOverviews::Individual;
  70
  71 =head1 CXGN::Cview::MapOverviews
  72
  73 This class implements an abstract interface for drawing map overview images.
  74
  75 =cut
  76
  77 use CXGN::DB::Connection;
  78
  79 use base qw( CXGN::DB::Connection );
  80
  81 # an abstract class from which other overviews inherit.
  82
  83 =head2 function new()
  84
  85  Synopsis:      Constructor for MapOverview object
  86   Example:      my $map_overview = CXGN::Cview::MapOverviews::Generic
  87                                    ->new( $map_object, $args_ref );
  88  Arguments:     usually a subclass of CXGN::Cview::Map
  89                 subclasses.
  90                 the $args_ref can have the following keys (* means required)
  91                 force              forces recalculation of the image
  92                 basepath*          the basepath to use for tempfile storage
  93                 tempfiles_subdir*  the subdir, after the basepath, where
  94                                    the tempfiles are stored
  95                 dbh*               a database handle
  96
  97  Returns:       a CXGN::Cview::MapOverview object
  98  Side effects:  none
  99  Description:
 100
 101 =cut
 102
 103 sub new {
 104     my $class = shift;
 105     my $map = shift;
 106     my $args = shift;
 107
 108     my $self = bless {}, $class;
 109
 110     $self->_set_force($args->{force});
 111
 112     # define some default values
 113     #
 114     ####@{$self->{c_len}} = (0, 163, 140, 170, 130, 120, 100, 110, 90, 115, 90, 100, 120);
 115
 116     $self->set_horizontal_spacing(50);
 117
 118     # set up the cache
 119     #
 120     my $cache =  CXGN::Tools::WebImageCache->new();
 121
 122     $cache->set_force($args->{force});
 123     $cache->set_basedir($args->{basepath});
 124     $cache->set_temp_dir($args->{tempfiles_subdir});
 125
 126     $self->set_cache($cache);
 127     $self->set_image_width(700);
 128     $self->set_image_height(200);
 129
 130     return $self;
 131 }
 132
 133 =head2 accessors set_map(), get_map()
 134
 135  Synopsis:      $overview->get_map();
 136  Arguments:
 137  Returns:       gets the map object.
 138  Side effects:  the corresponding map will be represented
 139                 on the overview.
 140  Description:
 141
 142 =cut
 143
 144 sub get_map {
 145     my $self=shift;
 146     return $self->{map};
 147 }
 148
 149 sub set_map {
 150     my $self=shift;
 151     $self->{map}=shift;
 152 }
 153
 154 =head2 function set_horizontal_spacing()
 155
 156  Synopsis:      $overview->set_horizontal_spacing(60)
 157  Arguments:     the horizontal spacing in pixels
 158  Returns:       nothing
 159  Side effects:  Defines the spacing between the chromosome glyphs
 160                 in the overview image. If this is not set, the
 161                 default is 50.
 162  Description:
 163
 164 =cut
 165
 166 sub set_horizontal_spacing {
 167     my $self=shift;
 168     $self->{horizontal_spacing} = shift;
 169 }
 170
 171 =head2 function get_horizontal_spacing()
 172
 173  Synopsis:      $my_spacing = $overview->get_horizontal_spacing()
 174  Arguments:     None (accessor)
 175  Returns:       the number of pixels between the chromosome glyphs.
 176  Side effects:  None
 177  Description:
 178
 179 =cut
 180
 181 sub get_horizontal_spacing {
 182     my $self=shift;
 183     return $self->{horizontal_spacing};
 184 }
 185
 186 =head2 function render_map()
 187
 188  Synopsis:      $overview->render_map()
 189  Arguments:
 190  Returns:       nothing
 191  Side effects:  renders the map and sets two properties (see below).
 192  Description:   this function needs to be implemented in subclasses
 193                 to draw the desired map. The calculated map should be
 194                 stored directly using the cache functions
 195                 (see CXGN::Tools::WebImageCache) (essentially, using the
 196                 functions set_image_data() and set_image_map_data() ).
 197
 198                 The subclassed function should call SUPER::render_map(),
 199                 such that the key can be properly set.
 200
 201
 202 =cut
 203
 204 sub render_map {
 205     my $self = shift;
 206
 207
 208
 209 }
 210
 211 =head2 function get_file_png()
 212
 213  Synopsis:      $overview->get_file_png($path)
 214  Arguments:     a fully qualified path of the file
 215  Returns:
 216
 217  Side effects:
 218  Description:   saves the image into the specified file
 219  Status:
 220
 221 =cut
 222
 223 sub get_file_png {
 224     my $self=shift;
 225     my $path = shift;
 226
 227     $self->{map_image}->render_png_file($path);
 228 }
 229
 230 =head2 function get_image_map()
 231
 232  Synopsis:      my $html_image_map = $overview->get_image_map();
 233  Arguments:     none
 234  Returns:       an html image map, defining the links on the image
 235  Side effects:  none
 236  Description:   none
 237  Status:        DEPRECATED! USE get_image_html INSTEAD!
 238
 239 =cut
 240
 241 sub get_image_map {
 242     my $self=shift;
 243     my $map_name = shift;
 244
 245     my $map_file = ($self->get_temp_file())[1].".map";
 246
 247     if (!$self->has_cache()) {
 248         open (my $FILE, ">", $map_file) ||
 249             die "Can't open map file $map_file: $!";
 250         print $FILE $self->{image_map};
 251         close($FILE);
 252     }
 253     else {
 254         open (my $FILE, "<", $map_file) ||
 255             die "Can't open map file! $map_file";
 256         my @FILE = (<$FILE>);
 257         close($FILE);
 258         $self->{image_map} = join "\n", @FILE;
 259     }
 260     return $self->{image_map};
 261
 262 }
 263
 264 =head2 function set_image_map()
 265
 266   Synopsis:     $overview->set_image_map();
 267   Arguments:    a string representing the html image map for
 268                 the overview image (essentially, the appropriate
 269                 <map> tag that goes with the overview image).
 270   Returns:
 271   Side effects: this will be used directly to print the <map> tag
 272   Description:
 273
 274 =cut
 275
 276 sub set_image_map {
 277     my $self = shift;
 278     $self->{image_map}=shift;
 279 }
 280
 281 =head2 function get_image_html()
 282
 283   Synopsis:
 284   Arguments:    none
 285   Returns:      a string representing the image for an html page,
 286                 including image tag and image map
 287   Side effects:
 288   Description:
 289
 290 =cut
 291
 292 sub get_image_html {
 293     my $self = shift;
 294     return $self->get_cache()->get_image_html();
 295
 296 #    return '<img src="'.($self->get_file_png())[0].'" usemap="#overview" border="0" />'."<br />\n". $self->get_image_map("overview");
 297 }
 298
 299 =head2 accessors get_marker_count(), set_marker_count()
 300
 301  Synopsis:     my $count = $map->get_marker_count($chr)
 302  Arguments:    a chromosome name
 303  Returns:      the number of markers on that chromosome
 304  Side effects:
 305  Description:  needs to be implemented in a subclass.
 306
 307 =cut
 308
 309
 310 sub get_marker_count {
 311 }
 312
 313 sub set_marker_count {
 314 }
 315
 316 =head2 accessors set_map_image(), get_map_image()
 317
 318   Property:     the image object (GD::Image)
 319   Side Effects:
 320   Description:  this image object is used for drawing the image
 321
 322 =cut
 323
 324 sub get_map_image {
 325     my $self=shift;
 326     return $self->{map_image};
 327 }
 328
 329 sub set_map_image {
 330     my $self=shift;
 331     $self->{map_image}=shift;
 332 }
 333
 334 =head2 function hilite_marker()
 335
 336  Synopsis:      $overview->hilite_marker("TG280");
 337  Arguments:     a marker name (string)
 338  Returns:       nothing
 339  Side effects:  causes the marker to be highlighted on the overview
 340  Description:
 341
 342 =cut
 343
 344 sub hilite_marker {
 345     my $self = shift;
 346     my $marker_name = shift;
 347     if (!exists($self->{hilite_markers})) { @{$self->{hilite_markers}}=(); }
 348     push @{$self->{hilite_markers}}, $marker_name;
 349 }
 350
 351 sub get_hilite_markers {
 352     my $self = shift;
 353     if (!exists($self->{hilite_markers})) { @{$self->{hilite_markers}}=(); }
 354     return @{$self->{hilite_markers}};
 355 }
 356
 357 sub add_marker_not_found {
 358     my $self = shift;
 359     my $marker = shift;
 360     #
 361     # prevent these not initialized errors...
 362     #
 363     if (!exists($self->{markers_not_found})) { %{$self->{markers_not_found}}=(); }
 364     ${$self->{markers_not_found}}{$marker}=1;
 365 }
 366
 367 # return the markers that were not found for hiliting on the overview diagram
 368 # Note: render_map has to be called before calling this function.
 369 #
 370 sub get_markers_not_found {
 371     my $self = shift;
 372     if (!$self->{markers_not_found}) { %{$self->{markers_not_found}}=(); }
 373     return ( map ($_, (keys(%{$self->{markers_not_found}}))));
 374 }
 375
 376 =head2 add_map_items
 377
 378  Usage:
 379  Desc:
 380  Ret:
 381  Args:
 382  Side Effects:
 383  Example:
 384
 385 =cut
 386
 387 sub add_map_items {
 388     my $self = shift;
 389     my @map_items = @_;
 390
 391     $self->get_map()->set_map_items(@map_items);
 392
 393 }
 394
 395 =head2 accessors set_chr_height(), get_chr_height()
 396
 397   Property:     the height of the chromosome in pixels.
 398                 This is currently only used for the Project
 399                 Stats overview, in which chromosome don\'t
 400                 have a 'natural' height.
 401   Side Effects:
 402   Description:
 403
 404 =cut
 405
 406 sub get_chr_height {
 407     my $self=shift;
 408     return $self->{chr_height};
 409 }
 410
 411 sub set_chr_height {
 412     my $self=shift;
 413     $self->{chr_height}=shift;
 414 }
 415
 416 =head2 accessors set_image_height(), get_image_height()
 417
 418   Property:     The height of the image in pixels.
 419   Setter Args:
 420   Side Effects:
 421   Description:
 422
 423 =cut
 424
 425 sub get_image_height {
 426     my $self=shift;
 427     return $self->{image_height};
 428 }
 429
 430 sub set_image_height {
 431     my $self=shift;
 432     $self->{image_height}=shift;
 433 }
 434
 435 =head2 accessors set_image_width(), get_image_width()
 436
 437   Property:     the width of the entire image in pixels.
 438   Setter Args:
 439   Getter Args:
 440   Getter Ret:
 441   Side Effects:
 442   Description:
 443
 444 =cut
 445
 446 sub get_image_width {
 447     my $self=shift;
 448     return $self->{image_width};
 449 }
 450
 451 sub set_image_width {
 452     my $self=shift;
 453     $self->{image_width}=shift;
 454 }
 455
 456
 457
 458 # accessors _set_force, _get_force
 459 #
 460 # if set to true, forces the re-calculation of the image and stats.
 461 #
 462 sub _get_force {
 463     my $self=shift;
 464     return $self->{force};
 465 }
 466
 467 sub _set_force {
 468     my $self=shift;
 469     $self->{force}=shift;
 470 }
 471
 472 =head2 accessors set_cache(), get_cache()
 473
 474   Property:     a CXGN::Tools::WebImageCache object
 475   Args/Ret:     the same
 476   Side Effects:
 477   Description:  see CXGN::Tools::WebImageCache
 478
 479 =cut
 480
 481 sub get_cache {
 482     my $self=shift;
 483     return $self->{cache};
 484 }
 485
 486 sub set_cache {
 487     my $self=shift;
 488     $self->{cache}=shift;
 489 }
 490
 491 =head2 get_chromosomes(), set_chromosomes()
 492
 493  Usage:        my @c = $map->get_chromosomes();
 494  Desc:         returns (sets) a list of Cview chromosome objects for
 495                this map, in the same order as get_chromosome_names().
 496  Side Effects:
 497  Example:
 498
 499 =cut
 500
 501 sub get_chromosomes {
 502   my $self=shift;
 503   return $self->{chromosomes};
 504
 505 }
 506
 507 sub set_chromosomes {
 508   my $self=shift;
 509   $self->{chromosomes}=shift;
 510 }
 511
 512
 513 =head2 accessors set_chromosome_count, get_chromosome_count
 514
 515   Property:
 516   Setter Args:
 517   Getter Args:
 518   Getter Ret:
 519   Side Effects:
 520   Description:
 521
 522 =cut
 523
 524 sub get_chromosome_count {
 525     my $self=shift;
 526     return $self->{chromosome_count};
 527 }
 528
 529 sub set_chromosome_count {
 530     my $self=shift;
 531     $self->{chromosome_count}=shift;
 532 }
 533
 534
 535 =head2 function get_cache_key()
 536
 537  Usage:        $map->get_cache_key()
 538  Desc:         needs to be implemented in subclass and return
 539                a cache key for the current map
 540  Side Effects:
 541  Example:
 542
 543 =cut
 544
 545 sub get_cache_key {
 546     die "get_cache_key is abstract. Please implement in subclass.";
 547 }
 548
 549 1;