2525
2626@dataclasses .dataclass (frozen = True )
2727class SeriesDef :
28- """Description of curve."""
28+ """A dataclass to describe the definition of the curve.
29+
30+ Args:
31+ fit_func: A callable that defines the fit model of this curve. The argument names
32+ in the callable are parsed to create the fit parameter list, which will appear
33+ in the analysis results. The first argument should be ``x`` that represents
34+ X-values that the experiment sweeps.
35+ filter_kwargs: Optional. Dictionary of properties that uniquely identifies this series.
36+ This dictionary is used for data processing.
37+ This must be provided when the curve analysis consists of multiple series.
38+ name: Optional. Name of this series.
39+ plot_color: Optional. String representation of the color that is used to draw fit data
40+ and data points in the output figure. This depends on the drawer class
41+ being set to the curve analysis options. Usually this conforms to the
42+ Matplotlib color names.
43+ plot_symbol: Optional. String representation of the marker shape that is used to draw
44+ data points in the output figure. This depends on the drawer class
45+ being set to the curve analysis options. Usually this conforms to the
46+ Matplotlib symbol names.
47+ canvas: Optional. Index of sub-axis in the output figure that draws this curve.
48+ This option is valid only when the drawer instance provides multi-axis drawing.
49+ model_description: Optional. Arbitrary string representation of this fit model.
50+ This string will appear in the analysis results as a part of metadata.
51+ """
2952
30- # Arbitrary callback to define the fit function. First argument should be x.
3153 fit_func : Callable
32-
33- # Keyword dictionary to define the series with circuit metadata
3454 filter_kwargs : Dict [str , Any ] = dataclasses .field (default_factory = dict )
35-
36- # Name of this series. This name will appear in the figure and raw x-y value report.
3755 name : str = "Series-0"
38-
39- # Color of this line.
4056 plot_color : str = "black"
41-
42- # Symbol to represent data points of this line.
4357 plot_symbol : str = "o"
44-
45- # Latex description of this fit model
46- model_description : Optional [str ] = None
47-
48- # Index of canvas if the result figure is multi-panel
4958 canvas : Optional [int ] = None
50-
51- # Automatically extracted signature of the fit function
52- signature : Tuple [str ] = dataclasses .field (init = False )
59+ model_description : Optional [str ] = None
60+ signature : Tuple [str , ...] = dataclasses .field (init = False )
5361
5462 def __post_init__ (self ):
5563 """Parse the fit function signature to extract the names of the variables.
@@ -65,24 +73,30 @@ def __post_init__(self):
6573
6674@dataclasses .dataclass (frozen = True )
6775class CurveData :
68- """Set of extracted experiment data."""
76+ """A dataclass that manages the multiple arrays comprising the dataset for fitting.
77+
78+ This dataset can consist of X, Y values from multiple series.
79+ To extract curve data of the particular series, :meth:`get_subset_of` can be used.
80+
81+ Args:
82+ x: X-values that experiment sweeps.
83+ y: Y-values that observed and processed by the data processor.
84+ y_err: Uncertainty of the Y-values which is created by the data processor.
85+ Usually this assumes standard error.
86+ shots: Number of shots used in the experiment to obtain the Y-values.
87+ data_allocation: List with identical size with other arrays.
88+ The value indicates the series index of the corresponding element.
89+ This is classified based upon the matching of :attr:`SeriesDef.filter_kwargs`
90+ with the circuit metadata of the corresponding data index.
91+ If metadata doesn't match with any series definition, element is filled with ``-1``.
92+ labels: List of curve labels. The list index corresponds to the series index.
93+ """
6994
70- # X data
7195 x : np .ndarray
72-
73- # Y data
7496 y : np .ndarray
75-
76- # Error bar
7797 y_err : np .ndarray
78-
79- # Shots number
8098 shots : np .ndarray
81-
82- # Maping of data index to series index
8399 data_allocation : np .ndarray
84-
85- # List of curve names
86100 labels : List [str ]
87101
88102 def get_subset_of (self , index : Union [str , int ]) -> "CurveData" :
@@ -114,37 +128,34 @@ def get_subset_of(self, index: Union[str, int]) -> "CurveData":
114128
115129@dataclasses .dataclass (frozen = True )
116130class FitData :
117- """Set of data generated by the fit function."""
131+ """A dataclass to store the outcome of the fitting.
132+
133+ Args:
134+ popt: List of optimal parameter values with uncertainties if available.
135+ popt_keys: List of parameter names being fit.
136+ pcov: Covariance matrix from the least square fitting.
137+ reduced_chisq: Reduced Chi-squared value for the fit curve.
138+ dof: Degree of freedom in this fit model.
139+ x_data: X-values provided to the fitter.
140+ y_data: Y-values provided to the fitter.
141+ """
118142
119- # Order sensitive fit parameter values
120143 popt : List [uncertainties .UFloat ]
121-
122- # Order sensitive parameter name list
123144 popt_keys : List [str ]
124-
125- # Covariance matrix
126145 pcov : np .ndarray
127-
128- # Reduced Chi-squared value of fit curve
129146 reduced_chisq : float
130-
131- # Degree of freedom
132147 dof : int
133-
134- # X data
135148 x_data : np .ndarray
136-
137- # Y data
138149 y_data : np .ndarray
139150
140151 @property
141152 def x_range (self ) -> Tuple [float , float ]:
142- """Return range of x values."""
153+ """Range of x values."""
143154 return np .min (self .x_data ), np .max (self .x_data )
144155
145156 @property
146157 def y_range (self ) -> Tuple [float , float ]:
147- """Return range of y values."""
158+ """Range of y values."""
148159 return np .min (self .y_data ), np .max (self .y_data )
149160
150161 def fitval (self , key : str ) -> uncertainties .UFloat :
@@ -169,7 +180,13 @@ def fitval(self, key: str) -> uncertainties.UFloat:
169180
170181@dataclasses .dataclass
171182class ParameterRepr :
172- """Detailed description of fitting parameter."""
183+ """Detailed description of fitting parameter.
184+
185+ Args:
186+ name: Original name of the fit parameter being defined in the fit model.
187+ repr: Optional. Human-readable parameter name shown in the analysis result and in the figure.
188+ unit: Optional. Physical unit of this parameter if applicable.
189+ """
173190
174191 # Fitter argument name
175192 name : str
0 commit comments