Skip to content

docstrings

Example module with docstring content and formatting.

FirstOrderLinearModel

Bases: NamedTuple

Describes a first order linear model of the form y = m x + c

Note

If you need a single function which implements the model without storing the fitted parameters, first_order_linear.

Attributes:

Name Type Description
c float

y-intercept of the linear model
m float

gradient of the linear model

Examples:

>>> FirstOrderLinearModel(m=0.5, c=1.0)
FirstOrderLinearModel(c=1.0, m=0.5)
Source code in docs/docstrings.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
class FirstOrderLinearModel(NamedTuple):
    """
    Describes a first order linear model of the form y = m x + c

    Note:
        If you need a single function which implements the model
        without storing the fitted parameters,
        [`first_order_linear`][docs.docstrings.first_order_linear].

    Attributes:
        c: y-intercept of the linear model
        m: gradient of the linear model

    Examples:
        >>> FirstOrderLinearModel(m=0.5, c=1.0)
        FirstOrderLinearModel(c=1.0, m=0.5)

    """

    c: float
    m: float

    def __call__(self, x: np.ndarray) -> np.ndarray:
        """
        Evaluate the model at locations X.

        Arguments:
            x: locations on the x-axis

        Returns:
            y: values

        Examples:
            >>> model = FirstOrderLinearModel(m=0.5, c=1)
            >>> model(np.array([0., 1., 2.]))
            array([1. , 1.5, 2. ])

        """
        y = first_order_linear(x, c=self.c, m=self.m)
        return y

__call__(x)

Evaluate the model at locations X.

Parameters:

Name Type Description Default
x np.ndarray

locations on the x-axis

 required

Returns:

Name Type Description
y np.ndarray

values

Examples:

>>> model = FirstOrderLinearModel(m=0.5, c=1)
>>> model(np.array([0., 1., 2.]))
array([1. , 1.5, 2. ])
Source code in docs/docstrings.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
def __call__(self, x: np.ndarray) -> np.ndarray:
    """
    Evaluate the model at locations X.

    Arguments:
        x: locations on the x-axis

    Returns:
        y: values

    Examples:
        >>> model = FirstOrderLinearModel(m=0.5, c=1)
        >>> model(np.array([0., 1., 2.]))
        array([1. , 1.5, 2. ])

    """
    y = first_order_linear(x, c=self.c, m=self.m)
    return y

curve_fitting_function(x, y, max_iterations=25, starting_m=0, starting_c=0)

Fits a first order linear model of form y = m x + c using the modified Powell method, and ensuring that the fitted model only includes as much precision as is sensible from the data.

Parameters:

Name Type Description Default
x np.ndarray

input x-values

 required
y np.ndarray

input y-values

 required
max_iterations int

maximum number of optimization steps to use

 25

Returns:

Name Type Description
model FirstOrderLinearModel

Callable which includes the fitted parameters as attributes.

Examples:

>>> x = np.linspace(-1., 1., 100)
>>> noise = np.random.RandomState(42).normal(loc=0., scale=0.1, size=100)
>>> y = first_order_linear(x, c=1.234, m=5.678) + noise
>>> curve_fitting_function(x, y, max_iterations=10)
FirstOrderLinearModel(c=1.2, m=5.7)
Source code in docs/docstrings.py 
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
def curve_fitting_function(
    x: np.ndarray,
    y: np.ndarray,
    max_iterations: int = 25,
    starting_m: float = 0,
    starting_c: float = 0,
) -> FirstOrderLinearModel:
    """
    Fits a first order linear model of form y = m x + c using the modified Powell method,
    and ensuring that the fitted model only includes as much precision as is sensible
    from the data.

    Arguments:
        x: input x-values
        y: input y-values
        max_iterations: maximum number of optimization steps to use

    Returns:
        model: Callable which includes the fitted parameters as attributes.

    Examples:
        >>> x = np.linspace(-1., 1., 100)
        >>> noise = np.random.RandomState(42).normal(loc=0., scale=0.1, size=100)
        >>> y = first_order_linear(x, c=1.234, m=5.678) + noise
        >>> curve_fitting_function(x, y, max_iterations=10)
        FirstOrderLinearModel(c=1.2, m=5.7)
    """

    # The data sometimes have large outliers, making the L2-norm less useful.
    # We use the L1-norm to be more robust to outliers.
    def l1(params):
        l1_norm = np.sum(np.abs(y - first_order_linear(x, c=params[0], m=params[1])))
        return l1_norm

    results = scipy.optimize.minimize(
        fun=l1,
        x0=(starting_c, starting_m),
        method="Powell",
        options=dict(maxiter=max_iterations),
    )

    # The results of the minimizer are floats with a very high precision,
    # potentially much higher than we would be confident reporting.
    # A rule of thumb is that we get one significant figure of precision for each step of 10x
    # in the dataset size. We round the data to that precision.
    significant_figures = np.round(np.log10(x.shape[0])).astype(int)

    model = FirstOrderLinearModel(
        c=_round_significant_figures(results.x[0], significant_figures),
        m=_round_significant_figures(results.x[1], significant_figures),
    )

    return model

first_order_linear(x, c, m)

Evaluate a first order linear model of the form y = m x + c.

Parameters:

Name Type Description Default
x Union[float, np.ndarray]

input location(s) on the x-axis

 required
c float

y-intercept of the linear model

 required
m float

gradient of the linear model

 required

Returns:

Name Type Description
y Union[float, np.ndarray]

result y = m x + c, the same shape and type as x

Examples:

>>> first_order_linear(0. , 1. , 0. )
1.0
>>> first_order_linear(np.array([-1. , 0. , 1. ]), c=1.0, m=2.0)
array([-1.,  1.,  3.])
Source code in docs/docstrings.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
def first_order_linear(
    x: Union[float, np.ndarray], c: float, m: float
) -> Union[float, np.ndarray]:
    """
    Evaluate a first order linear model of the form y = m x + c.

    Arguments:
        x: input location(s) on the x-axis
        c: y-intercept of the linear model
        m: gradient of the linear model

    Returns:
        y: result y = m x + c, the same shape and type as x

    Examples:
        >>> first_order_linear(0. , 1. , 0. )
        1.0
        >>> first_order_linear(np.array([-1. , 0. , 1. ]), c=1.0, m=2.0)
        array([-1.,  1.,  3.])
    """
    y = m * x + c
    return y