{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Optimization is more likely to converge to the maximum likelihood estimate when the user provides tight bounds containing the maximum likelihood estimate. For example, when fitting a binomial distribution to data, the number of experiments underlying each sample may be known, in which case the corresponding shape parameter " }, { "__type": "InlineCode", "__tag": 4051, "value": "n" }, { "__type": "Text", "__tag": 4046, "value": " can be fixed." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Array API Standard Support" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineRole", "__tag": 4003, "value": "fit", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " is not in-scope for support of Python Array API Standard compatible backends other than NumPy." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See " }, { "__type": "InlineRole", "__tag": 4003, "value": "dev-arrayapi", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for more information." } ] } ], "title": [], "level": 0, "target": null }, "Warns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Raises": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Yields": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Methods": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Returns": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "result", "annotation": "`~scipy.stats._result_classes.FitResult`", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An object with the following fields." } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "params" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "params" } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "success" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "success" } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "message" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "message" } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The object has the following method:" } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "nllf(params=None, data=None)" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "By default, the negative log-likelihood function at the fitted " }, { "__type": "InlineRole", "__tag": 4003, "value": "params", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for the given " }, { "__type": "ParamRef", "__tag": 4071, "name": "data" }, { "__type": "Text", "__tag": 4046, "value": ". Accepts a tuple containing alternative shapes, location, and scale of the distribution and an array of alternative data." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "plot(ax=None)" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Superposes the PDF/PMF of the fitted distribution over a normalized histogram of the data." } ] } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Fit a discrete or continuous distribution to data" } ] } ], "title": [], "level": 0, "target": null }, "Receives": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Warnings": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Attributes": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Parameters": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "dist", "annotation": "`scipy.stats.rv_continuous` or `scipy.stats.rv_discrete`", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The object representing the distribution to be fit to the data." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "data", "annotation": "1D array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The data to which the distribution is to be fit. If the data contain any of " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.nan" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.inf" }, { "__type": "Text", "__tag": 4046, "value": ", or -" }, { "__type": "InlineCode", "__tag": 4051, "value": "np.inf" }, { "__type": "Text", "__tag": 4046, "value": ", the fit method will raise a " }, { "__type": "InlineCode", "__tag": 4051, "value": "ValueError" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "bounds", "annotation": "dict or sequence of tuples, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If a dictionary, each key is the name of a parameter of the distribution, and the corresponding value is a tuple containing the lower and upper bound on that parameter. If the distribution is defined only for a finite range of values of that parameter, no entry for that parameter is required; e.g., some distributions have parameters which must be on the interval [0, 1]. Bounds for parameters location (" }, { "__type": "InlineCode", "__tag": 4051, "value": "loc" }, { "__type": "Text", "__tag": 4046, "value": ") and scale (" }, { "__type": "InlineCode", "__tag": 4051, "value": "scale" }, { "__type": "Text", "__tag": 4046, "value": ") are optional; by default, they are fixed to 0 and 1, respectively." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If a sequence, element " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "i" } ] }, { "__type": "Text", "__tag": 4046, "value": " is a tuple containing the lower and upper bound on the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "i" } ] }, { "__type": "Text", "__tag": 4046, "value": "th parameter of the distribution. In this case, bounds for " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "all" } ] }, { "__type": "Text", "__tag": 4046, "value": " distribution shape parameters must be provided. Optionally, bounds for location and scale may follow the distribution shape parameters." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If a shape is to be held fixed (e.g. if it is known), the lower and upper bounds may be equal. If a user-provided lower or upper bound is beyond a bound of the domain for which the distribution is defined, the bound of the distribution's domain will replace the user-provided value. Similarly, parameters which must be integral will be constrained to integral values within the user-provided bounds." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "guess", "annotation": "dict or array_like, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If a dictionary, each key is the name of a parameter of the distribution, and the corresponding value is a guess for the value of the parameter." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If a sequence, element " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "i" } ] }, { "__type": "Text", "__tag": 4046, "value": " is a guess for the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "i" } ] }, { "__type": "Text", "__tag": 4046, "value": "th parameter of the distribution. In this case, guesses for " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "all" } ] }, { "__type": "Text", "__tag": 4046, "value": " distribution shape parameters must be provided." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "guess" }, { "__type": "Text", "__tag": 4046, "value": " is not provided, guesses for the decision variables will not be passed to the optimizer. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "guess" }, { "__type": "Text", "__tag": 4046, "value": " is provided, guesses for any missing parameters will be set at the mean of the lower and upper bounds. Guesses for parameters which must be integral will be rounded to integral values, and guesses that lie outside the intersection of the user-provided bounds and the domain of the distribution will be clipped." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "method", "annotation": "{'mle', 'mse'}", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "With " }, { "__type": "InlineCode", "__tag": 4051, "value": "method=\"mle\"" }, { "__type": "Text", "__tag": 4046, "value": " (default), the fit is computed by minimizing the negative log-likelihood function. A large, finite penalty (rather than infinite negative log-likelihood) is applied for observations beyond the support of the distribution. With " }, { "__type": "InlineCode", "__tag": 4051, "value": "method=\"mse\"" }, { "__type": "Text", "__tag": 4046, "value": ", the fit is computed by minimizing the negative log-product spacing function. The same penalty is applied for observations beyond the support. We follow the approach of " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": ", which is generalized for samples with repeated observations." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "optimizer", "annotation": "callable, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "ParamRef", "__tag": 4071, "name": "optimizer" }, { "__type": "Text", "__tag": 4046, "value": " is a callable that accepts the following positional argument." } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "fun" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "fun" } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "ParamRef", "__tag": 4071, "name": "optimizer" }, { "__type": "Text", "__tag": 4046, "value": " must also accept the following keyword argument." } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "bounds" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "bounds" } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "guess" }, { "__type": "Text", "__tag": 4046, "value": " is provided, " }, { "__type": "ParamRef", "__tag": 4071, "name": "optimizer" }, { "__type": "Text", "__tag": 4046, "value": " must also accept the following keyword argument." } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "x0" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "x0" } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If the distribution has any shape parameters that must be integral or if the distribution is discrete and the location parameter is not fixed, " }, { "__type": "ParamRef", "__tag": 4071, "name": "optimizer" }, { "__type": "Text", "__tag": 4046, "value": " must also accept the following keyword argument." } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "integrality" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "integrality" } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "ParamRef", "__tag": 4071, "name": "optimizer" }, { "__type": "Text", "__tag": 4046, "value": " must return an object, such as an instance of " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.optimize.OptimizeResult", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.optimize._optimize:OptimizeResult" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ", which holds the optimal values of the decision variables in an attribute " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": ". If attributes " }, { "__type": "InlineCode", "__tag": 4051, "value": "fun" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "status" }, { "__type": "Text", "__tag": 4046, "value": ", or " }, { "__type": "InlineCode", "__tag": 4051, "value": "message" }, { "__type": "Text", "__tag": 4046, "value": " are provided, they will be included in the result object returned by " }, { "__type": "InlineRole", "__tag": 4003, "value": "fit", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Given a distribution, data, and bounds on the parameters of the distribution, return maximum likelihood estimates of the parameters." } ] } ], "title": [], "level": 0, "target": null }, "Other Parameters": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null } }, "_ordered_sections": [ "Summary", "Extended Summary", "Parameters", "Attributes", "Methods", "Returns", "Yields", "Receives", "Other Parameters", "Raises", "Warns", "Warnings", "Notes" ], "item_file": "/scipy/stats/_fit.py", "item_line": 317, "item_type": "function", "aliases": [ "scipy.stats.fit" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Suppose we wish to fit a distribution to the following data.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy import stats\nrng = np.random.default_rng()\ndist = stats.nbinom\nshapes = (5, 0.5)\ndata = dist.rvs(*shapes, size=1000, random_state=rng)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nSuppose we do not know how the data were generated, but we suspect that\nit follows a negative binomial distribution with parameters *n* and *p*\\.\n(See `scipy.stats.nbinom`.) We believe that the parameter *n* was fewer\nthan 30, and we know that the parameter *p* must lie on the interval\n[0, 1]. We record this information in a variable `bounds` and pass\nthis information to `fit`.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "bounds = [(0, 30), (0, 1)]\nres = stats.fit(dist, data, bounds)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n`fit` searches within the user-specified `bounds` for the\nvalues that best match the data (in the sense of maximum likelihood\nestimation). In this case, it found shape values similar to those\nfrom which the data were actually generated.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "res.params\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nWe can visualize the results by superposing the probability mass function\nof the distribution (with the shapes fit to the data) over a normalized\nhistogram of the data.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import matplotlib.pyplot as plt # matplotlib must be installed to plot\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "res.plot()\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "plt.show()\n", "execution_status": "success" }, { "__type": "Figure", "__tag": 4024, "value": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "1.17.1", "kind": "assets", "path": "fig-b0466b9787631e77.png" } }, { "__type": "Text", "__tag": 4046, "value": "\nNote that the estimate for *n* was exactly integral; this is because\nthe domain of the `nbinom` PMF includes only integral *n*, and the `nbinom`\nobject \"knows\" that. `nbinom` also knows that the shape *p* must be a\nvalue between 0 and 1. In such a case - when the domain of the distribution\nwith respect to a parameter is finite - we are not required to specify\nbounds for the parameter.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "bounds = {'n': (0, 30)} # omit parameter p using a `dict`\nres2 = stats.fit(dist, data, bounds)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "res2.params\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nIf we wish to force the distribution to be fit with *n* fixed at 6, we can\nset both the lower and upper bounds on *n* to 6. Note, however, that the\nvalue of the objective function being optimized is typically worse (higher)\nin this case.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "bounds = {'n': (6, 6)} # fix parameter `n`\nres3 = stats.fit(dist, data, bounds)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "res3.params\nres3.nllf() > res.nllf()\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nNote that the numerical results of the previous examples are typical, but\nthey may vary because the default optimizer used by `fit`,\n`scipy.optimize.differential_evolution`, is stochastic. However, we can\ncustomize the settings used by the optimizer to ensure reproducibility -\nor even use a different optimizer entirely - using the `optimizer`\nparameter.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "from scipy.optimize import differential_evolution\nrng = np.random.default_rng(767585560716548)\ndef optimizer(fun, bounds, *, integrality):\n return differential_evolution(fun, bounds, strategy='best2bin',\n rng=rng, integrality=integrality)\nbounds = [(0, 30), (0, 1)]\nres4 = stats.fit(dist, data, bounds, optimizer=optimizer)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "res4.params\n", "execution_status": "failure" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "rv_continuous", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "rv_continuous" }, "kind": "module" }, "descriptions": [], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "rv_discrete", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.stats._distn_infrastructure:rv_discrete" }, "kind": "module" }, "descriptions": [], "type": "func" } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "dist", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "data", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "bounds", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "guess", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "method", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "mle" }, { "__type": "SigParam", "__tag": 4030, "name": "optimizer", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "fit" }, "references": [ ".. [1] Shao, Yongzhao, and Marjorie G. Hahn. \"Maximum product of spacings", " method: a unified formulation with illustration of strong", " consistency.\" Illinois Journal of Mathematics 43.3 (1999): 489-499." ], "qa": "scipy.stats._fit:fit", "arbitrary": [], "local_refs": [ "bounds", "data", "dist", "guess", "method", "optimizer", "result" ] }