class_docstr: James-Stein estimator.
  
  Supported targets: binomial and continuous. For polynomial target support, see PolynomialWrapper.
  
  For feature value `i`, James-Stein estimator returns a weighted average of:
  
      1. The mean target value for the observed feature value `i`.
      2. The mean target value (regardless of the feature value).
  
  This can be written as::
  
      JS_i = (1-B)*mean(y_i) + B*mean(y)
  
  The question is, what should be the weight `B`?
  If we put too much weight on the conditional mean value, we will overfit.
  If we put too much weight on the global mean, we will underfit.
  The canonical solution in machine learning is to perform cross-validation.
  However, Charles Stein came with a closed-form solution to the problem.
  The intuition is: If the estimate of `mean(y_i)` is unreliable (`y_i` has high variance),
  we should put more weight on `mean(y)`. Stein put it into an equation as::
  
      B = var(y_i) / (var(y_i)+var(y))
  
  The only remaining issue is that we do not know `var(y)`, let alone `var(y_i)`.
  Hence, we have to estimate the variances. But how can we reliably estimate the
  variances, when we already struggle with the estimation of the mean values?!
  There are multiple solutions:
  
      1. If we have the same count of observations for each feature value `i` and all
      `y_i` are close to each other, we can pretend that all `var(y_i)` are identical.
      This is called a pooled model.
      2. If the observation counts are not equal, it makes sense to replace the variances
      with squared standard errors, which penalize small observation counts::
  
          SE^2 = var(y)/count(y)
  
      This is called an independent model.
  
  James-Stein estimator has, however, one practical limitation - it was defined
  only for normal distributions. If you want to apply it for binary classification,
  which allows only values {0, 1}, it is better to first convert the mean target value
  from the bound interval <0,1> into an unbounded interval by replacing mean(y)
  with log-odds ratio::
  
      log-odds_ratio_i = log(mean(y_i)/mean(y_not_i))
  
  This is called binary model. The estimation of parameters of this model is, however,
  tricky and sometimes it fails fatally. In these situations, it is better to use beta
  model, which generally delivers slightly worse accuracy than binary model but does
  not suffer from fatal failures.
  
  Parameters
  ----------
  
  verbose: int
      integer indicating verbosity of the output. 0 for none.
  cols: list
      a list of columns to encode, if None, all string columns will be encoded.
  drop_invariant: bool
      boolean for whether or not to drop encoded columns with 0 variance.
  return_df: bool
      boolean for whether to return a pandas DataFrame from transform (otherwise it will be a numpy array).
  handle_missing: str
      options are 'return_nan', 'error' and 'value', defaults to 'value', which returns the prior probability.
  handle_unknown: str
      options are 'return_nan', 'error' and 'value', defaults to 'value', which returns the prior probability.
  model: str
      options are 'pooled', 'beta', 'binary' and 'independent', defaults to 'independent'.
  randomized: bool,
      adds normal (Gaussian) distribution noise into training data in order to decrease overfitting (testing data are untouched).
  sigma: float
      standard deviation (spread or "width") of the normal distribution.
  
  
  Example
  -------
  >>> from category_encoders import *
  >>> import pandas as pd
  >>> from sklearn.datasets import fetch_openml
  >>> bunch = fetch_openml(name="house_prices", as_frame=True)
  >>> display_cols = ["Id", "MSSubClass", "MSZoning", "LotFrontage", "YearBuilt", "Heating", "CentralAir"]
  >>> y = bunch.target
  >>> X = pd.DataFrame(bunch.data, columns=bunch.feature_names)[display_cols]
  >>> enc = JamesSteinEncoder(cols=['CentralAir', 'Heating']).fit(X, y)
  >>> numeric_dataset = enc.transform(X)
  >>> print(numeric_dataset.info())
  <class 'pandas.core.frame.DataFrame'>
  RangeIndex: 1460 entries, 0 to 1459
  Data columns (total 7 columns):
   #   Column       Non-Null Count  Dtype  
  ---  ------       --------------  -----  
   0   Id           1460 non-null   float64
   1   MSSubClass   1460 non-null   float64
   2   MSZoning     1460 non-null   object 
   3   LotFrontage  1201 non-null   float64
   4   YearBuilt    1460 non-null   float64
   5   Heating      1460 non-null   float64
   6   CentralAir   1460 non-null   float64
  dtypes: float64(6), object(1)
  memory usage: 80.0+ KB
  None
  
  References
  ----------
  
  .. [1] Parametric empirical Bayes inference: Theory and applications, equations 1.19 & 1.20, from
  https://www.jstor.org/stable/2287098
  
  .. [2] Empirical Bayes for multiple sample sizes, from
  http://chris-said.io/2017/05/03/empirical-bayes-for-multiple-sample-sizes/
  
  .. [3] Shrinkage Estimation of Log-odds Ratios for Comparing Mobility Tables, from
  https://journals.sagepub.com/doi/abs/10.1177/0081175015570097
  
  .. [4] Stein's paradox and group rationality, from
  http://www.philos.rug.nl/~romeyn/presentation/2017_romeijn_-_Paris_Stein.pdf
  
  .. [5] Stein's Paradox in Statistics, from
  http://statweb.stanford.edu/~ckirby/brad/other/Article1977.pdf
