Hide keyboard shortcuts

Hot-keys on this page

r m x p   toggle line displays

j k   next/prev highlighted chunk

0   (zero) top of page

1   (one) first highlighted chunk

1# This file is part of Patsy 

2# Copyright (C) 2011-2013 Nathaniel Smith <njs@pobox.com> 

3# See file LICENSE.txt for license information. 

4 

5# This module sets up the namespace of stuff that is available to formulas by 

6# default. All formulas are interpreted in an environment that acts as if 

7# from patsy.builtins import * 

8# has been executed. (Of course, you can also execute this yourself if you 

9# want to use these in your regular code for some reason.) 

10 

11__all__ = ["I", "Q"] 

12 

13from patsy.contrasts import ContrastMatrix, Treatment, Poly, Sum, Helmert, Diff 

14__all__ += ["ContrastMatrix", "Treatment", "Poly", "Sum", "Helmert", "Diff"] 

15 

16from patsy.categorical import C 

17__all__ += ["C"] 

18 

19from patsy.state import center, standardize, scale 

20__all__ += ["center", "standardize", "scale"] 

21 

22from patsy.splines import bs 

23__all__ += ["bs"] 

24 

25from patsy.mgcv_cubic_splines import cr, cc, te 

26__all__ += ["cr", "cc", "te"] 

27 

28def I(x): 

29 """The identity function. Simply returns its input unchanged. 

30 

31 Since Patsy's formula parser ignores anything inside a function call 

32 syntax, this is useful to 'hide' arithmetic operations from it. For 

33 instance:: 

34 

35 y ~ x1 + x2 

36 

37 has ``x1`` and ``x2`` as two separate predictors. But in:: 

38 

39 y ~ I(x1 + x2) 

40 

41 we instead have a single predictor, defined to be the sum of ``x1`` and 

42 ``x2``.""" 

43 return x 

44 

45def test_I(): 

46 assert I(1) == 1 

47 assert I(None) is None 

48 

49def Q(name): 

50 """A way to 'quote' variable names, especially ones that do not otherwise 

51 meet Python's variable name rules. 

52 

53 If ``x`` is a variable, ``Q("x")`` returns the value of ``x``. (Note that 

54 ``Q`` takes the *string* ``"x"``, not the value of ``x`` itself.) This 

55 works even if instead of ``x``, we have a variable name that would not 

56 otherwise be legal in Python. 

57 

58 For example, if you have a column of data named ``weight.in.kg``, then you 

59 can't write:: 

60 

61 y ~ weight.in.kg 

62 

63 because Python will try to find a variable named ``weight``, that has an 

64 attribute named ``in``, that has an attribute named ``kg``. (And worse 

65 yet, ``in`` is a reserved word, which makes this example doubly broken.) 

66 Instead, write:: 

67 

68 y ~ Q("weight.in.kg") 

69 

70 and all will be well. Note, though, that this requires embedding a Python 

71 string inside your formula, which may require some care with your quote 

72 marks. Some standard options include:: 

73 

74 my_fit_function("y ~ Q('weight.in.kg')", ...) 

75 my_fit_function('y ~ Q("weight.in.kg")', ...) 

76 my_fit_function("y ~ Q(\\"weight.in.kg\\")", ...) 

77 

78 Note also that ``Q`` is an ordinary Python function, which means that you 

79 can use it in more complex expressions. For example, this is a legal 

80 formula:: 

81 

82 y ~ np.sqrt(Q("weight.in.kg")) 

83 """ 

84 from patsy.eval import EvalEnvironment 

85 env = EvalEnvironment.capture(1) 

86 try: 

87 return env.namespace[name] 

88 except KeyError: 

89 raise NameError("no data named %r found" % (name,)) 

90 

91def test_Q(): 

92 a = 1 

93 assert Q("a") == 1 

94 assert Q("Q") is Q 

95 from nose.tools import assert_raises 

96 assert_raises(NameError, Q, "asdfsadfdsad") 

97