dev/developers/develop.html



<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  <meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<meta property="og:title" content="Developing scikit-learn estimators" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://scikit-learn/stable/developers/develop.html" />
<meta property="og:site_name" content="scikit-learn" />
<meta property="og:description" content="Whether you are proposing an estimator for inclusion in scikit-learn, developing a separate package compatible with scikit-learn, or implementing custom components for your own projects, this chapt..." />
<meta property="og:image" content="https://scikit-learn.org/stable/_static/scikit-learn-logo-small.png" />
<meta property="og:image:alt" content="scikit-learn" />
<meta name="description" content="Whether you are proposing an estimator for inclusion in scikit-learn, developing a separate package compatible with scikit-learn, or implementing custom components for your own projects, this chapt..." />

  <meta name="viewport" content="width=device-width, initial-scale=1.0">

  
  <title>Developing scikit-learn estimators &mdash; scikit-learn 1.4.dev0 documentation</title>
  
  <link rel="canonical" href="http://scikit-learn.org/stable/developers/develop.html" />

  
  <link rel="shortcut icon" href="../_static/favicon.ico"/>
  

  <link rel="stylesheet" href="../_static/css/vendor/bootstrap.min.css" type="text/css" />
  <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
  <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
  <link rel="stylesheet" href="../_static/copybutton.css" type="text/css" />
  <link rel="stylesheet" href="../_static/plot_directive.css" type="text/css" />
  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Vibur" type="text/css" />
  <link rel="stylesheet" href="../_static/jupyterlite_sphinx.css" type="text/css" />
  <link rel="stylesheet" href="../_static/sg_gallery.css" type="text/css" />
  <link rel="stylesheet" href="../_static/sg_gallery-binder.css" type="text/css" />
  <link rel="stylesheet" href="../_static/sg_gallery-dataframe.css" type="text/css" />
  <link rel="stylesheet" href="../_static/sg_gallery-rendered-html.css" type="text/css" />
  <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/js/vendor/jquery-3.6.3.slim.min.js"></script> 
</head>
<body>


<nav id="navbar" class="sk-docs-navbar navbar navbar-expand-md navbar-light bg-light py-0">
  <div class="container-fluid sk-docs-container px-0">
      <a class="navbar-brand py-0" href="../index.html">
        <img
          class="sk-brand-img"
          src="../_static/scikit-learn-logo-small.png"
          alt="logo"/>
      </a>
    <button
      id="sk-navbar-toggler"
      class="navbar-toggler"
      type="button"
      data-toggle="collapse"
      data-target="#navbarSupportedContent"
      aria-controls="navbarSupportedContent"
      aria-expanded="false"
      aria-label="Toggle navigation"
    >
      <span class="navbar-toggler-icon"></span>
    </button>

    <div class="sk-navbar-collapse collapse navbar-collapse" id="navbarSupportedContent">
      <ul class="navbar-nav mr-auto">
        <li class="nav-item">
          <a class="sk-nav-link nav-link" href="../install.html">Install</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link" href="../user_guide.html">User Guide</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link" href="../modules/classes.html">API</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link" href="../auto_examples/index.html">Examples</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link" target="_blank" rel="noopener noreferrer" href="https://blog.scikit-learn.org/">Community</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link nav-more-item-mobile-items" href="../getting_started.html" >Getting Started</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link nav-more-item-mobile-items" href="../tutorial/index.html" >Tutorial</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link nav-more-item-mobile-items" href="../whats_new/v1.4.html" >What's new</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link nav-more-item-mobile-items" href="../glossary.html" >Glossary</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link nav-more-item-mobile-items" href="index.html" >Development</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link nav-more-item-mobile-items" href="../faq.html" >FAQ</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link nav-more-item-mobile-items" href="../support.html" >Support</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link nav-more-item-mobile-items" href="../related_projects.html" >Related packages</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link nav-more-item-mobile-items" href="../roadmap.html" >Roadmap</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link nav-more-item-mobile-items" href="../governance.html" >Governance</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link nav-more-item-mobile-items" href="../about.html" >About us</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link nav-more-item-mobile-items" href="https://github.com/scikit-learn/scikit-learn" >GitHub</a>
        </li>
        <li class="nav-item">
          <a class="sk-nav-link nav-link nav-more-item-mobile-items" href="https://scikit-learn.org/dev/versions.html" >Other Versions and Download</a>
        </li>
        <li class="nav-item dropdown nav-more-item-dropdown">
          <a class="sk-nav-link nav-link dropdown-toggle" href="#" id="navbarDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">More</a>
          <div class="dropdown-menu" aria-labelledby="navbarDropdown">
              <a class="sk-nav-dropdown-item dropdown-item" href="../getting_started.html" >Getting Started</a>
              <a class="sk-nav-dropdown-item dropdown-item" href="../tutorial/index.html" >Tutorial</a>
              <a class="sk-nav-dropdown-item dropdown-item" href="../whats_new/v1.4.html" >What's new</a>
              <a class="sk-nav-dropdown-item dropdown-item" href="../glossary.html" >Glossary</a>
              <a class="sk-nav-dropdown-item dropdown-item" href="index.html" >Development</a>
              <a class="sk-nav-dropdown-item dropdown-item" href="../faq.html" >FAQ</a>
              <a class="sk-nav-dropdown-item dropdown-item" href="../support.html" >Support</a>
              <a class="sk-nav-dropdown-item dropdown-item" href="../related_projects.html" >Related packages</a>
              <a class="sk-nav-dropdown-item dropdown-item" href="../roadmap.html" >Roadmap</a>
              <a class="sk-nav-dropdown-item dropdown-item" href="../governance.html" >Governance</a>
              <a class="sk-nav-dropdown-item dropdown-item" href="../about.html" >About us</a>
              <a class="sk-nav-dropdown-item dropdown-item" href="https://github.com/scikit-learn/scikit-learn" >GitHub</a>
              <a class="sk-nav-dropdown-item dropdown-item" href="https://scikit-learn.org/dev/versions.html" >Other Versions and Download</a>
          </div>
        </li>
      </ul>
      <div id="searchbox" role="search">
          <div class="searchformwrapper">
          <form class="search" action="../search.html" method="get">
            <input class="sk-search-text-input" type="text" name="q" aria-labelledby="searchlabel" />
            <input class="sk-search-text-btn" type="submit" value="Go" />
          </form>
          </div>
      </div>
    </div>
  </div>
</nav>
<div class="d-flex" id="sk-doc-wrapper">
    <input type="checkbox" name="sk-toggle-checkbox" id="sk-toggle-checkbox">
    <label id="sk-sidemenu-toggle" class="sk-btn-toggle-toc btn sk-btn-primary" for="sk-toggle-checkbox">Toggle Menu</label>
    <div id="sk-sidebar-wrapper" class="border-right">
      <div class="sk-sidebar-toc-wrapper">
        <div class="btn-group w-100 mb-2" role="group" aria-label="rellinks">
            <a href="minimal_reproducer.html" role="button" class="btn sk-btn-rellink py-1" sk-rellink-tooltip="Crafting a minimal reproducer for scikit-learn">Prev</a><a href="index.html" role="button" class="btn sk-btn-rellink py-1" sk-rellink-tooltip="Developer’s Guide">Up</a>
            <a href="tips.html" role="button" class="btn sk-btn-rellink py-1" sk-rellink-tooltip="Developers’ Tips and Tricks">Next</a>
        </div>
        <div class="alert alert-danger p-1 mb-2" role="alert">
          <p class="text-center mb-0">
          <strong>scikit-learn 1.4.dev0</strong><br/>
          <a href="http://scikit-learn.org/dev/versions.html">Other versions</a>
          </p>
        </div>
        <div class="alert alert-warning p-1 mb-2" role="alert">
          <p class="text-center mb-0">
            Please <a class="font-weight-bold" href="../about.html#citing-scikit-learn"><string>cite us</string></a> if you use the software.
          </p>
        </div>
            <div class="sk-sidebar-toc">
              <ul>
<li><a class="reference internal" href="#">Developing scikit-learn estimators</a><ul>
<li><a class="reference internal" href="#apis-of-scikit-learn-objects">APIs of scikit-learn objects</a><ul>
<li><a class="reference internal" href="#different-objects">Different objects</a></li>
<li><a class="reference internal" href="#estimators">Estimators</a><ul>
<li><a class="reference internal" href="#instantiation">Instantiation</a></li>
<li><a class="reference internal" href="#fitting">Fitting</a></li>
<li><a class="reference internal" href="#estimated-attributes">Estimated Attributes</a></li>
<li><a class="reference internal" href="#optional-arguments">Optional Arguments</a></li>
<li><a class="reference internal" href="#universal-attributes">Universal attributes</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#rolling-your-own-estimator">Rolling your own estimator</a><ul>
<li><a class="reference internal" href="#get-params-and-set-params">get_params and set_params</a></li>
<li><a class="reference internal" href="#parameters-and-init">Parameters and init</a></li>
<li><a class="reference internal" href="#cloning">Cloning</a></li>
<li><a class="reference internal" href="#pipeline-compatibility">Pipeline compatibility</a></li>
<li><a class="reference internal" href="#estimator-types">Estimator types</a></li>
<li><a class="reference internal" href="#specific-models">Specific models</a></li>
<li><a class="reference internal" href="#estimator-tags">Estimator Tags</a></li>
</ul>
</li>
<li><a class="reference internal" href="#developer-api-for-set-output">Developer API for <code class="docutils literal notranslate"><span class="pre">set_output</span></code></a></li>
<li><a class="reference internal" href="#developer-api-for-check-is-fitted">Developer API for <code class="docutils literal notranslate"><span class="pre">check_is_fitted</span></code></a></li>
<li><a class="reference internal" href="#coding-guidelines">Coding guidelines</a><ul>
<li><a class="reference internal" href="#input-validation">Input validation</a></li>
<li><a class="reference internal" href="#random-numbers">Random Numbers</a></li>
<li><a class="reference internal" href="#numerical-assertions-in-tests">Numerical assertions in tests</a></li>
</ul>
</li>
</ul>
</li>
</ul>

            </div>
      </div>
    </div>
    <div id="sk-page-content-wrapper">
      <div class="sk-page-content container-fluid body px-md-3" role="main">
        
  <section id="developing-scikit-learn-estimators">
