File Coverage

blib/lib/Lab/Moose/Instrument/AdjustRange.pm
Criterion Covered Total %
statement 14 37 37.8
branch 0 10 0.0
condition n/a
subroutine 5 6 83.3
pod 1 1 100.0
total 20 54 37.0


line stmt bran cond sub pod time code
1             package Lab::Moose::Instrument::AdjustRange;
2             $Lab::Moose::Instrument::AdjustRange::VERSION = '3.900';
3             #ABSTRACT: Role for automatic adjustment of measurement ranges.
4              
5 2     2   2746 use v5.20;
  2         9  
6              
7 2     2   13 use Moose::Role;
  2         5  
  2         17  
8 2     2   11016 use MooseX::Params::Validate;
  2         5  
  2         18  
9 2     2   973 use Lab::Moose::Instrument 'setter_params';
  2         4  
  2         123  
10              
11 2     2   14 use Carp;
  2         5  
  2         615  
12              
13             requires qw/allowed_ranges set_range get_cached_range/;
14              
15              
16             sub adjust_measurement_range {
17 0     0 1   my $self = shift;
18 0           my ( $value, $verbose, $ranges, $safety_factor ) = validated_list(
19             \@_,
20             value => { isa => 'Num' },
21             verbose => { isa => 'Bool', default => 1 },
22             ranges => { isa => 'ArrayRef[Num]', optional => 1 },
23             safety_factor => { isa => 'Num', default => 1 },
24             );
25              
26 0           $value = abs($value);
27              
28 0           my @ranges;
29 0 0         if ( defined $ranges ) {
30 0           @ranges = @{$ranges};
  0            
31             }
32             else {
33 0           @ranges = @{ $self->allowed_ranges };
  0            
34             }
35              
36 0           @ranges = sort @ranges; # ascending order
37              
38 0           my $current_range = $self->get_cached_range();
39 0           my $new_range;
40              
41 0           for my $range (@ranges) {
42 0 0         if ( $value <= $safety_factor * $range ) {
43 0           $new_range = $range;
44 0           last;
45             }
46             }
47              
48 0 0         if ( not defined $new_range ) {
49              
50             # use maximum range
51 0           $new_range = $ranges[-1];
52             }
53              
54 0 0         if ( $new_range != $current_range ) {
55 0 0         if ($verbose) {
56 0           carp
57             "Adjusting range from $current_range to $new_range (current value: $value)";
58             }
59 0           $self->set_range( value => $new_range );
60             }
61 0           return $current_range;
62             }
63              
64              
65             1;
66              
67             __END__
68              
69             =pod
70              
71             =encoding UTF-8
72              
73             =head1 NAME
74              
75             Lab::Moose::Instrument::AdjustRange - Role for automatic adjustment of measurement ranges.
76              
77             =head1 VERSION
78              
79             version 3.900
80              
81             =head1 DESCRIPTION
82              
83             This role provides the C<'adjust_measurement_range'> method,
84             which selects a measurement range suitable for the current input signal.
85              
86             =head1 METHODS
87              
88             =head2 adjust_measurement_range
89              
90             my $value = $instrument->get_value();
91             my $old_range = $instrument->adjust_measurement_range(
92             value => $value,
93             verbose => 1,
94             );
95             my $new_range = $instrument->get_range();
96              
97             To limit the allowed ranges, supply an arrayref with allowed ranges:
98              
99             $instrument->adjust_measurement_range(
100             value => ...,
101             allowed_ranges => [0.1, 10],
102             );
103              
104             If C<verbose> is set, carp whenever the measurement range is changed.
105              
106             By default, the range is changed, whenever the signal exceeds 100% of the measurement range, this factor can be adjusted with the C<safety_factor> attribute.
107              
108             $instrument->adjust_measurement_range(
109             ...,
110             ...,
111             safety_factor => 0.8, # change range when signal is at 80% of current range
112             );
113              
114             =head1 REQUIRED METHODS
115              
116             =head2 allowed_ranges
117              
118             Arrayref with allowed ranges
119              
120             =head2 set_range
121              
122             $instrument->set_range(value => $new_range);
123              
124             Set measurement range.
125              
126             =head2 get_range
127              
128             $instrument->get_cached_range();
129              
130             Get current range from cache.
131              
132             =head1 COPYRIGHT AND LICENSE
133              
134             This software is copyright (c) 2023 by the Lab::Measurement team; in detail:
135              
136             Copyright 2018 Simon Reinhardt
137             2020 Andreas K. Huettel
138              
139              
140             This is free software; you can redistribute it and/or modify it under
141             the same terms as the Perl 5 programming language system itself.
142              
143             =cut