class_docstr_tok: ["James-Stein","estimator",".","Supported","targets",":","binomial","and","continuous",".","For","polynomial","target","support",",","see","PolynomialWrapper",".","For","feature","value","`","i","`",",","James-Stein","estimator","returns","a","weighted","average","of",":","1",".","The","mean","target","value","for","the","observed","feature","value","`","i","`",".","2",".","The","mean","target","value","(","regardless","of","the","feature","value",")",".","This","can","be","written","as",":",":","JS_i","=","(","1-B",")","*","mean","(","y_i",")","+","B","*","mean","(","y",")","The","question","is",",","what","should","be","the","weight","`","B","`","?","If","we","put","too","much","weight","on","the","conditional","mean","value",",","we","will","overfit",".","If","we","put","too","much","weight","on","the","global","mean",",","we","will","underfit",".","The","canonical","solution","in","machine","learning","is","to","perform","cross-validation",".","However",",","Charles","Stein","came","with","a","closed-form","solution","to","the","problem",".","The","intuition","is",":","If","the","estimate","of","`","mean","(","y_i",")","`","is","unreliable","(","`","y_i","`","has","high","variance",")",",","we","should","put","more","weight","on","`","mean","(","y",")","`",".","Stein","put","it","into","an","equation","as",":",":","B","=","var","(","y_i",")","\/","(","var","(","y_i",")","+var","(","y",")",")","The","only","remaining","issue","is","that","we","do","not","know","`","var","(","y",")","`",",","let","alone","`","var","(","y_i",")","`",".","Hence",",","we","have","to","estimate","the","variances",".","But","how","can","we","reliably","estimate","the","variances",",","when","we","already","struggle","with","the","estimation","of","the","mean","values","?","!","There","are","multiple","solutions",":","1",".","If","we","have","the","same","count","of","observations","for","each","feature","value","`","i","`","and","all","`","y_i","`","are","close","to","each","other",",","we","can","pretend","that","all","`","var","(","y_i",")","`","are","identical",".","This","is","called","a","pooled","model",".","2",".","If","the","observation","counts","are","not","equal",",","it","makes","sense","to","replace","the","variances","with","squared","standard","errors",",","which","penalize","small","observation","counts",":",":","SE^2","=","var","(","y",")","\/count","(","y",")","This","is","called","an","independent","model",".","James-Stein","estimator","has",",","however",",","one","practical","limitation","-","it","was","defined","only","for","normal","distributions",".","If","you","want","to","apply","it","for","binary","classification",",","which","allows","only","values","{","0",",","1","}",",","it","is","better","to","first","convert","the","mean","target","value","from","the","bound","interval","<","0,1",">","into","an","unbounded","interval","by","replacing","mean","(","y",")","with","log-odds","ratio",":",":","log-odds_ratio_i","=","log","(","mean","(","y_i",")","\/mean","(","y_not_i",")",")","This","is","called","binary","model",".","The","estimation","of","parameters","of","this","model","is",",","however",",","tricky","and","sometimes","it","fails","fatally",".","In","these","situations",",","it","is","better","to","use","beta","model",",","which","generally","delivers","slightly","worse","accuracy","than","binary","model","but","does","not","suffer","from","fatal","failures",".","Parameters","--","--","--","--","--","verbose",":","int","integer","indicating","verbosity","of","the","output",".","0","for","none",".","cols",":","list","a","list","of","columns","to","encode",",","if","None",",","all","string","columns","will","be","encoded",".","drop_invariant",":","bool","boolean","for","whether","or","not","to","drop","encoded","columns","with","0","variance",".","return_df",":","bool","boolean","for","whether","to","return","a","pandas","DataFrame","from","transform","(","otherwise","it","will","be","a","numpy","array",")",".","handle_missing",":","str","options","are","'return_nan","'",",","'error","'","and","'value","'",",","defaults","to","'value","'",",","which","returns","the","prior","probability",".","handle_unknown",":","str","options","are","'return_nan","'",",","'error","'","and","'value","'",",","defaults","to","'value","'",",","which","returns","the","prior","probability",".","model",":","str","options","are","'pooled","'",",","'beta","'",",","'binary","'","and","'independent","'",",","defaults","to","'independent","'",".","randomized",":","bool",",","adds","normal","(","Gaussian",")","distribution","noise","into","training","data","in","order","to","decrease","overfitting","(","testing","data","are","untouched",")",".","sigma",":","float","standard","deviation","(","spread","or","``","width","''",")","of","the","normal","distribution",".","Example","--","--","--","-",">",">",">","from","category_encoders","import","*",">",">",">","import","pandas","as","pd",">",">",">","from","sklearn.datasets","import","fetch_openml",">",">",">","bunch","=","fetch_openml","(","name=","''","house_prices","''",",","as_frame=True",")",">",">",">","display_cols","=","[","``","Id","''",",","``","MSSubClass","''",",","``","MSZoning","''",",","``","LotFrontage","''",",","``","YearBuilt","''",",","``","Heating","''",",","``","CentralAir","''","]",">",">",">","y","=","bunch.target",">",">",">","X","=","pd.DataFrame","(","bunch.data",",","columns=bunch.feature_names",")","[","display_cols","]",">",">",">","enc","=","JamesSteinEncoder","(","cols=","[","'CentralAir","'",",","'Heating","'","]",")",".fit","(","X",",","y",")",">",">",">","numeric_dataset","=","enc.transform","(","X",")",">",">",">","print","(","numeric_dataset.info","(",")",")","<","class","'pandas.core.frame.DataFrame","'",">","RangeIndex",":","1460","entries",",","0","to","1459","Data","columns","(","total","7","columns",")",":","#","Column","Non-Null","Count","Dtype","--","-","--","--","--","--","--","--","--","--","--","--","--","--","-","0","Id","1460","non-null","float64","1","MSSubClass","1460","non-null","float64","2","MSZoning","1460","non-null","object","3","LotFrontage","1201","non-null","float64","4","YearBuilt","1460","non-null","float64","5","Heating","1460","non-null","float64","6","CentralAir","1460","non-null","float64","dtypes",":","float64","(","6",")",",","object","(","1",")","memory","usage",":","80.0+","KB","None","References","--","--","--","--","--","..","[","1","]","Parametric","empirical","Bayes","inference",":","Theory","and","applications",",","equations","1.19","&","1.20",",","from","https",":","\/\/www.jstor.org\/stable\/2287098","..","[","2","]","Empirical","Bayes","for","multiple","sample","sizes",",","from","http",":","\/\/chris-said.io\/2017\/05\/03\/empirical-bayes-for-multiple-sample-sizes\/","..","[","3","]","Shrinkage","Estimation","of","Log-odds","Ratios","for","Comparing","Mobility","Tables",",","from","https",":","\/\/journals.sagepub.com\/doi\/abs\/10.1177\/0081175015570097","..","[","4","]","Stein","'s","paradox","and","group","rationality",",","from","http",":","\/\/www.philos.rug.nl\/~romeyn\/presentation\/2017_romeijn_-_Paris_Stein.pdf","..","[","5","]","Stein","'s","Paradox","in","Statistics",",","from","http",":","\/\/statweb.stanford.edu\/~ckirby\/brad\/other\/Article1977.pdf"]
code: def _transform(self, X, y=None):
      X = self.ordinal_encoder.transform(X)
  
      if self.handle_unknown == "error":
          if X[self.cols].isin([-1]).any().any():
              raise ValueError(
                  "Unexpected categories found in dataframe"
              )
  
      # Loop over columns and replace nominal values with WOE
      X = self._score(X, y)
      return X
  
file_path: category_encoders/category_encoders/james_stein.py
imports: import numpy
  import pandas
  import scipy
  from scipy import optimize
  from category_encoders.ordinal import OrdinalEncoder
  import category_encoders.utils
  from sklearn.utils.random import check_random_state
label_desc: Use image node_id 3 for calling the JamesSteinEncoder obj's underlying member method code with example usage: obj._transform(X, y) and returns: X