<span id="develop"></span><h1>Developing scikit-learn estimators<a class="headerlink" href="#developing-scikit-learn-estimators" title="Permalink to this heading">¶</a></h1>
<p>Whether you are proposing an estimator for inclusion in scikit-learn,
developing a separate package compatible with scikit-learn, or
implementing custom components for your own projects, this chapter
details how to develop objects that safely interact with scikit-learn
Pipelines and model selection tools.</p>
<section id="apis-of-scikit-learn-objects">
<span id="api-overview"></span><h2>APIs of scikit-learn objects<a class="headerlink" href="#apis-of-scikit-learn-objects" title="Permalink to this heading">¶</a></h2>
<p>To have a uniform API, we try to have a common basic API for all the
objects. In addition, to avoid the proliferation of framework code, we
try to adopt simple conventions and limit to a minimum the number of
methods an object must implement.</p>
<p>Elements of the scikit-learn API are described more definitively in the
<a class="reference internal" href="../glossary.html#glossary"><span class="std std-ref">Glossary of Common Terms and API Elements</span></a>.</p>
<section id="different-objects">
<h3>Different objects<a class="headerlink" href="#different-objects" title="Permalink to this heading">¶</a></h3>
<p>The main objects in scikit-learn are (one class can implement
multiple interfaces):</p>
<dl class="field-list">
<dt class="field-odd">Estimator<span class="colon">:</span></dt>
<dd class="field-odd"><p>The base object, implements a <code class="docutils literal notranslate"><span class="pre">fit</span></code> method to learn from data, either:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">estimator</span> <span class="o">=</span> <span class="n">estimator</span><span class="o">.</span><span class="n">fit</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">targets</span><span class="p">)</span>
</pre></div>
</div>
<p>or:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">estimator</span> <span class="o">=</span> <span class="n">estimator</span><span class="o">.</span><span class="n">fit</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
</pre></div>
</div>
</dd>
<dt class="field-even">Predictor<span class="colon">:</span></dt>
<dd class="field-even"><p>For supervised learning, or some unsupervised problems, implements:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">prediction</span> <span class="o">=</span> <span class="n">predictor</span><span class="o">.</span><span class="n">predict</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
</pre></div>
</div>
<p>Classification algorithms usually also offer a way to quantify certainty
of a prediction, either using <code class="docutils literal notranslate"><span class="pre">decision_function</span></code> or <code class="docutils literal notranslate"><span class="pre">predict_proba</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">probability</span> <span class="o">=</span> <span class="n">predictor</span><span class="o">.</span><span class="n">predict_proba</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
</pre></div>
</div>
</dd>
<dt class="field-odd">Transformer<span class="colon">:</span></dt>
<dd class="field-odd"><p>For filtering or modifying the data, in a supervised or unsupervised
way, implements:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">new_data</span> <span class="o">=</span> <span class="n">transformer</span><span class="o">.</span><span class="n">transform</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
</pre></div>
</div>
<p>When fitting and transforming can be performed much more efficiently
together than separately, implements:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">new_data</span> <span class="o">=</span> <span class="n">transformer</span><span class="o">.</span><span class="n">fit_transform</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
</pre></div>
</div>
</dd>
<dt class="field-even">Model<span class="colon">:</span></dt>
<dd class="field-even"><p>A model that can give a <a class="reference external" href="https://en.wikipedia.org/wiki/Goodness_of_fit">goodness of fit</a>
measure or a likelihood of unseen data, implements (higher is better):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">score</span> <span class="o">=</span> <span class="n">model</span><span class="o">.</span><span class="n">score</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
</pre></div>
</div>
</dd>
</dl>
</section>
<section id="estimators">
<h3>Estimators<a class="headerlink" href="#estimators" title="Permalink to this heading">¶</a></h3>
<p>The API has one predominant object: the estimator. An estimator is an
object that fits a model based on some training data and is capable of
inferring some properties on new data. It can be, for instance, a
classifier or a regressor. All estimators implement the fit method:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">estimator</span><span class="o">.</span><span class="n">fit</span><span class="p">(</span><span class="n">X</span><span class="p">,</span> <span class="n">y</span><span class="p">)</span>
</pre></div>
</div>
<p>All built-in estimators also have a <code class="docutils literal notranslate"><span class="pre">set_params</span></code> method, which sets
data-independent parameters (overriding previous parameter values passed
to <code class="docutils literal notranslate"><span class="pre">__init__</span></code>).</p>
<p>All estimators in the main scikit-learn codebase should inherit from
<code class="docutils literal notranslate"><span class="pre">sklearn.base.BaseEstimator</span></code>.</p>
<section id="instantiation">
<h4>Instantiation<a class="headerlink" href="#instantiation" title="Permalink to this heading">¶</a></h4>
<p>This concerns the creation of an object. The object’s <code class="docutils literal notranslate"><span class="pre">__init__</span></code> method
might accept constants as arguments that determine the estimator’s behavior
(like the C constant in SVMs). It should not, however, take the actual training
data as an argument, as this is left to the <code class="docutils literal notranslate"><span class="pre">fit()</span></code> method:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">clf2</span> <span class="o">=</span> <span class="n">SVC</span><span class="p">(</span><span class="n">C</span><span class="o">=</span><span class="mf">2.3</span><span class="p">)</span>
<span class="n">clf3</span> <span class="o">=</span> <span class="n">SVC</span><span class="p">([[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">],</span> <span class="p">[</span><span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">]],</span> <span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">])</span> <span class="c1"># WRONG!</span>
</pre></div>
</div>
<p>The arguments accepted by <code class="docutils literal notranslate"><span class="pre">__init__</span></code> should all be keyword arguments
with a default value. In other words, a user should be able to instantiate
an estimator without passing any arguments to it. The arguments should all
correspond to hyperparameters describing the model or the optimisation
problem the estimator tries to solve. These initial arguments (or parameters)
are always remembered by the estimator.
Also note that they should not be documented under the “Attributes” section,
but rather under the “Parameters” section for that estimator.</p>
<p>In addition, <strong>every keyword argument accepted by</strong> <code class="docutils literal notranslate"><span class="pre">__init__</span></code> <strong>should
correspond to an attribute on the instance</strong>. Scikit-learn relies on this to
find the relevant attributes to set on an estimator when doing model selection.</p>
<p>To summarize, an <code class="docutils literal notranslate"><span class="pre">__init__</span></code> should look like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">param1</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">param2</span><span class="o">=</span><span class="mi">2</span><span class="p">):</span>
    <span class="bp">self</span><span class="o">.</span><span class="n">param1</span> <span class="o">=</span> <span class="n">param1</span>
    <span class="bp">self</span><span class="o">.</span><span class="n">param2</span> <span class="o">=</span> <span class="n">param2</span>
</pre></div>
</div>
<p>There should be no logic, not even input validation,
and the parameters should not be changed.
The corresponding logic should be put where the parameters are used,
typically in <code class="docutils literal notranslate"><span class="pre">fit</span></code>.
The following is wrong:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">param1</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">param2</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">param3</span><span class="o">=</span><span class="mi">3</span><span class="p">):</span>
    <span class="c1"># WRONG: parameters should not be modified</span>
    <span class="k">if</span> <span class="n">param1</span> <span class="o">&gt;</span> <span class="mi">1</span><span class="p">:</span>
        <span class="n">param2</span> <span class="o">+=</span> <span class="mi">1</span>
    <span class="bp">self</span><span class="o">.</span><span class="n">param1</span> <span class="o">=</span> <span class="n">param1</span>
    <span class="c1"># WRONG: the object&#39;s attributes should have exactly the name of</span>
    <span class="c1"># the argument in the constructor</span>
    <span class="bp">self</span><span class="o">.</span><span class="n">param3</span> <span class="o">=</span> <span class="n">param2</span>
