NAME

PDL::Graphics::Prima::Limits - defining a few useful constants for setting axis limits

DESCRIPTION

You probably won't ever need to use this module explicitly, but you will likely use the constants defined here to manipulate axis autoscaling. This module defines the constants lm::Auto and lm::Hold. If the explanation below does not make sense, these constants are also discussed in PDL::Graphics::Prima::Axis, PDL::Graphics::Prima::Simple, and elsewhere.

lm::Auto

When you set an axis's min or max to lm::Auto, you turn on min or max autoscaling:

 # Set the x-min to -5 for now...
 $plot->x->min(-5);

 # Turn on autoscaling for x-min:
 $plot->x->min(lm::Auto);

lm::Hold

DEPRECATION CANDIDATE. I am considering deprecating this limit in favor of a new limit, discussed below. If you use lm::Hold, please let me know so that I can take your concerns into consideration. It presently serves as a fairly simple shorthand that I have not actually used in any of my real code. It is easy to create the desired effect with simple code, and I have concocted a much more helpful meaning for this value, detailed under the next item, lm::NextTick.

This constant gives a shorthand for changing from autoscaling to non-autoscaling. For example, suppose you are building a plot from multiple data sets and want to autoscale based on the first few but not for the remaining. In that case you might say:

 $plot->dataSets->{'data'} = ds::Pair($x, $y);
 $plot->y->minmax(lm::Hold, lm::Hold);
 $plot->dataSets->{'model'} = ds::Func(\&my_func);

You can achieve the same ends like so:

 $plot->dataSets->{'data'} = ds::Pair($x, $y);
 $plot->y->minmax($plot->y->minmax);
 $plot->dataSets->{'model'} = ds::Func(\&my_func);

If you just wanted to set the min to hold, you could use lm::Hold like this:

 $plot->y->min(lm::Hold);

which is equivalent to:

 $plot->y->min($plot->y->min);

Also note that the return value of $plot->y-min> returns different things depending on whether you are using scalar or list context. (Yes, that's an Axis thing, not a Limits thing, but it bears repeating here anyway.)

lm::NextTick

PROPOSAL CANDIDATE. I am considering adding this functionality some time in mid to late 2013. It would use the same bit representation as what is currently lm::Hold, so this would be a backwards incompatible change. However, I am not aware of any code that actually uses lm::Hold apart from a few of my own example scripts (I don't use it in any of my production code), so I suspect it will be fine. (Or, perhaps I should actually make turning autoscaling on or off a separate axis method. Ah well, ideas, ideas. Feedback welcome.)

The proposed behavior of lm::NextTick is similar to that of lm::Auto in that the axis limits would be computed automatically from the data. The major difference is that lm::NextTick is that, having computed the "tight" automatic min and/or max, the algorithm would actually set the min and/or max to a value slightly lower and/or higher, corresponding to the value that the Tick calculator would pick for the next major tick value. The goal here would be better static figures without having to tweak the limits.

For example, when I create a default diamond plot in a containing window of 400x400 pixels with inputs $x = pdl(1.1, 18.2) and $y = pdl(10, 20), the actual axis extrema are slightly wider thant the data's min and max and come to 0.84 and 18.5, in order to accomodate the width of the diamonds. I see three tick marks at 5, 10, and 15. When lm::NextTick gets implemented, the extrema for that specification would be 0 and 20, showing tick marks at 0, 5, 10, 15, and 20.

That, at least, is the proposed specification. I imagine this would get a lot more use than lm::Hold, especially since it's not even possible at the moment.

AUTHOR

David Mertens (dcmertens.perl@gmail.com)

ADDITIONAL MODULES

Here is the full list of modules in this distribution:

PDL::Graphics::Prima

Defines the Plot widget for use in Prima applications

PDL::Graphics::Prima::Axis

Specifies the behavior of axes (but not the scaling)

PDL::Graphics::Prima::DataSet

Specifies the behavior of DataSets

PDL::Graphics::Prima::Limits

Defines the lm:: namespace

PDL::Graphics::Prima::Palette

Specifies a collection of different color palettes

PDL::Graphics::Prima::PlotType

Defines the different ways to visualize your data

PDL::Graphics::Prima::ReadLine

Encapsulates all interaction with the Term::ReadLine family of modules.

PDL::Graphics::Prima::Scaling

Specifies different kinds of scaling, including linear and logarithmic

PDL::Graphics::Prima::Simple

Defines a number of useful functions for generating simple and not-so-simple plots

PDL::Graphics::Prima::SizeSpec

Compute pixel distances from meaningful units

LICENSE AND COPYRIGHT

Unless otherwise stated, all contributions in code and documentation are copyright (c) their respective authors, all rights reserved.

Portions of this module's code are copyright (c) 2011 The Board of Trustees at the University of Illinois.

Portions of this module's code are copyright (c) 2011-2013 Northwestern University.

Portions of this module's code are copyright (c) 2013-2014 Dickinson College.

This module's documentation is copyright (c) 2011-2014 David Mertens.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.