File: parameters.rst

package info (click to toggle)
astropy 5.2.1-2
  • links: PTS, VCS
  • area: main
  • in suites: bookworm
  • size: 41,972 kB
  • sloc: python: 219,331; ansic: 147,297; javascript: 13,556; lex: 8,496; sh: 3,319; xml: 1,622; makefile: 185
file content (229 lines) | stat: -rw-r--r-- 9,199 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
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
72
73
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
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
.. include:: links.inc

.. _modeling-parameters:

**********
Parameters
**********

Basics
======

Most models in this package are "parametric" in the sense that each subclass
of `~astropy.modeling.Model` represents an entire family of models, each
member of which is distinguished by a fixed set of parameters that fit that
model to some dependent and independent variable(s) (also referred to
throughout the package as the outputs and inputs of the model).

Parameters are used in three different contexts within this package: Basic
evaluation of models, fitting models to data, and providing information about
individual models to users (including documentation).

Most subclasses of `~astropy.modeling.Model`--specifically those implementing a
specific physical or statistical model, have a fixed set of parameters that can
be specified for instances of that model.  There are a few classes of models
(in particular polynomials) in which the number of parameters depends on some
other property of the model (the degree in the case of polynomials).

Models maintain a list of parameter names,
`~astropy.modeling.Model.param_names`.  Single parameters are instances of
`~astropy.modeling.Parameter` which provides a proxy for the actual parameter
values.  Simple mathematical operations can be performed with them, but they
also contain additional attributes specific to model parameters, such as any
constraints on their values and documentation.

Parameter values may be scalars *or* array values.  Some parameters are
required by their very nature to be arrays (such as the transformation matrix
for an `~astropy.modeling.projections.AffineTransformation2D`).  In most other
cases, however, array-valued parameters have no meaning specific to the model,
and are simply combined with input arrays during model evaluation according to
the standard `Numpy broadcasting rules`_.

Parameter constraints
=====================

`astropy.modeling` supports several types of parameter constraints. They are implemented
as properties of `~astropy.modeling.Parameter`, the class which defines all fittable
parameters, and can be set on individual parameters or on model instances.

The `astropy.modeling.Parameter.fixed` constraint is boolean and indicates
whether a parameter is kept "fixed" or "frozen" during fitting. For example, fixing the
``stddev`` of a :class:`~astropy.modeling.functional_models.Gaussian1D` model
means it will be excluded from the list of fitted parameters::

    >>> from astropy.modeling.models import Gaussian1D
    >>> g = Gaussian1D(amplitude=10.2, mean=2.3, stddev=1.2)
    >>> g.stddev.fixed
    False
    >>> g.stddev.fixed = True
    >>> g.stddev.fixed
    True

`astropy.modeling.Parameter.bounds` is a tuple of numbers
setting minimum and maximum value for a parameter. ``(None, None)`` indicates
the parameter values are not bound. ``bounds`` can be set also using the
`~astropy.modeling.Parameter.min` and
`~astropy.modeling.Parameter.max` properties. Assigning ``None`` to
the corresponding property removes the bound on the parameter. For example, setting
bounds on the ``mean`` value of a :class:`~astropy.modeling.functional_models.Gaussian1D`
model can be done either by setting ``min`` and ``max``::

    >>> g.mean.bounds
    (None, None)
    >>> g.mean.min = 2.2
    >>> g.mean.bounds
    (2.2, None)
    >>> g.mean.max = 2.4
    >>> g.mean.bounds
    (2.2, 2.4)

or using the ``bounds`` property::

    >>> g.mean.bounds = (2.2, 2.4)

`astropy.modeling.Parameter.tied` is a user supplied callable
which takes a model instance and returns a value for the parameter.  It is most useful
with setting constraints on compounds models, for example a ratio between two parameters (:ref:`example<tied>`).

Constraints can also be set when the model is initialized. For example::

    >>> g = Gaussian1D(amplitude=10.2, mean=2.3, stddev=1.2,
    ...                fixed={'stddev': True},
    ... 	        bounds={'mean': (2.2, 2.4)})
    >>> g.stddev.fixed
    True
    >>> g.mean.bounds
    (2.2, 2.4)


Parameter examples
==================

- Model classes can be introspected directly to find out what parameters they
  accept::

      >>> from astropy.modeling import models
      >>> models.Gaussian1D.param_names
      ('amplitude', 'mean', 'stddev')

  The order of the items in the ``param_names`` list is relevant--this
  is the same order in which values for those parameters should be passed in
  when constructing an instance of that model::

      >>> g = models.Gaussian1D(1.0, 0.0, 0.1)
      >>> g  # doctest: +FLOAT_CMP
      <Gaussian1D(amplitude=1.0, mean=0.0, stddev=0.1)>

  However, parameters may also be given as keyword arguments (in any order)::

      >>> g = models.Gaussian1D(mean=0.0, amplitude=2.0, stddev=0.2)
      >>> g  # doctest: +FLOAT_CMP
      <Gaussian1D(amplitude=2.0, mean=0.0, stddev=0.2)>

  So all that really matters is knowing the names (and meanings) of the
  parameters that each model accepts.  More information about an individual
  model can also be obtained using the `help` built-in::

      >>> help(models.Gaussian1D)  # doctest: +SKIP