</pre></div>
</div>
<p>The reason for postponing the validation is that the same validation
would have to be performed in <code class="docutils literal notranslate"><span class="pre">set_params</span></code>,
which is used in algorithms like <code class="docutils literal notranslate"><span class="pre">GridSearchCV</span></code>.</p>
</section>
<section id="fitting">
<h4>Fitting<a class="headerlink" href="#fitting" title="Permalink to this heading">¶</a></h4>
<p>The next thing you will probably want to do is to estimate some
parameters in the model. This is implemented in the <code class="docutils literal notranslate"><span class="pre">fit()</span></code> method.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">fit()</span></code> method takes the training data as arguments, which can be one
array in the case of unsupervised learning, or two arrays in the case
of supervised learning.</p>
<p>Note that the model is fitted using <code class="docutils literal notranslate"><span class="pre">X</span></code> and <code class="docutils literal notranslate"><span class="pre">y</span></code>, but the object holds no
reference to <code class="docutils literal notranslate"><span class="pre">X</span></code> and <code class="docutils literal notranslate"><span class="pre">y</span></code>. There are, however, some exceptions to this, as in
the case of precomputed kernels where this data must be stored for use by
the predict method.</p>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Parameters</p></th>
<th class="head"></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>X</p></td>
<td><p>array-like of shape (n_samples, n_features)</p></td>
</tr>
<tr class="row-odd"><td><p>y</p></td>
<td><p>array-like of shape (n_samples,)</p></td>
</tr>
<tr class="row-even"><td><p>kwargs</p></td>
<td><p>optional data-dependent parameters</p></td>
</tr>
</tbody>
</table>
<p><code class="docutils literal notranslate"><span class="pre">X.shape[0]</span></code> should be the same as <code class="docutils literal notranslate"><span class="pre">y.shape[0]</span></code>. If this requisite
is not met, an exception of type <code class="docutils literal notranslate"><span class="pre">ValueError</span></code> should be raised.</p>
<p><code class="docutils literal notranslate"><span class="pre">y</span></code> might be ignored in the case of unsupervised learning. However, to
make it possible to use the estimator as part of a pipeline that can
mix both supervised and unsupervised transformers, even unsupervised
estimators need to accept a <code class="docutils literal notranslate"><span class="pre">y=None</span></code> keyword argument in
the second position that is just ignored by the estimator.
For the same reason, <code class="docutils literal notranslate"><span class="pre">fit_predict</span></code>, <code class="docutils literal notranslate"><span class="pre">fit_transform</span></code>, <code class="docutils literal notranslate"><span class="pre">score</span></code>
and <code class="docutils literal notranslate"><span class="pre">partial_fit</span></code> methods need to accept a <code class="docutils literal notranslate"><span class="pre">y</span></code> argument in
the second place if they are implemented.</p>
<p>The method should return the object (<code class="docutils literal notranslate"><span class="pre">self</span></code>). This pattern is useful
to be able to implement quick one liners in an IPython session such as:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">y_predicted</span> <span class="o">=</span> <span class="n">SVC</span><span class="p">(</span><span class="n">C</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span><span class="o">.</span><span class="n">fit</span><span class="p">(</span><span class="n">X_train</span><span class="p">,</span> <span class="n">y_train</span><span class="p">)</span><span class="o">.</span><span class="n">predict</span><span class="p">(</span><span class="n">X_test</span><span class="p">)</span>
</pre></div>
</div>
<p>Depending on the nature of the algorithm, <code class="docutils literal notranslate"><span class="pre">fit</span></code> can sometimes also
accept additional keywords arguments. However, any parameter that can
have a value assigned prior to having access to the data should be an
<code class="docutils literal notranslate"><span class="pre">__init__</span></code> keyword argument. <strong>fit parameters should be restricted
to directly data dependent variables</strong>. For instance a Gram matrix or
an affinity matrix which are precomputed from the data matrix <code class="docutils literal notranslate"><span class="pre">X</span></code> are
data dependent. A tolerance stopping criterion <code class="docutils literal notranslate"><span class="pre">tol</span></code> is not directly
data dependent (although the optimal value according to some scoring
function probably is).</p>
<p>When <code class="docutils literal notranslate"><span class="pre">fit</span></code> is called, any previous call to <code class="docutils literal notranslate"><span class="pre">fit</span></code> should be ignored. In
general, calling <code class="docutils literal notranslate"><span class="pre">estimator.fit(X1)</span></code> and then <code class="docutils literal notranslate"><span class="pre">estimator.fit(X2)</span></code> should
be the same as only calling <code class="docutils literal notranslate"><span class="pre">estimator.fit(X2)</span></code>. However, this may not be
true in practice when <code class="docutils literal notranslate"><span class="pre">fit</span></code> depends on some random process, see
<a class="reference internal" href="../glossary.html#term-random_state"><span class="xref std std-term">random_state</span></a>. Another exception to this rule is when the
hyper-parameter <code class="docutils literal notranslate"><span class="pre">warm_start</span></code> is set to <code class="docutils literal notranslate"><span class="pre">True</span></code> for estimators that
support it. <code class="docutils literal notranslate"><span class="pre">warm_start=True</span></code> means that the previous state of the
trainable parameters of the estimator are reused instead of using the
default initialization strategy.</p>
</section>
<section id="estimated-attributes">
<h4>Estimated Attributes<a class="headerlink" href="#estimated-attributes" title="Permalink to this heading">¶</a></h4>
<p>Attributes that have been estimated from the data must always have a name
ending with trailing underscore, for example the coefficients of
some regression estimator would be stored in a <code class="docutils literal notranslate"><span class="pre">coef_</span></code> attribute after
<code class="docutils literal notranslate"><span class="pre">fit</span></code> has been called.</p>
<p>The estimated attributes are expected to be overridden when you call <code class="docutils literal notranslate"><span class="pre">fit</span></code>
a second time.</p>
</section>
<section id="optional-arguments">
<h4>Optional Arguments<a class="headerlink" href="#optional-arguments" title="Permalink to this heading">¶</a></h4>
<p>In iterative algorithms, the number of iterations should be specified by
an integer called <code class="docutils literal notranslate"><span class="pre">n_iter</span></code>.</p>
</section>
<section id="universal-attributes">
<h4>Universal attributes<a class="headerlink" href="#universal-attributes" title="Permalink to this heading">¶</a></h4>
<p>Estimators that expect tabular input should set a <code class="docutils literal notranslate"><span class="pre">n_features_in_</span></code>
attribute at <code class="docutils literal notranslate"><span class="pre">fit</span></code> time to indicate the number of features that the estimator
expects for subsequent calls to <code class="docutils literal notranslate"><span class="pre">predict</span></code> or <code class="docutils literal notranslate"><span class="pre">transform</span></code>.
See
<a class="reference external" href="https://scikit-learn-enhancement-proposals.readthedocs.io/en/latest/slep010/proposal.html">SLEP010</a>
for details.</p>
</section>
</section>
</section>
<section id="rolling-your-own-estimator">
<span id="id1"></span><h2>Rolling your own estimator<a class="headerlink" href="#rolling-your-own-estimator" title="Permalink to this heading">¶</a></h2>
<p>If you want to implement a new estimator that is scikit-learn-compatible,
whether it is just for you or for contributing it to scikit-learn, there are
several internals of scikit-learn that you should be aware of in addition to
the scikit-learn API outlined above. You can check whether your estimator
adheres to the scikit-learn interface and standards by running
<a class="reference internal" href="../modules/generated/sklearn.utils.estimator_checks.check_estimator.html#sklearn.utils.estimator_checks.check_estimator" title="sklearn.utils.estimator_checks.check_estimator"><code class="xref py py-func docutils literal notranslate"><span class="pre">check_estimator</span></code></a> on an instance. The
<a class="reference internal" href="../modules/generated/sklearn.utils.estimator_checks.parametrize_with_checks.html#sklearn.utils.estimator_checks.parametrize_with_checks" title="sklearn.utils.estimator_checks.parametrize_with_checks"><code class="xref py py-func docutils literal notranslate"><span class="pre">parametrize_with_checks</span></code></a> pytest
decorator can also be used (see its docstring for details and possible
interactions with <code class="docutils literal notranslate"><span class="pre">pytest</span></code>):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">sklearn.utils.estimator_checks</span> <span class="kn">import</span> <span class="n">check_estimator</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">sklearn.svm</span> <span class="kn">import</span> <span class="n">LinearSVC</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">check_estimator</span><span class="p">(</span><span class="n">LinearSVC</span><span class="p">())</span>  <span class="c1"># passes</span>
</pre></div>
</div>
<p>The main motivation to make a class compatible to the scikit-learn estimator
interface might be that you want to use it together with model evaluation and
selection tools such as <a class="reference internal" href="../modules/generated/sklearn.model_selection.GridSearchCV.html#sklearn.model_selection.GridSearchCV" title="sklearn.model_selection.GridSearchCV"><code class="xref py py-class docutils literal notranslate"><span class="pre">model_selection.GridSearchCV</span></code></a> and
<a class="reference internal" href="../modules/generated/sklearn.pipeline.Pipeline.html#sklearn.pipeline.Pipeline" title="sklearn.pipeline.Pipeline"><code class="xref py py-class docutils literal notranslate"><span class="pre">pipeline.Pipeline</span></code></a>.</p>
<p>Before detailing the required interface below, we describe two ways to achieve
the correct interface more easily.</p>
<aside class="topic">
<p class="topic-title">Project template:</p>
<p>We provide a <a class="reference external" href="https://github.com/scikit-learn-contrib/project-template/">project template</a>
which helps in the creation of Python packages containing scikit-learn compatible estimators.
It provides:</p>
<ul class="simple">
<li><p>an initial git repository with Python package directory structure</p></li>
<li><p>a template of a scikit-learn estimator</p></li>
<li><p>an initial test suite including use of <code class="docutils literal notranslate"><span class="pre">check_estimator</span></code></p></li>
<li><p>directory structures and scripts to compile documentation and example
galleries</p></li>
<li><p>scripts to manage continuous integration (testing on Linux and Windows)</p></li>
<li><p>instructions from getting started to publishing on <a class="reference external" href="https://pypi.org/">PyPi</a></p></li>
</ul>
</aside>
<aside class="topic">
<p class="topic-title"><code class="docutils literal notranslate"><span class="pre">BaseEstimator</span></code> and mixins:</p>
<p>We tend to use “duck typing”, so building an estimator which follows
the API suffices for compatibility, without needing to inherit from or
even import any scikit-learn classes.</p>
<p>However, if a dependency on scikit-learn is acceptable in your code,
you can prevent a lot of boilerplate code
by deriving a class from <code class="docutils literal notranslate"><span class="pre">BaseEstimator</span></code>
and optionally the mixin classes in <code class="docutils literal notranslate"><span class="pre">sklearn.base</span></code>.
For example, below is a custom classifier, with more examples included
in the scikit-learn-contrib
<a class="reference external" href="https://github.com/scikit-learn-contrib/project-template/blob/master/skltemplate/_template.py">project template</a>.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">numpy</span> <span class="k">as</span> <span class="nn">np</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">sklearn.base</span> <span class="kn">import</span> <span class="n">BaseEstimator</span><span class="p">,</span> <span class="n">ClassifierMixin</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">sklearn.utils.validation</span> <span class="kn">import</span> <span class="n">check_X_y</span><span class="p">,</span> <span class="n">check_array</span><span class="p">,</span> <span class="n">check_is_fitted</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">sklearn.utils.multiclass</span> <span class="kn">import</span> <span class="n">unique_labels</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">sklearn.metrics</span> <span class="kn">import</span> <span class="n">euclidean_distances</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">TemplateClassifier</span><span class="p">(</span><span class="n">BaseEstimator</span><span class="p">,</span> <span class="n">ClassifierMixin</span><span class="p">):</span>
<span class="gp">...</span>
<span class="gp">... </span>    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">demo_param</span><span class="o">=</span><span class="s1">&#39;demo&#39;</span><span class="p">):</span>
<span class="gp">... </span>        <span class="bp">self</span><span class="o">.</span><span class="n">demo_param</span> <span class="o">=</span> <span class="n">demo_param</span>
<span class="gp">...</span>
<span class="gp">... </span>    <span class="k">def</span> <span class="nf">fit</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">X</span><span class="p">,</span> <span class="n">y</span><span class="p">):</span>
<span class="gp">...</span>
<span class="gp">... </span>        <span class="c1"># Check that X and y have correct shape</span>
<span class="gp">... </span>        <span class="n">X</span><span class="p">,</span> <span class="n">y</span> <span class="o">=</span> <span class="n">check_X_y</span><span class="p">(</span><span class="n">X</span><span class="p">,</span> <span class="n">y</span><span class="p">)</span>
<span class="gp">... </span>        <span class="c1"># Store the classes seen during fit</span>
<span class="gp">... </span>        <span class="bp">self</span><span class="o">.</span><span class="n">classes_</span> <span class="o">=</span> <span class="n">unique_labels</span><span class="p">(</span><span class="n">y</span><span class="p">)</span>
<span class="gp">...</span>
<span class="gp">... </span>        <span class="bp">self</span><span class="o">.</span><span class="n">X_</span> <span class="o">=</span> <span class="n">X</span>
<span class="gp">... </span>        <span class="bp">self</span><span class="o">.</span><span class="n">y_</span> <span class="o">=</span> <span class="n">y</span>
<span class="gp">... </span>        <span class="c1"># Return the classifier</span>
<span class="gp">... </span>        <span class="k">return</span> <span class="bp">self</span>
<span class="gp">...</span>
<span class="gp">... </span>    <span class="k">def</span> <span class="nf">predict</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">X</span><span class="p">):</span>
<span class="gp">...</span>
<span class="gp">... </span>        <span class="c1"># Check if fit has been called</span>
<span class="gp">... </span>        <span class="n">check_is_fitted</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
<span class="gp">...</span>
<span class="gp">... </span>        <span class="c1"># Input validation</span>
<span class="gp">... </span>        <span class="n">X</span> <span class="o">=</span> <span class="n">check_array</span><span class="p">(</span><span class="n">X</span><span class="p">)</span>
<span class="gp">...</span>
<span class="gp">... </span>        <span class="n">closest</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">argmin</span><span class="p">(</span><span class="n">euclidean_distances</span><span class="p">(</span><span class="n">X</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">X_</span><span class="p">),</span> <span class="n">axis</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="gp">... </span>        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">y_</span><span class="p">[</span><span class="n">closest</span><span class="p">]</span>
</pre></div>
</div>
</aside>
<section id="get-params-and-set-params">
<h3>get_params and set_params<a class="headerlink" href="#get-params-and-set-params" title="Permalink to this heading">¶</a></h3>
<p>All scikit-learn estimators have <code class="docutils literal notranslate"><span class="pre">get_params</span></code> and <code class="docutils literal notranslate"><span class="pre">set_params</span></code> functions.
The <code class="docutils literal notranslate"><span class="pre">get_params</span></code> function takes no arguments and returns a dict of the
<code class="docutils literal notranslate"><span class="pre">__init__</span></code> parameters of the estimator, together with their values.</p>
<p>It must take one keyword argument, <code class="docutils literal notranslate"><span class="pre">deep</span></code>, which receives a boolean value
that determines whether the method should return the parameters of
sub-estimators (for most estimators, this can be ignored). The default value
for <code class="docutils literal notranslate"><span class="pre">deep</span></code> should be <code class="docutils literal notranslate"><span class="pre">True</span></code>. For instance considering the following
estimator:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">sklearn.base</span> <span class="kn">import</span> <span class="n">BaseEstimator</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">sklearn.linear_model</span> <span class="kn">import</span> <span class="n">LogisticRegression</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">MyEstimator</span><span class="p">(</span><span class="n">BaseEstimator</span><span class="p">):</span>
<span class="gp">... </span>    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">subestimator</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">my_extra_param</span><span class="o">=</span><span class="s2">&quot;random&quot;</span><span class="p">):</span>
<span class="gp">... </span>        <span class="bp">self</span><span class="o">.</span><span class="n">subestimator</span> <span class="o">=</span> <span class="n">subestimator</span>
<span class="gp">... </span>        <span class="bp">self</span><span class="o">.</span><span class="n">my_extra_param</span> <span class="o">=</span> <span class="n">my_extra_param</span>
</pre></div>
</div>
<p>The parameter <code class="docutils literal notranslate"><span class="pre">deep</span></code> will control whether or not the parameters of the
<code class="docutils literal notranslate"><span class="pre">subestimator</span></code> should be reported. Thus when <code class="docutils literal notranslate"><span class="pre">deep=True</span></code>, the output will be:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">my_estimator</span> <span class="o">=</span> <span class="n">MyEstimator</span><span class="p">(</span><span class="n">subestimator</span><span class="o">=</span><span class="n">LogisticRegression</span><span class="p">())</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">param</span><span class="p">,</span> <span class="n">value</span> <span class="ow">in</span> <span class="n">my_estimator</span><span class="o">.</span><span class="n">get_params</span><span class="p">(</span><span class="n">deep</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
<span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">param</span><span class="si">}</span><span class="s2"> -&gt; </span><span class="si">{</span><span class="n">value</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
<span class="go">my_extra_param -&gt; random</span>
<span class="go">subestimator__C -&gt; 1.0</span>
<span class="go">subestimator__class_weight -&gt; None</span>
<span class="go">subestimator__dual -&gt; False</span>
<span class="go">subestimator__fit_intercept -&gt; True</span>
<span class="go">subestimator__intercept_scaling -&gt; 1</span>
<span class="go">subestimator__l1_ratio -&gt; None</span>
<span class="go">subestimator__max_iter -&gt; 100</span>
<span class="go">subestimator__multi_class -&gt; auto</span>
<span class="go">subestimator__n_jobs -&gt; None</span>
<span class="go">subestimator__penalty -&gt; l2</span>
<span class="go">subestimator__random_state -&gt; None</span>
<span class="go">subestimator__solver -&gt; lbfgs</span>
<span class="go">subestimator__tol -&gt; 0.0001</span>
<span class="go">subestimator__verbose -&gt; 0</span>
<span class="go">subestimator__warm_start -&gt; False</span>
<span class="go">subestimator -&gt; LogisticRegression()</span>
</pre></div>
</div>
<p>Often, the <code class="docutils literal notranslate"><span class="pre">subestimator</span></code> has a name (as e.g. named steps in a
<a class="reference internal" href="../modules/generated/sklearn.pipeline.Pipeline.html#sklearn.pipeline.Pipeline" title="sklearn.pipeline.Pipeline"><code class="xref py py-class docutils literal notranslate"><span class="pre">Pipeline</span></code></a> object), in which case the key should
become <code class="docutils literal notranslate"><span class="pre">&lt;name&gt;__C</span></code>, <code class="docutils literal notranslate"><span class="pre">&lt;name&gt;__class_weight</span></code>, etc.</p>
<p>While when <code class="docutils literal notranslate"><span class="pre">deep=False</span></code>, the output will be:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">param</span><span class="p">,</span> <span class="n">value</span> <span class="ow">in</span> <span class="n">my_estimator</span><span class="o">.</span><span class="n">get_params</span><span class="p">(</span><span class="n">deep</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
<span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">param</span><span class="si">}</span><span class="s2"> -&gt; </span><span class="si">{</span><span class="n">value</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
<span class="go">my_extra_param -&gt; random</span>
<span class="go">subestimator -&gt; LogisticRegression()</span>
</pre></div>
</div>
<p>On the other hand, <code class="docutils literal notranslate"><span class="pre">set_params</span></code> takes the parameters of <code class="docutils literal notranslate"><span class="pre">__init__</span></code>
as keyword arguments, unpacks them into a dict of the form
<code class="docutils literal notranslate"><span class="pre">'parameter':</span> <span class="pre">value</span></code> and sets the parameters of the estimator using this dict.
Return value must be the estimator itself.</p>
<p>While the <code class="docutils literal notranslate"><span class="pre">get_params</span></code> mechanism is not essential (see <a class="reference internal" href="#cloning"><span class="std std-ref">Cloning</span></a> below),
the <code class="docutils literal notranslate"><span class="pre">set_params</span></code> function is necessary as it is used to set parameters during
grid searches.</p>
<p>The easiest way to implement these functions, and to get a sensible
<code class="docutils literal notranslate"><span class="pre">__repr__</span></code> method, is to inherit from <code class="docutils literal notranslate"><span class="pre">sklearn.base.BaseEstimator</span></code>. If you
do not want to make your code dependent on scikit-learn, the easiest way to
implement the interface is:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">get_params</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">deep</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>
    <span class="c1"># suppose this estimator has parameters &quot;alpha&quot; and &quot;recursive&quot;</span>
    <span class="k">return</span> <span class="p">{</span><span class="s2">&quot;alpha&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">alpha</span><span class="p">,</span> <span class="s2">&quot;recursive&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">recursive</span><span class="p">}</span>

<span class="k">def</span> <span class="nf">set_params</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">**</span><span class="n">parameters</span><span class="p">):</span>
    <span class="k">for</span> <span class="n">parameter</span><span class="p">,</span> <span class="n">value</span> <span class="ow">in</span> <span class="n">parameters</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
        <span class="nb">setattr</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">parameter</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>
    <span class="k">return</span> <span class="bp">self</span>
</pre></div>
</div>
</section>
<section id="parameters-and-init">
<h3>Parameters and init<a class="headerlink" href="#parameters-and-init" title="Permalink to this heading">¶</a></h3>
<p>As <a class="reference internal" href="../modules/generated/sklearn.model_selection.GridSearchCV.html#sklearn.model_selection.GridSearchCV" title="sklearn.model_selection.GridSearchCV"><code class="xref py py-class docutils literal notranslate"><span class="pre">model_selection.GridSearchCV</span></code></a> uses <code class="docutils literal notranslate"><span class="pre">set_params</span></code>
to apply parameter setting to estimators,
it is essential that calling <code class="docutils literal notranslate"><span class="pre">set_params</span></code> has the same effect
as setting parameters using the <code class="docutils literal notranslate"><span class="pre">__init__</span></code> method.
The easiest and recommended way to accomplish this is to
<strong>not do any parameter validation in</strong> <code class="docutils literal notranslate"><span class="pre">__init__</span></code>.
All logic behind estimator parameters,
like translating string arguments into functions, should be done in <code class="docutils literal notranslate"><span class="pre">fit</span></code>.</p>
<p>Also it is expected that parameters with trailing <code class="docutils literal notranslate"><span class="pre">_</span></code> are <strong>not to be set
inside the</strong> <code class="docutils literal notranslate"><span class="pre">__init__</span></code> <strong>method</strong>. All and only the public attributes set by
fit have a trailing <code class="docutils literal notranslate"><span class="pre">_</span></code>. As a result the existence of parameters with
trailing <code class="docutils literal notranslate"><span class="pre">_</span></code> is used to check if the estimator has been fitted.</p>
</section>
<section id="cloning">
<span id="id2"></span><h3>Cloning<a class="headerlink" href="#cloning" title="Permalink to this heading">¶</a></h3>
<p>For use with the <a class="reference internal" href="../modules/classes.html#module-sklearn.model_selection" title="sklearn.model_selection"><code class="xref py py-mod docutils literal notranslate"><span class="pre">model_selection</span></code></a> module,
an estimator must support the <code class="docutils literal notranslate"><span class="pre">base.clone</span></code> function to replicate an estimator.
This can be done by providing a <code class="docutils literal notranslate"><span class="pre">get_params</span></code> method.
If <code class="docutils literal notranslate"><span class="pre">get_params</span></code> is present, then <code class="docutils literal notranslate"><span class="pre">clone(estimator)</span></code> will be an instance of
<code class="docutils literal notranslate"><span class="pre">type(estimator)</span></code> on which <code class="docutils literal notranslate"><span class="pre">set_params</span></code> has been called with clones of
the result of <code class="docutils literal notranslate"><span class="pre">estimator.get_params()</span></code>.</p>
<p>Objects that do not provide this method will be deep-copied
(using the Python standard function <code class="docutils literal notranslate"><span class="pre">copy.deepcopy</span></code>)
if <code class="docutils literal notranslate"><span class="pre">safe=False</span></code> is passed to <code class="docutils literal notranslate"><span class="pre">clone</span></code>.</p>
<p>Estimators can customize the behavior of <a class="reference internal" href="../modules/generated/sklearn.base.clone.html#sklearn.base.clone" title="sklearn.base.clone"><code class="xref py py-func docutils literal notranslate"><span class="pre">base.clone</span></code></a> by defining a
<code class="docutils literal notranslate"><span class="pre">__sklearn_clone__</span></code> method. <code class="docutils literal notranslate"><span class="pre">__sklearn_clone__</span></code> must return an instance of the
estimator. <code class="docutils literal notranslate"><span class="pre">__sklearn_clone__</span></code> is useful when an estimator needs to hold on to
some state when <a class="reference internal" href="../modules/generated/sklearn.base.clone.html#sklearn.base.clone" title="sklearn.base.clone"><code class="xref py py-func docutils literal notranslate"><span class="pre">base.clone</span></code></a> is called on the estimator. For example, a
frozen meta-estimator for transformers can be defined as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">FrozenTransformer</span><span class="p">(</span><span class="n">BaseEstimator</span><span class="p">):</span>
    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">fitted_transformer</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">fitted_transformer</span> <span class="o">=</span> <span class="n">fitted_transformer</span>

    <span class="k">def</span> <span class="fm">__getattr__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
        <span class="c1"># `fitted_transformer`&#39;s attributes are now accessible</span>
        <span class="k">return</span> <span class="nb">getattr</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">fitted_transformer</span><span class="p">,</span> <span class="n">name</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">__sklearn_clone__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="bp">self</span>

    <span class="k">def</span> <span class="nf">fit</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">X</span><span class="p">,</span> <span class="n">y</span><span class="p">):</span>
        <span class="c1"># Fitting does not change the state of the estimator</span>
        <span class="k">return</span> <span class="bp">self</span>

    <span class="k">def</span> <span class="nf">fit_transform</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">X</span><span class="p">,</span> <span class="n">y</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
        <span class="c1"># fit_transform only transforms the data</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">fitted_transformer</span><span class="o">.</span><span class="n">transform</span><span class="p">(</span><span class="n">X</span><span class="p">,</span> <span class="n">y</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="pipeline-compatibility">
<h3>Pipeline compatibility<a class="headerlink" href="#pipeline-compatibility" title="Permalink to this heading">¶</a></h3>
<p>For an estimator to be usable together with <code class="docutils literal notranslate"><span class="pre">pipeline.Pipeline</span></code> in any but the
last step, it needs to provide a <code class="docutils literal notranslate"><span class="pre">fit</span></code> or <code class="docutils literal notranslate"><span class="pre">fit_transform</span></code> function.
To be able to evaluate the pipeline on any data but the training set,
it also needs to provide a <code class="docutils literal notranslate"><span class="pre">transform</span></code> function.
There are no special requirements for the last step in a pipeline, except that
it has a <code class="docutils literal notranslate"><span class="pre">fit</span></code> function. All <code class="docutils literal notranslate"><span class="pre">fit</span></code> and <code class="docutils literal notranslate"><span class="pre">fit_transform</span></code> functions must
take arguments <code class="docutils literal notranslate"><span class="pre">X,</span> <span class="pre">y</span></code>, even if y is not used. Similarly, for <code class="docutils literal notranslate"><span class="pre">score</span></code> to be
usable, the last step of the pipeline needs to have a <code class="docutils literal notranslate"><span class="pre">score</span></code> function that
accepts an optional <code class="docutils literal notranslate"><span class="pre">y</span></code>.</p>
</section>
<section id="estimator-types">
<h3>Estimator types<a class="headerlink" href="#estimator-types" title="Permalink to this heading">¶</a></h3>
<p>Some common functionality depends on the kind of estimator passed.
For example, cross-validation in <a class="reference internal" href="../modules/generated/sklearn.model_selection.GridSearchCV.html#sklearn.model_selection.GridSearchCV" title="sklearn.model_selection.GridSearchCV"><code class="xref py py-class docutils literal notranslate"><span class="pre">model_selection.GridSearchCV</span></code></a> and
<a class="reference internal" href="../modules/generated/sklearn.model_selection.cross_val_score.html#sklearn.model_selection.cross_val_score" title="sklearn.model_selection.cross_val_score"><code class="xref py py-func docutils literal notranslate"><span class="pre">model_selection.cross_val_score</span></code></a> defaults to being stratified when used
on a classifier, but not otherwise. Similarly, scorers for average precision
that take a continuous prediction need to call <code class="docutils literal notranslate"><span class="pre">decision_function</span></code> for classifiers,
but <code class="docutils literal notranslate"><span class="pre">predict</span></code> for regressors. This distinction between classifiers and regressors
is implemented using the <code class="docutils literal notranslate"><span class="pre">_estimator_type</span></code> attribute, which takes a string value.
It should be <code class="docutils literal notranslate"><span class="pre">&quot;classifier&quot;</span></code> for classifiers and <code class="docutils literal notranslate"><span class="pre">&quot;regressor&quot;</span></code> for
regressors and <code class="docutils literal notranslate"><span class="pre">&quot;clusterer&quot;</span></code> for clustering methods, to work as expected.
Inheriting from <code class="docutils literal notranslate"><span class="pre">ClassifierMixin</span></code>, <code class="docutils literal notranslate"><span class="pre">RegressorMixin</span></code> or <code class="docutils literal notranslate"><span class="pre">ClusterMixin</span></code>
will set the attribute automatically.  When a meta-estimator needs to distinguish
among estimator types, instead of checking <code class="docutils literal notranslate"><span class="pre">_estimator_type</span></code> directly, helpers
like <a class="reference internal" href="../modules/generated/sklearn.base.is_classifier.html#sklearn.base.is_classifier" title="sklearn.base.is_classifier"><code class="xref py py-func docutils literal notranslate"><span class="pre">base.is_classifier</span></code></a> should be used.</p>
</section>
<section id="specific-models">
<h3>Specific models<a class="headerlink" href="#specific-models" title="Permalink to this heading">¶</a></h3>
<p>Classifiers should accept <code class="docutils literal notranslate"><span class="pre">y</span></code> (target) arguments to <code class="docutils literal notranslate"><span class="pre">fit</span></code> that are
sequences (lists, arrays) of either strings or integers.  They should not
assume that the class labels are a contiguous range of integers; instead, they
should store a list of classes in a <code class="docutils literal notranslate"><span class="pre">classes_</span></code> attribute or property.  The
order of class labels in this attribute should match the order in which
<code class="docutils literal notranslate"><span class="pre">predict_proba</span></code>, <code class="docutils literal notranslate"><span class="pre">predict_log_proba</span></code> and <code class="docutils literal notranslate"><span class="pre">decision_function</span></code> return their
values.  The easiest way to achieve this is to put:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="bp">self</span><span class="o">.</span><span class="n">classes_</span><span class="p">,</span> <span class="n">y</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">unique</span><span class="p">(</span><span class="n">y</span><span class="p">,</span> <span class="n">return_inverse</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<p>in <code class="docutils literal notranslate"><span class="pre">fit</span></code>.  This returns a new <code class="docutils literal notranslate"><span class="pre">y</span></code> that contains class indexes, rather than
labels, in the range [0, <code class="docutils literal notranslate"><span class="pre">n_classes</span></code>).</p>
<p>A classifier’s <code class="docutils literal notranslate"><span class="pre">predict</span></code> method should return
arrays containing class labels from <code class="docutils literal notranslate"><span class="pre">classes_</span></code>.
In a classifier that implements <code class="docutils literal notranslate"><span class="pre">decision_function</span></code>,
this can be achieved with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">predict</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">X</span><span class="p">):</span>
    <span class="n">D</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">decision_function</span><span class="p">(</span><span class="n">X</span><span class="p">)</span>
    <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">classes_</span><span class="p">[</span><span class="n">np</span><span class="o">.</span><span class="n">argmax</span><span class="p">(</span><span class="n">D</span><span class="p">,</span> <span class="n">axis</span><span class="o">=</span><span class="mi">1</span><span class="p">)]</span>
