Coverage for src/signal_edges/plotter/definitions.py: 100%

1"""Definitions for the opinionated plotter.""" 

2 

3from collections.abc import Sequence 

4from dataclasses import dataclass 

5from enum import IntEnum, auto 

6from typing import TypeAlias 

7 

8import numpy as np 

9import numpy.typing as npt 

10 

11 

12class Mode(IntEnum): 

13 """Plotter mode provides some customization options between plots.""" 

14 

15 #: Linear plotter with independent vertical axis and horizontal axis in each plot. 

16 LINEAR = auto() 

17 #: Linear plotter with shared horizontal axis for all subplots, a single column is required. 

18 SHARED_H_AXIS = auto() 

19 

20 

21@dataclass 

22class Units: 

23 """Units provide a name, a symbol and magnitude for display. 

24 

25 :param name: The name of the units, for example, ``seconds`` for seconds. 

26 :param symbol: The symbol for the units, for example, ``s`` for seconds. 

27 :param magnitude: The magnitude the units measure, for example, ``Time`` for seconds.""" 

28 

29 name: str 

30 symbol: str 

31 magnitude: str 

32 

33 

34@dataclass 

35class Subplot: 

36 """Definition of a subplot within a plot. 

37 

38 :param name: Name of the subplot, must be unique within the plot. 

39 :param hvalues: `1xN` array with values for the horizontal axis, they must satisfy the requirement `x[n] < x[n+1]`. 

40 :param hunits: The units for the horizontal axis. 

41 :param vvalues: `1xN` array with the values for the vertical axis. 

42 :param vunits: The units for the vertical axis. 

43 :param begin: The value on the horizontal axis where the plotting starts. 

44 :param end: The value on the vertical axis where the plotting ends. 

45 :param munits: The margin units to both sides of the plot, a margin unit equals ``begin`` - ``end``. 

46 :param color: A matplotlib RGB/RGBA string or named color, such as ``#FFFFFF80`` or ``black``. 

47 :param linestyle: A matplotlib named linestyle value, such as ``solid`` or ``dashed``. 

48 :param marker: A matplotlib named marker value, such as ``none`` or ``o``.""" 

49 

50 # pylint: disable=too-many-instance-attributes 

51 

52 name: str 

53 hvalues: npt.NDArray[np.float_] 

54 hunits: Units 

55 vvalues: npt.NDArray[np.float_] 

56 vunits: Units 

57 begin: float 

58 end: float 

59 munits: float = 0.0 

60 color: str = "red" 

61 linestyle: str = "solid" 

62 marker: str = "o" 

63 

64 

65#: Type alias for a plot, a collection of subplots. 

66Plot: TypeAlias = list[Subplot] 

67#: Type alias for the plot area, accessed as ``x[row_i][column_i][plot_id]``. 

68PlotArea: TypeAlias = dict[int, dict[int, Plot]] 

69 

70 

71@dataclass 

72class Cursor: 

73 """A vertical line that marks values of interest in one or more subplots within a plot. 

74 

75 :param name: Name of the cursor for display, it is recommended to use a single character. 

76 :param hindex: The index of the horizontal value of the first subplot in the plot for the cursor. 

77 :param row: The row index of the plot. 

78 :param column: The column index of the plot. 

79 :param subplot_ids: Identifiers of the subplots for which the cursor should fetch vertical axis values. 

80 :param hvdec: Number of decimals for the value on the horizontal axis on display. 

81 :param vvdec: Number of decimals for values on the vertical axis of relevant subplots on display. 

82 :param color: A matplotlib RGB/RGBA string or named color, such as ``#FFFFFF80`` or ``black``. 

83 :param linestyle: A matplotlib named linestyle value, such as ``solid`` or ``dashed``.""" 

84 

85 # pylint: disable=too-many-instance-attributes 

86 

87 name: str 

88 hindex: int 

89 row: int 

90 column: int 

91 subplot_ids: Sequence[str] 

92 hvdec: int = 3 

93 vvdec: int = 3 

94 color: str = "#E0E0E080" 

95 linestyle: str = "dashed"