- Some types of models can have different numbers of parameters depending
  on other properties of the model.  In particular, the parameters of
  polynomial models are their coefficients, the number of which depends on the
  polynomial's degree::

      >>> p1 = models.Polynomial1D(degree=3, c0=1.0, c1=0.0, c2=2.0, c3=3.0)
      >>> p1.param_names
      ('c0', 'c1', 'c2', 'c3')
      >>> p1  # doctest: +FLOAT_CMP
      <Polynomial1D(3, c0=1., c1=0., c2=2., c3=3.)>

  For the basic `~astropy.modeling.polynomial.Polynomial1D` class the
  parameters are named ``c0`` through ``cN`` where ``N`` is the degree of the
  polynomial.  The above example represents the polynomial :math:`3x^3 + 2x^2 +
  1`.

- Some models also have default values for one or more of their parameters.
  For polynomial models, for example, the default value of all coefficients is
  zero--this allows a polynomial instance to be created without specifying any
  of the coefficients initially::

      >>> p2 = models.Polynomial1D(degree=4)
      >>> p2  # doctest: +FLOAT_CMP
      <Polynomial1D(4, c0=0., c1=0., c2=0., c3=0., c4=0.)>

- Parameters can then be set/updated by accessing attributes on the model of
  the same names as the parameters::

      >>> p2.c4 = 1
      >>> p2.c2 = 3.5
      >>> p2.c0 = 2.0
      >>> p2  # doctest: +FLOAT_CMP
      <Polynomial1D(4, c0=2., c1=0., c2=3.5, c3=0., c4=1.)>

  This example now represents the polynomial :math:`x^4 + 3.5x^2 + 2`.

- It is possible to set the coefficients of a polynomial by passing the
  parameters in a dictionary, since all parameters can be provided as keyword
  arguments::

      >>> ch2 = models.Chebyshev2D(x_degree=2, y_degree=3)
      >>> coeffs = dict((name, [idx, idx + 10])
      ...               for idx, name in enumerate(ch2.param_names))
      >>> ch2 = models.Chebyshev2D(x_degree=2, y_degree=3, n_models=2,
      ...                          **coeffs)
      >>> ch2.param_sets  # doctest: +FLOAT_CMP
      array([[ 0., 10.],
             [ 1., 11.],
             [ 2., 12.],
             [ 3., 13.],
             [ 4., 14.],
             [ 5., 15.],
             [ 6., 16.],
             [ 7., 17.],
             [ 8., 18.],
             [ 9., 19.],
             [10., 20.],
             [11., 21.]])

- Or directly, using keyword arguments::

      >>> ch2 = models.Chebyshev2D(x_degree=2, y_degree=3,
      ...                          c0_0=[0, 10], c0_1=[3, 13],
      ...                          c0_2=[6, 16], c0_3=[9, 19],
      ...                          c1_0=[1, 11], c1_1=[4, 14],
      ...                          c1_2=[7, 17], c1_3=[10, 20,],
      ...                          c2_0=[2, 12], c2_1=[5, 15],
      ...                          c2_2=[8, 18], c2_3=[11, 21])

- Individual parameters values may be arrays of different sizes and shapes::

      >>> p3 = models.Polynomial1D(degree=2, c0=1.0, c1=[2.0, 3.0],
      ...                          c2=[[4.0, 5.0], [6.0, 7.0], [8.0, 9.0]])
      >>> p3(2.0)  # doctest: +FLOAT_CMP
      array([[21., 27.],
             [29., 35.],
             [37., 43.]])

  This is equivalent to evaluating the Numpy expression::

      >>> import numpy as np
      >>> c2 = np.array([[4.0, 5.0],
      ...                [6.0, 7.0],
      ...                [8.0, 9.0]])
      >>> c1 = np.array([2.0, 3.0])
      >>> c2 * 2.0**2 + c1 * 2.0 + 1.0  # doctest: +FLOAT_CMP
      array([[21., 27.],
             [29., 35.],
             [37., 43.]])

  Note that in most cases, when using array-valued parameters, the parameters
  must obey the standard broadcasting rules for Numpy arrays with respect to
  each other::

      >>> models.Polynomial1D(degree=2, c0=1.0, c1=[2.0, 3.0],
      ...                     c2=[4.0, 5.0, 6.0])  # doctest: +IGNORE_EXCEPTION_DETAIL
      Traceback (most recent call last):
      ...
      InputParameterError: Parameter u'c1' of shape (2,) cannot be broadcast
      with parameter u'c2' of shape (3,).  All parameter arrays must have
      shapes that are mutually compatible according to the broadcasting rules.