</pre></div>
</div>
<p>In linear models, coefficients are stored in an array called <code class="docutils literal notranslate"><span class="pre">coef_</span></code>, and the
independent term is stored in <code class="docutils literal notranslate"><span class="pre">intercept_</span></code>.  <code class="docutils literal notranslate"><span class="pre">sklearn.linear_model._base</span></code>
contains a few base classes and mixins that implement common linear model
patterns.</p>
<p>The <a class="reference internal" href="../modules/classes.html#module-sklearn.utils.multiclass" title="sklearn.utils.multiclass"><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiclass</span></code></a> module contains useful functions
for working with multiclass and multilabel problems.</p>
</section>
<section id="estimator-tags">
<span id="id3"></span><h3>Estimator Tags<a class="headerlink" href="#estimator-tags" title="Permalink to this heading">¶</a></h3>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>The estimator tags are experimental and the API is subject to change.</p>
</div>
<p>Scikit-learn introduced estimator tags in version 0.21. These are annotations
of estimators that allow programmatic inspection of their capabilities, such as
sparse matrix support, supported output types and supported methods. The
estimator tags are a dictionary returned by the method <code class="docutils literal notranslate"><span class="pre">_get_tags()</span></code>. These
tags are used in the common checks run by the
<a class="reference internal" href="../modules/generated/sklearn.utils.estimator_checks.check_estimator.html#sklearn.utils.estimator_checks.check_estimator" title="sklearn.utils.estimator_checks.check_estimator"><code class="xref py py-func docutils literal notranslate"><span class="pre">check_estimator</span></code></a> function and the
<a class="reference internal" href="../modules/generated/sklearn.utils.estimator_checks.parametrize_with_checks.html#sklearn.utils.estimator_checks.parametrize_with_checks" title="sklearn.utils.estimator_checks.parametrize_with_checks"><code class="xref py py-func docutils literal notranslate"><span class="pre">parametrize_with_checks</span></code></a> decorator.
Tags determine which checks to run and what input data is appropriate. Tags
can depend on estimator parameters or even system architecture and can in
general only be determined at runtime.</p>
<p>The current set of estimator tags are:</p>
<dl class="simple">
<dt>allow_nan (default=False)</dt><dd><p>whether the estimator supports data with missing values encoded as np.nan</p>
</dd>
<dt>array_api_support (default=False)</dt><dd><p>whether the estimator supports Array API compatible inputs.</p>
</dd>
<dt>binary_only (default=False)</dt><dd><p>whether estimator supports binary classification but lacks multi-class
classification support.</p>
</dd>
<dt>multilabel (default=False)</dt><dd><p>whether the estimator supports multilabel output</p>
</dd>
<dt>multioutput (default=False)</dt><dd><p>whether a regressor supports multi-target outputs or a classifier supports
multi-class multi-output.</p>
</dd>
<dt>multioutput_only (default=False)</dt><dd><p>whether estimator supports only multi-output classification or regression.</p>
</dd>
<dt>no_validation (default=False)</dt><dd><p>whether the estimator skips input-validation. This is only meant for
stateless and dummy transformers!</p>
</dd>
<dt>non_deterministic (default=False)</dt><dd><p>whether the estimator is not deterministic given a fixed <code class="docutils literal notranslate"><span class="pre">random_state</span></code></p>
</dd>
<dt>pairwise (default=False)</dt><dd><p>This boolean attribute indicates whether the data (<code class="docutils literal notranslate"><span class="pre">X</span></code>) <a class="reference internal" href="../glossary.html#term-fit"><span class="xref std std-term">fit</span></a> and
similar methods consists of pairwise measures over samples rather than a
feature representation for each sample.  It is usually <code class="docutils literal notranslate"><span class="pre">True</span></code> where an
estimator has a <code class="docutils literal notranslate"><span class="pre">metric</span></code> or <code class="docutils literal notranslate"><span class="pre">affinity</span></code> or <code class="docutils literal notranslate"><span class="pre">kernel</span></code> parameter with value
‘precomputed’. Its primary purpose is to support a <a class="reference internal" href="../glossary.html#term-meta-estimator"><span class="xref std std-term">meta-estimator</span></a>
or a cross validation procedure that extracts a sub-sample of data intended
for a pairwise estimator, where the data needs to be indexed on both axes.
Specifically, this tag is used by
<code class="docutils literal notranslate"><span class="pre">sklearn.utils.metaestimators._safe_split</span></code> to slice rows and
columns.</p>
</dd>
<dt>preserves_dtype (default=``[np.float64]``)</dt><dd><p>applies only on transformers. It corresponds to the data types which will
be preserved such that <code class="docutils literal notranslate"><span class="pre">X_trans.dtype</span></code> is the same as <code class="docutils literal notranslate"><span class="pre">X.dtype</span></code> after
calling <code class="docutils literal notranslate"><span class="pre">transformer.transform(X)</span></code>. If this list is empty, then the
transformer is not expected to preserve the data type. The first value in
the list is considered as the default data type, corresponding to the data
type of the output when the input data type is not going to be preserved.</p>
</dd>
<dt>poor_score (default=False)</dt><dd><p>whether the estimator fails to provide a “reasonable” test-set score, which
currently for regression is an R2 of 0.5 on <code class="docutils literal notranslate"><span class="pre">make_regression(n_samples=200,</span>
<span class="pre">n_features=10,</span> <span class="pre">n_informative=1,</span> <span class="pre">bias=5.0,</span> <span class="pre">noise=20,</span> <span class="pre">random_state=42)</span></code>, and
for classification an accuracy of 0.83 on
<code class="docutils literal notranslate"><span class="pre">make_blobs(n_samples=300,</span> <span class="pre">random_state=0)</span></code>. These datasets and values
are based on current estimators in sklearn and might be replaced by
something more systematic.</p>
</dd>
<dt>requires_fit (default=True)</dt><dd><p>whether the estimator requires to be fitted before calling one of
<code class="docutils literal notranslate"><span class="pre">transform</span></code>, <code class="docutils literal notranslate"><span class="pre">predict</span></code>, <code class="docutils literal notranslate"><span class="pre">predict_proba</span></code>, or <code class="docutils literal notranslate"><span class="pre">decision_function</span></code>.</p>
</dd>
<dt>requires_positive_X (default=False)</dt><dd><p>whether the estimator requires positive X.</p>
</dd>
<dt>requires_y (default=False)</dt><dd><p>whether the estimator requires y to be passed to <code class="docutils literal notranslate"><span class="pre">fit</span></code>, <code class="docutils literal notranslate"><span class="pre">fit_predict</span></code> or
<code class="docutils literal notranslate"><span class="pre">fit_transform</span></code> methods. The tag is True for estimators inheriting from
<code class="docutils literal notranslate"><span class="pre">~sklearn.base.RegressorMixin</span></code> and <code class="docutils literal notranslate"><span class="pre">~sklearn.base.ClassifierMixin</span></code>.</p>
</dd>
<dt>requires_positive_y (default=False)</dt><dd><p>whether the estimator requires a positive y (only applicable for regression).</p>
</dd>
<dt>_skip_test (default=False)</dt><dd><p>whether to skip common tests entirely. Don’t use this unless you have a
<em>very good</em> reason.</p>
</dd>
<dt>_xfail_checks (default=False)</dt><dd><p>dictionary <code class="docutils literal notranslate"><span class="pre">{check_name:</span> <span class="pre">reason}</span></code> of common checks that will be marked
as <code class="docutils literal notranslate"><span class="pre">XFAIL</span></code> for pytest, when using
<a class="reference internal" href="../modules/generated/sklearn.utils.estimator_checks.parametrize_with_checks.html#sklearn.utils.estimator_checks.parametrize_with_checks" title="sklearn.utils.estimator_checks.parametrize_with_checks"><code class="xref py py-func docutils literal notranslate"><span class="pre">parametrize_with_checks</span></code></a>. These
checks will be simply ignored and not run by
<a class="reference internal" href="../modules/generated/sklearn.utils.estimator_checks.check_estimator.html#sklearn.utils.estimator_checks.check_estimator" title="sklearn.utils.estimator_checks.check_estimator"><code class="xref py py-func docutils literal notranslate"><span class="pre">check_estimator</span></code></a>, but a
<code class="docutils literal notranslate"><span class="pre">SkipTestWarning</span></code> will be raised.
Don’t use this unless there is a <em>very good</em> reason for your estimator
not to pass the check.
Also note that the usage of this tag is highly subject to change because
we are trying to make it more flexible: be prepared for breaking changes
in the future.</p>
</dd>
<dt>stateless (default=False)</dt><dd><p>whether the estimator needs access to data for fitting. Even though an
estimator is stateless, it might still need a call to <code class="docutils literal notranslate"><span class="pre">fit</span></code> for
initialization.</p>
</dd>
<dt>X_types (default=[‘2darray’])</dt><dd><p>Supported input types for X as list of strings. Tests are currently only
run if ‘2darray’ is contained in the list, signifying that the estimator
takes continuous 2d numpy arrays as input. The default value is
[‘2darray’]. Other possible types are <code class="docutils literal notranslate"><span class="pre">'string'</span></code>, <code class="docutils literal notranslate"><span class="pre">'sparse'</span></code>,
<code class="docutils literal notranslate"><span class="pre">'categorical'</span></code>, <code class="docutils literal notranslate"><span class="pre">dict</span></code>, <code class="docutils literal notranslate"><span class="pre">'1dlabels'</span></code> and <code class="docutils literal notranslate"><span class="pre">'2dlabels'</span></code>. The goal is
that in the future the supported input type will determine the data used
during testing, in particular for <code class="docutils literal notranslate"><span class="pre">'string'</span></code>, <code class="docutils literal notranslate"><span class="pre">'sparse'</span></code> and
<code class="docutils literal notranslate"><span class="pre">'categorical'</span></code> data. For now, the test for sparse data do not make use
of the <code class="docutils literal notranslate"><span class="pre">'sparse'</span></code> tag.</p>
</dd>
</dl>
<p>It is unlikely that the default values for each tag will suit the needs of your
specific estimator. Additional tags can be created or default tags can be
overridden by defining a <code class="docutils literal notranslate"><span class="pre">_more_tags()</span></code> method which returns a dict with the
desired overridden tags or new tags. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">MyMultiOutputEstimator</span><span class="p">(</span><span class="n">BaseEstimator</span><span class="p">):</span>

    <span class="k">def</span> <span class="nf">_more_tags</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="p">{</span><span class="s1">&#39;multioutput_only&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span>
                <span class="s1">&#39;non_deterministic&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
</pre></div>
</div>
<p>Any tag that is not in <code class="docutils literal notranslate"><span class="pre">_more_tags()</span></code> will just fall-back to the default values
documented above.</p>
<p>Even if it is not recommended, it is possible to override the method
<code class="docutils literal notranslate"><span class="pre">_get_tags()</span></code>. Note however that <strong>all tags must be present in the dict</strong>. If
any of the keys documented above is not present in the output of <code class="docutils literal notranslate"><span class="pre">_get_tags()</span></code>,
an error will occur.</p>
<p>In addition to the tags, estimators also need to declare any non-optional
parameters to <code class="docutils literal notranslate"><span class="pre">__init__</span></code> in the <code class="docutils literal notranslate"><span class="pre">_required_parameters</span></code> class attribute,
which is a list or tuple.  If <code class="docutils literal notranslate"><span class="pre">_required_parameters</span></code> is only
<code class="docutils literal notranslate"><span class="pre">[&quot;estimator&quot;]</span></code> or <code class="docutils literal notranslate"><span class="pre">[&quot;base_estimator&quot;]</span></code>, then the estimator will be
instantiated with an instance of <code class="docutils literal notranslate"><span class="pre">LogisticRegression</span></code> (or
<code class="docutils literal notranslate"><span class="pre">RidgeRegression</span></code> if the estimator is a regressor) in the tests. The choice
of these two models is somewhat idiosyncratic but both should provide robust
closed-form solutions.</p>
</section>
</section>
<section id="developer-api-for-set-output">
<span id="developer-api-set-output"></span><h2>Developer API for <code class="docutils literal notranslate"><span class="pre">set_output</span></code><a class="headerlink" href="#developer-api-for-set-output" title="Permalink to this heading">¶</a></h2>
<p>With
<a class="reference external" href="https://scikit-learn-enhancement-proposals.readthedocs.io/en/latest/slep018/proposal.html">SLEP018</a>,
scikit-learn introduces the <code class="docutils literal notranslate"><span class="pre">set_output</span></code> API for configuring transformers to
output pandas DataFrames. The <code class="docutils literal notranslate"><span class="pre">set_output</span></code> API is automatically defined if the
transformer defines <a class="reference internal" href="../glossary.html#term-get_feature_names_out"><span class="xref std std-term">get_feature_names_out</span></a> and subclasses
<a class="reference internal" href="../modules/generated/sklearn.base.TransformerMixin.html#sklearn.base.TransformerMixin" title="sklearn.base.TransformerMixin"><code class="xref py py-class docutils literal notranslate"><span class="pre">base.TransformerMixin</span></code></a>. <a class="reference internal" href="../glossary.html#term-get_feature_names_out"><span class="xref std std-term">get_feature_names_out</span></a> is used to get the
column names of pandas output.</p>
<p><a class="reference internal" href="../modules/generated/sklearn.base.OneToOneFeatureMixin.html#sklearn.base.OneToOneFeatureMixin" title="sklearn.base.OneToOneFeatureMixin"><code class="xref py py-class docutils literal notranslate"><span class="pre">base.OneToOneFeatureMixin</span></code></a> and
<a class="reference internal" href="../modules/generated/sklearn.base.ClassNamePrefixFeaturesOutMixin.html#sklearn.base.ClassNamePrefixFeaturesOutMixin" title="sklearn.base.ClassNamePrefixFeaturesOutMixin"><code class="xref py py-class docutils literal notranslate"><span class="pre">base.ClassNamePrefixFeaturesOutMixin</span></code></a> are helpful mixins for defining
<a class="reference internal" href="../glossary.html#term-get_feature_names_out"><span class="xref std std-term">get_feature_names_out</span></a>. <a class="reference internal" href="../modules/generated/sklearn.base.OneToOneFeatureMixin.html#sklearn.base.OneToOneFeatureMixin" title="sklearn.base.OneToOneFeatureMixin"><code class="xref py py-class docutils literal notranslate"><span class="pre">base.OneToOneFeatureMixin</span></code></a> is useful when
the transformer has a one-to-one correspondence between input features and output
features, such as <a class="reference internal" href="../modules/generated/sklearn.preprocessing.StandardScaler.html#sklearn.preprocessing.StandardScaler" title="sklearn.preprocessing.StandardScaler"><code class="xref py py-class docutils literal notranslate"><span class="pre">StandardScaler</span></code></a>.
<a class="reference internal" href="../modules/generated/sklearn.base.ClassNamePrefixFeaturesOutMixin.html#sklearn.base.ClassNamePrefixFeaturesOutMixin" title="sklearn.base.ClassNamePrefixFeaturesOutMixin"><code class="xref py py-class docutils literal notranslate"><span class="pre">base.ClassNamePrefixFeaturesOutMixin</span></code></a> is useful when the transformer
needs to generate its own feature names out, such as <a class="reference internal" href="../modules/generated/sklearn.decomposition.PCA.html#sklearn.decomposition.PCA" title="sklearn.decomposition.PCA"><code class="xref py py-class docutils literal notranslate"><span class="pre">PCA</span></code></a>.</p>
<p>You can opt-out of the <code class="docutils literal notranslate"><span class="pre">set_output</span></code> API by setting <code class="docutils literal notranslate"><span class="pre">auto_wrap_output_keys=None</span></code>
when defining a custom subclass:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">MyTransformer</span><span class="p">(</span><span class="n">TransformerMixin</span><span class="p">,</span> <span class="n">BaseEstimator</span><span class="p">,</span> <span class="n">auto_wrap_output_keys</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>

    <span class="k">def</span> <span class="nf">fit</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">X</span><span class="p">,</span> <span class="n">y</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
        <span class="k">return</span> <span class="bp">self</span>
    <span class="k">def</span> <span class="nf">transform</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">X</span><span class="p">,</span> <span class="n">y</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
        <span class="k">return</span> <span class="n">X</span>
    <span class="k">def</span> <span class="nf">get_feature_names_out</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">input_features</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
        <span class="o">...</span>
</pre></div>
</div>
<p>The default value for <code class="docutils literal notranslate"><span class="pre">auto_wrap_output_keys</span></code> is <code class="docutils literal notranslate"><span class="pre">(&quot;transform&quot;,)</span></code>, which automatically
wraps <code class="docutils literal notranslate"><span class="pre">fit_transform</span></code> and <code class="docutils literal notranslate"><span class="pre">transform</span></code>. The <code class="docutils literal notranslate"><span class="pre">TransformerMixin</span></code> uses the
<code class="docutils literal notranslate"><span class="pre">__init_subclass__</span></code> mechanism to consume <code class="docutils literal notranslate"><span class="pre">auto_wrap_output_keys</span></code> and pass all other
keyword arguments to it’s super class. Super classes’ <code class="docutils literal notranslate"><span class="pre">__init_subclass__</span></code> should
<strong>not</strong> depend on <code class="docutils literal notranslate"><span class="pre">auto_wrap_output_keys</span></code>.</p>
<p>For transformers that return multiple arrays in <code class="docutils literal notranslate"><span class="pre">transform</span></code>, auto wrapping will
only wrap the first array and not alter the other arrays.</p>
<p>See <a class="reference internal" href="../auto_examples/miscellaneous/plot_set_output.html#sphx-glr-auto-examples-miscellaneous-plot-set-output-py"><span class="std std-ref">Introducing the set_output API</span></a>
for an example on how to use the API.</p>
</section>
<section id="developer-api-for-check-is-fitted">
<span id="developer-api-check-is-fitted"></span><h2>Developer API for <code class="docutils literal notranslate"><span class="pre">check_is_fitted</span></code><a class="headerlink" href="#developer-api-for-check-is-fitted" title="Permalink to this heading">¶</a></h2>
<p>By default <a class="reference internal" href="../modules/generated/sklearn.utils.validation.check_is_fitted.html#sklearn.utils.validation.check_is_fitted" title="sklearn.utils.validation.check_is_fitted"><code class="xref py py-func docutils literal notranslate"><span class="pre">check_is_fitted</span></code></a> checks if there
are any attributes in the instance with a trailing underscore, e.g. <code class="docutils literal notranslate"><span class="pre">coef_</span></code>.
An estimator can change the behavior by implementing a <code class="docutils literal notranslate"><span class="pre">__sklearn_is_fitted__</span></code>
method taking no input and returning a boolean. If this method exists,
<a class="reference internal" href="../modules/generated/sklearn.utils.validation.check_is_fitted.html#sklearn.utils.validation.check_is_fitted" title="sklearn.utils.validation.check_is_fitted"><code class="xref py py-func docutils literal notranslate"><span class="pre">check_is_fitted</span></code></a> simply returns its output.</p>
<p>See <a class="reference internal" href="../auto_examples/developing_estimators/sklearn_is_fitted.html#sphx-glr-auto-examples-developing-estimators-sklearn-is-fitted-py"><span class="std std-ref">__sklearn_is_fitted__ as Developer API</span></a>
for an example on how to use the API.</p>
</section>
<section id="coding-guidelines">
<span id="id4"></span><h2>Coding guidelines<a class="headerlink" href="#coding-guidelines" title="Permalink to this heading">¶</a></h2>
<p>The following are some guidelines on how new code should be written for
inclusion in scikit-learn, and which may be appropriate to adopt in external
projects. Of course, there are special cases and there will be exceptions to
these rules. However, following these rules when submitting new code makes
the review easier so new code can be integrated in less time.</p>
<p>Uniformly formatted code makes it easier to share code ownership. The
scikit-learn project tries to closely follow the official Python guidelines
detailed in <a class="reference external" href="https://www.python.org/dev/peps/pep-0008">PEP8</a> that
detail how code should be formatted and indented. Please read it and
follow it.</p>
<p>In addition, we add the following guidelines:</p>
<ul class="simple">
<li><p>Use underscores to separate words in non class names: <code class="docutils literal notranslate"><span class="pre">n_samples</span></code>
rather than <code class="docutils literal notranslate"><span class="pre">nsamples</span></code>.</p></li>
<li><p>Avoid multiple statements on one line. Prefer a line return after
a control flow statement (<code class="docutils literal notranslate"><span class="pre">if</span></code>/<code class="docutils literal notranslate"><span class="pre">for</span></code>).</p></li>
<li><p>Use relative imports for references inside scikit-learn.</p></li>
<li><p>Unit tests are an exception to the previous rule;
they should use absolute imports, exactly as client code would.
A corollary is that, if <code class="docutils literal notranslate"><span class="pre">sklearn.foo</span></code> exports a class or function
that is implemented in <code class="docutils literal notranslate"><span class="pre">sklearn.foo.bar.baz</span></code>,
the test should import it from <code class="docutils literal notranslate"><span class="pre">sklearn.foo</span></code>.</p></li>
<li><p><strong>Please don’t use</strong> <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">*</span></code> <strong>in any case</strong>. It is considered harmful
by the <a class="reference external" href="https://docs.python.org/3.1/howto/doanddont.html#at-module-level">official Python recommendations</a>.
It makes the code harder to read as the origin of symbols is no
longer explicitly referenced, but most important, it prevents
using a static analysis tool like <a class="reference external" href="https://divmod.readthedocs.io/en/latest/products/pyflakes.html">pyflakes</a> to automatically
find bugs in scikit-learn.</p></li>
<li><p>Use the <a class="reference external" href="https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard">numpy docstring standard</a>
in all your docstrings.</p></li>
</ul>
<p>A good example of code that we like can be found <a class="reference external" href="https://gist.github.com/nateGeorge/5455d2c57fb33c1ae04706f2dc4fee01">here</a>.</p>
<section id="input-validation">
<h3>Input validation<a class="headerlink" href="#input-validation" title="Permalink to this heading">¶</a></h3>
<p>The module <a class="reference internal" href="../modules/classes.html#module-sklearn.utils" title="sklearn.utils"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sklearn.utils</span></code></a> contains various functions for doing input
validation and conversion. Sometimes, <code class="docutils literal notranslate"><span class="pre">np.asarray</span></code> suffices for validation;
do <em>not</em> use <code class="docutils literal notranslate"><span class="pre">np.asanyarray</span></code> or <code class="docutils literal notranslate"><span class="pre">np.atleast_2d</span></code>, since those let NumPy’s
<code class="docutils literal notranslate"><span class="pre">np.matrix</span></code> through, which has a different API
(e.g., <code class="docutils literal notranslate"><span class="pre">*</span></code> means dot product on <code class="docutils literal notranslate"><span class="pre">np.matrix</span></code>,
but Hadamard product on <code class="docutils literal notranslate"><span class="pre">np.ndarray</span></code>).</p>
<p>In other cases, be sure to call <a class="reference internal" href="../modules/generated/sklearn.utils.check_array.html#sklearn.utils.check_array" title="sklearn.utils.check_array"><code class="xref py py-func docutils literal notranslate"><span class="pre">check_array</span></code></a> on any array-like argument
passed to a scikit-learn API function. The exact parameters to use depends
mainly on whether and which <code class="docutils literal notranslate"><span class="pre">scipy.sparse</span></code> matrices must be accepted.</p>
<p>For more information, refer to the <a class="reference internal" href="utilities.html#developers-utils"><span class="std std-ref">Utilities for Developers</span></a> page.</p>
</section>
<section id="random-numbers">
<h3>Random Numbers<a class="headerlink" href="#random-numbers" title="Permalink to this heading">¶</a></h3>
<p>If your code depends on a random number generator, do not use
<code class="docutils literal notranslate"><span class="pre">numpy.random.random()</span></code> or similar routines.  To ensure
repeatability in error checking, the routine should accept a keyword
<code class="docutils literal notranslate"><span class="pre">random_state</span></code> and use this to construct a
<code class="docutils literal notranslate"><span class="pre">numpy.random.RandomState</span></code> object.
See <a class="reference internal" href="../modules/generated/sklearn.utils.check_random_state.html#sklearn.utils.check_random_state" title="sklearn.utils.check_random_state"><code class="xref py py-func docutils literal notranslate"><span class="pre">sklearn.utils.check_random_state</span></code></a> in <a class="reference internal" href="utilities.html#developers-utils"><span class="std std-ref">Utilities for Developers</span></a>.</p>
<p>Here’s a simple example of code using some of the above guidelines:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sklearn.utils</span> <span class="kn">import</span> <span class="n">check_array</span><span class="p">,</span> <span class="n">check_random_state</span>

<span class="k">def</span> <span class="nf">choose_random_sample</span><span class="p">(</span><span class="n">X</span><span class="p">,</span> <span class="n">random_state</span><span class="o">=</span><span class="mi">0</span><span class="p">):</span>
<span class="w">    </span><span class="sd">&quot;&quot;&quot;Choose a random point from X.</span>

<span class="sd">    Parameters</span>
<span class="sd">    ----------</span>
<span class="sd">    X : array-like of shape (n_samples, n_features)</span>
<span class="sd">        An array representing the data.</span>
<span class="sd">    random_state : int or RandomState instance, default=0</span>
<span class="sd">        The seed of the pseudo random number generator that selects a</span>
<span class="sd">        random sample. Pass an int for reproducible output across multiple</span>
<span class="sd">        function calls.</span>
<span class="sd">        See :term:`Glossary &lt;random_state&gt;`.</span>

<span class="sd">    Returns</span>
<span class="sd">    -------</span>
<span class="sd">    x : ndarray of shape (n_features,)</span>
<span class="sd">        A random point selected from X.</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="n">X</span> <span class="o">=</span> <span class="n">check_array</span><span class="p">(</span><span class="n">X</span><span class="p">)</span>
    <span class="n">random_state</span> <span class="o">=</span> <span class="n">check_random_state</span><span class="p">(</span><span class="n">random_state</span><span class="p">)</span>
    <span class="n">i</span> <span class="o">=</span> <span class="n">random_state</span><span class="o">.</span><span class="n">randint</span><span class="p">(</span><span class="n">X</span><span class="o">.</span><span class="n">shape</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span>
    <span class="k">return</span> <span class="n">X</span><span class="p">[</span><span class="n">i</span><span class="p">]</span>
</pre></div>
</div>
<p>If you use randomness in an estimator instead of a freestanding function,
some additional guidelines apply.</p>
<p>First off, the estimator should take a <code class="docutils literal notranslate"><span class="pre">random_state</span></code> argument to its
<code class="docutils literal notranslate"><span class="pre">__init__</span></code> with a default value of <code class="docutils literal notranslate"><span class="pre">None</span></code>.
It should store that argument’s value, <strong>unmodified</strong>,
in an attribute <code class="docutils literal notranslate"><span class="pre">random_state</span></code>.
<code class="docutils literal notranslate"><span class="pre">fit</span></code> can call <code class="docutils literal notranslate"><span class="pre">check_random_state</span></code> on that attribute
to get an actual random number generator.
If, for some reason, randomness is needed after <code class="docutils literal notranslate"><span class="pre">fit</span></code>,
the RNG should be stored in an attribute <code class="docutils literal notranslate"><span class="pre">random_state_</span></code>.
The following example should make this clear:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">GaussianNoise</span><span class="p">(</span><span class="n">BaseEstimator</span><span class="p">,</span> <span class="n">TransformerMixin</span><span class="p">):</span>
<span class="w">    </span><span class="sd">&quot;&quot;&quot;This estimator ignores its input and returns random Gaussian noise.</span>

<span class="sd">    It also does not adhere to all scikit-learn conventions,</span>
<span class="sd">    but showcases how to handle randomness.</span>
<span class="sd">    &quot;&quot;&quot;</span>

    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">n_components</span><span class="o">=</span><span class="mi">100</span><span class="p">,</span> <span class="n">random_state</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">random_state</span> <span class="o">=</span> <span class="n">random_state</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">n_components</span> <span class="o">=</span> <span class="n">n_components</span>

    <span class="c1"># the arguments are ignored anyway, so we make them optional</span>
    <span class="k">def</span> <span class="nf">fit</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">X</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">y</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">random_state_</span> <span class="o">=</span> <span class="n">check_random_state</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">random_state</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">transform</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">X</span><span class="p">):</span>
        <span class="n">n_samples</span> <span class="o">=</span> <span class="n">X</span><span class="o">.</span><span class="n">shape</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">random_state_</span><span class="o">.</span><span class="n">randn</span><span class="p">(</span><span class="n">n_samples</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">n_components</span><span class="p">)</span>
