# 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

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

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