</pre></div>
</div>
<p>The reason for this setup is reproducibility:
when an estimator is <code class="docutils literal notranslate"><span class="pre">fit</span></code> twice to the same data,
it should produce an identical model both times,
hence the validation in <code class="docutils literal notranslate"><span class="pre">fit</span></code>, not <code class="docutils literal notranslate"><span class="pre">__init__</span></code>.</p>
</section>
<section id="numerical-assertions-in-tests">
<h3>Numerical assertions in tests<a class="headerlink" href="#numerical-assertions-in-tests" title="Permalink to this heading">¶</a></h3>
<p>When asserting the quasi-equality of arrays of continuous values,
do use <code class="docutils literal notranslate"><span class="pre">sklearn.utils._testing.assert_allclose</span></code>.</p>
<p>The relative tolerance is automatically inferred from the provided arrays
dtypes (for float32 and float64 dtypes in particular) but you can override
via <code class="docutils literal notranslate"><span class="pre">rtol</span></code>.</p>
<p>When comparing arrays of zero-elements, please do provide a non-zero value for
the absolute tolerance via <code class="docutils literal notranslate"><span class="pre">atol</span></code>.</p>
<p>For more information, please refer to the docstring of
<code class="docutils literal notranslate"><span class="pre">sklearn.utils._testing.assert_allclose</span></code>.</p>
</section>
</section>
</section>


      </div>
    <div class="container">
      <footer class="sk-content-footer">
            &copy; 2007 - 2023, scikit-learn developers (BSD License).
          <a href="../_sources/developers/develop.rst.txt" rel="nofollow">Show this page source</a>
      </footer>
    </div>
  </div>
</div>
<script src="../_static/js/vendor/bootstrap.min.js"></script>

<script>
    window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
    ga('create', 'UA-22606712-2', 'auto');
    ga('set', 'anonymizeIp', true);
    ga('send', 'pageview');
</script>
<script async src='https://www.google-analytics.com/analytics.js'></script>


<script defer data-domain="scikit-learn.org" src="https://views.scientific-python.org/js/script.js">
</script>


<script src="../_static/clipboard.min.js"></script>
<script src="../_static/copybutton.js"></script>

<script>
$(document).ready(function() {
    /* Add a [>>>] button on the top-right corner of code samples to hide
     * the >>> and ... prompts and the output and thus make the code
     * copyable. */
    var div = $('.highlight-python .highlight,' +
                '.highlight-python3 .highlight,' +
                '.highlight-pycon .highlight,' +
		'.highlight-default .highlight')
    var pre = div.find('pre');

    // get the styles from the current theme
    pre.parent().parent().css('position', 'relative');

    // create and add the button to all the code blocks that contain >>>
    div.each(function(index) {
        var jthis = $(this);
        // tracebacks (.gt) contain bare text elements that need to be
        // wrapped in a span to work with .nextUntil() (see later)
        jthis.find('pre:has(.gt)').contents().filter(function() {
            return ((this.nodeType == 3) && (this.data.trim().length > 0));
        }).wrap('<span>');
    });

	/*** Add permalink buttons next to glossary terms ***/
	$('dl.glossary > dt[id]').append(function() {
		return ('<a class="headerlink" href="#' +
			    this.getAttribute('id') +
			    '" title="Permalink to this term">¶</a>');
	});
});

</script>
    
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>
    
    <script src="https://scikit-learn.org/versionwarning.js"></script>
</body>
</html>