Annotation of OpenXM/src/asir-contrib/packages/doc/gtt_ekn/gtt_ekn-en.texi, Revision 1.2
1.2 ! takayama 1: %% $OpenXM$
! 2: %% xetex gtt_ekn-en.texi (.texi までつける. )
! 3: %% 英語版, 以下コメントは @comment で始める. \input texinfo 以降は普通の tex 命令は使えない.
! 4: \input texinfo-ja
1.1 takayama 5: @iftex
6: @catcode`@#=6
1.2 ! takayama 7: @def@fref#1{@xrefX[#1,,@code{#1},,,]}
! 8: @def@b#1{{@bf #1}}
1.1 takayama 9: @catcode`@#=@other
10: @end iftex
11: @overfullrule=0pt
1.2 ! takayama 12: @documentlanguage en
! 13: @c -*-texinfo-*-
! 14: @comment %**start of header
! 15: @comment --- おまじない終り ---
! 16:
! 17: @comment --- GNU info ファイルの名前 ---
! 18: @setfilename xyzman
! 19:
! 20: @comment --- タイトル ---
! 21: @settitle HGM for two way contingency table
! 22:
! 23: @comment %**end of header
! 24: @comment %@setchapternewpage odd
! 25:
! 26: @comment --- おまじない ---
! 27: @ifinfo
! 28: @macro fref{name}
! 29: @ref{\name\,,@code{\name\}}
! 30: @end macro
! 31: @end ifinfo
! 32:
! 33: @iftex
! 34: @comment @finalout
! 35: @end iftex
! 36:
1.1 takayama 37: @titlepage
1.2 ! takayama 38: @comment --- おまじない終り ---
! 39:
! 40: @comment --- タイトル, バージョン, 著者名, 著作権表示 ---
! 41: @title HGM functions for two way contingency tables.
! 42: @subtitle HGM functions for two way contingency tables on Risa/Asir
! 43: @subtitle Version 3.0
! 44: @subtitle June 11, 2019
! 45:
! 46: @author by Y.Goto, Y.Tachibana, N.Takayama
! 47: @page
! 48: @vskip 0pt plus 1filll
! 49: Copyright @copyright{} Risa/Asir committers
! 50: 2004--2019. All rights reserved.
1.1 takayama 51: @end titlepage
52:
1.2 ! takayama 53: @comment --- おまじない ---
1.1 takayama 54: @synindex vr fn
1.2 ! takayama 55: @comment --- おまじない終り ---
! 56:
! 57: @comment --- @node は GNU info, HTML 用 ---
! 58: @comment --- @node の引数は node-name, next, previous, up ---
1.1 takayama 59: @node Top,, (dir), (dir)
60:
1.2 ! takayama 61: @comment --- @menu は GNU info, HTML 用 ---
! 62: @comment --- chapter 名を正確に並べる ---
! 63: @comment --- この文書では chapter XYZ, Chapter Index がある.
! 64: @comment --- Chapter XYZ には section XYZについて, section XYZに関する関数がある.
1.1 takayama 65: @menu
1.2 ! takayama 66: * About this document::
! 67: * Functions of HGM for two way contingency tables::
! 68: * Modular method
! 69: * Binary splitting
1.1 takayama 70: * Index::
71: @end menu
72:
1.2 ! takayama 73: @comment --- chapter の開始 ---
! 74: @comment --- 親 chapter 名を正確に. 親がない場合は Top ---
! 75: @node About this document,,, Top
! 76: @chapter About this document
! 77:
! 78: This document explains Risa/Asir functions for two way contingency
! 79: tables by
! 80: HGM(holonomic gradient method).
! 81: Loading the package:
! 82: @example
! 83: import("gtt_ekn3.rr");
! 84: @end example
! 85: The package gtt_ekn3.rr is a major version up of gtt_ekn.rr.
! 86: @noindent
! 87: In order to download the latest asir-contrib package,
! 88: please use the asir_contrib_update() as follows.
! 89: @example
! 90: import("names.rr");
! 91: asir_contrib_update(|update=1);
! 92: @end example
! 93: @noindent
! 94: References cited in this document.
! 95: @itemize @bullet
! 96: @item [GM2016]
! 97: Y.Goto, K.Matsumoto, Pfaffian equations and contiguity relations of the hypergeometric function of type (k+1,k+n+2) and their applications,
! 98: @uref{http://arxiv.org/abs/1602.01637,arxiv:1602.01637 (version 1)}
! 99: @item [T2016]
! 100: Y.Tachibana, difference holonomic gradient method by the modular method.
! 101: 2016, master thesis of Kobe University (in Japanese).
! 102: @item [GTT2016]
! 103: Y.Goto, Y.Tachibana, N.Takayama,
! 104: implementation of difference holonomic gradient method for two way contingency tables.
! 105: RIMS kokyuroku (in Japanese).
! 106: @item [TGKT]
! 107: Y.Tachibana, Y.Goto, T.Koyama, N.Takayama,
! 108: Holonomic Gradient Method for Two Way Contingency Tables,
! 109: @uref{https://arxiv.org/abs/1803.04170, arxiv:1803.04170 (the 2nd version)}
! 110: @item [TKT2015]
! 111: N.Takayama, S.Kuriki, A.Takemura,
! 112: A-hypergeometric distributions and Newton polytopes.
! 113: @uref{http://arxiv.org/abs/1510.02269,arxiv:1510.02269}
! 114: @end itemize
! 115:
! 116: The changelogs are described only in the Japanese version of this document.
1.1 takayama 117:
1.2 ! takayama 118: @node Functions of HGM for two way contingency tables,,, Top
! 119: @chapter Functions of HGM for two way contingency tables
! 120:
! 121: @comment --- section ``実験的関数'' の subsection xyz_abc
! 122: @comment --- subsection xyz_pqr xyz_stu がある.
1.1 takayama 123: @menu
1.2 ! takayama 124: * gtt_ekn3.gmvector::
! 125: * gtt_ekn3.nc::
! 126: * gtt_ekn3.lognc::
! 127: * gtt_ekn3.expectation::
! 128: * gtt_ekn3.setup::
! 129: * gtt_ekn3.upAlpha::
! 130: * gtt_ekn3.cmle::
! 131: * gtt_ekn3.set_debug_level::
! 132: * gtt_ekn3.contiguity_mat_list_2::
! 133: * gtt_ekn3.show_path::
! 134: * gtt_ekn3.get_svalue::
! 135: * gtt_ekn3.assert1::
! 136: * gtt_ekn3.assert2::
! 137: * gtt_ekn3.assert3::
! 138: * gtt_ekn3.prob1::
1.1 takayama 139: @end menu
140:
1.2 ! takayama 141: @node Hypergeometric function E(k,n),,, Functions of HGM for two way contingency tables
! 142: @section Hypergeometric function E(k,n)
! 143:
! 144: @comment **********************************************************
! 145: @comment --- ◯◯◯◯ の説明
! 146: @comment --- 個々の関数の説明の開始 ---
! 147: @comment --- section 名を正確に ---
! 148: @node gtt_ekn3.gmvector,,, hypergeometric function E(k,n)
! 149: @subsection @code{gtt_ekn3.gmvector}
! 150: @comment --- 索引用キーワード
! 151: @findex gtt_ekn3.gmvector
! 152:
! 153: @table @t
! 154: @item gtt_ekn3.gmvector(@var{beta},@var{p})
! 155: :: It returns the value of the hypergeometric function E(k,n) and its derivatives associated to the two way contingency table with the marginal sum @var{beta}, parameter @var{p} (cell probability).
! 156: @item
! 157: It is an alias of gtt_ekn3.ekn_cBasis_2(@var{beta},@var{p})
! 158: @end table
! 159:
! 160: @comment --- 引数の簡単な説明 --- 以下まだ書いてない.
! 161: @table @var
! 162: @item return
! 163: vector, see below.
! 164: @item beta
! 165: a list of the row sum and the colum sum.
! 166: @item p
! 167: the parameter.
! 168: @end table
! 169:
! 170: @comment --- ここで関数の詳しい説明 ---
! 171: @comment --- @itemize〜@end itemize は箇条書き ---
! 172: @comment --- @bullet は黒点付き ---
! 173: @itemize @bullet
! 174: @item
! 175: The name gmvector is an abreviation of the Gauss-Manin vector defined in [GM2016].
! 176: @item
! 177: The return value is the vector S in the page 23 (the section 6) of
! 178: [GM2016].
! 179: This is a constant multiple of the vector F in the section 4 of [GM2016]
! 180: and the constant is determined so that the first element of the vector
! 181: is equal to the value of the series S in the section 6 of [GM2016].
! 182: @item
! 183: Consider an r1 x r2 contingency table.
! 184: Put m+1=r1, n+1=r2.
! 185: The normalizing constant Z is the sum of p^u/u!
! 186: where u is an (m+1) x (n+1) matrix (contingency table) with non-negative integer entries.
! 187: The sum is taken over u such that the row sum and the column sum of u
! 188: are equal to @var{beta}, see [TKT2015], [GM2016], [TGKT].
! 189: The first element of S (polynomial in this case) is equal to this polynomial Z
! 190: with a normalized p =
! 191: @verbatim
! 192: [[1,y11,...,y1n],
! 193: [1,y21,...,y2n],...,
! 194: [1,ym1, ...,ymn],
! 195: [1,1, ..., 1]]
! 196: @end verbatim
! 197: @comment ekn/Talks/2015-12-3-goto.tex
! 198: @item
! 199: The following options are also accepted by several functions, e.g., gmvector, expectation, nc.
! 200: @item
! 201: A distributed computation is turned on by the
! 202: option crt=1 (crt = Chinese remainder theorem)
! 203: [T2016].
! 204: The default is crt=0.
! 205: Parameters for the distributed computation are set by
! 206: gtt_ekn3.setup.
! 207: @item
! 208: Option bs=1. The matrix factorial, which is a product of contiguity relation matrices
! 209: with different parameters, is evaluated by the binary splitting method.
! 210: Examples: gtt_ekn3.assert2(15|bs=1)) (3x3 matrix), gtt_ekn3.test5x5(20|bs=1))(5x5 matrix).
! 211: The default is bs=0.
! 212: @item
! 213: Option path. A choice of algorithms to apply contiguity relations.
! 214: path=2 (the algorithm given in [GM2016]). path=3 (the algorithm given in [TGKT]
! 215: (revised version)).
! 216: The default is path=3.
! 217: @item
! 218: Option interval. The period of the intermediate reduction of numerators
! 219: and denominators.
! 220: A relevant value of ``interval'' will lead to an efficient evaluation,
! 221: but no optimal value of it is known. See [TGKT] as to details.
! 222: The default is no intermediate reduction.
! 223: @item
! 224: Option x=1. It opens a window for each process.
! 225: @end itemize
! 226:
! 227: @comment --- @example〜@end example は実行例の表示 ---
! 228: Example: A 2 x 2 contingency table. The row sum is [5,1] and column sum is [3,3].
! 229: The parameter (cell probability) is
! 230: [[1/2,1/3],[1/7,1/5]].
! 231: @example
! 232: [3000] import("gtt_ekn3.rr");
! 233: [3001] gtt_ekn3.gmvector([[5,1],[3,3]],[[1/2,1/3],[1/7,1/5]])
! 234: [775/27783]
! 235: [200/9261]
! 236: @end example
! 237:
1.1 takayama 238:
1.2 ! takayama 239: Example: Interval option.
! 240: @example
! 241: [4009] P=gtt_ekn3.prob1(5,5,100);
! 242: [[[100,200,300,400,500],[100,200,300,400,500]],
! 243: [[1,1/2,1/3,1/5,1/7],[1,1/11,1/13,1/17,1/19],
! 244: [1,1/23,1/29,1/31,1/37],[1,1/41,1/43,1/47,1/53],[1,1,1,1,1]]]
1.1 takayama 245:
1.2 ! takayama 246: [4010] util_timing(quote(gtt_ekn3.gmvector(P[0],P[1])[1];
! 247: [cpu,72.852,gc,0,memory,4462742364,real,72.856]
1.1 takayama 248:
1.2 ! takayama 249: [4011] util_timing(quote(gtt_ekn3.gmvector(P[0],P[1]|interval=100)))[1];
! 250: [cpu,67.484,gc,0,memory,3535280544,real,67.4844]
! 251: @end example
1.1 takayama 252:
253:
1.2 ! takayama 254: @comment --- 参照(リンク)を書く ---
! 255: @table @t
! 256: @item Refer to
! 257: @ref{gtt_ekn3.setup}
! 258: @ref{gtt_ekn3.pfaffian_basis}
! 259: @end table
1.1 takayama 260:
261:
1.2 ! takayama 262: @comment **********************************************************
! 263: @node gtt_ekn3.nc,,, hypergeometric function E(k,n)
! 264: @subsection @code{gtt_ekn3.nc}
! 265: @comment --- 索引用キーワード
! 266: @findex gtt_ekn3.nc
1.1 takayama 267:
268: @table @t
1.2 ! takayama 269: @item gtt_ekn3.nc(@var{beta},@var{p})
! 270: :: It returns the normalizing constant Z and its derivatives for the two way contingency tables
! 271: with the marginal sum @var{beta} and the parameter (cell probability) @var{p}.
! 272: See, e.g., [TKT2015], [TGKT] as to the definition of $Z$.
1.1 takayama 273: @end table
274:
1.2 ! takayama 275: @comment --- 引数の簡単な説明 --- 以下まだ書いてない.
1.1 takayama 276: @table @var
277: @item return
1.2 ! takayama 278: A list [Z,[[d_11 Z, d_12 Z, ...], ..., [d_m1 Z, d_m2 Z, ...., d_mn Z]]]
! 279: where d_ij Z denotes the partial derivative of Z with respect to the parameter
! 280: p_ij.
! 281: @item beta
! 282: The row sum and the column sum.
! 283: @item p
! 284: The parameter (cell probability).
1.1 takayama 285: @end table
286:
1.2 ! takayama 287: @comment --- ここで関数の詳しい説明 ---
! 288: @comment --- @itemize〜@end itemize は箇条書き ---
! 289: @comment --- @bullet は黒点付き ---
1.1 takayama 290: @itemize @bullet
1.2 ! takayama 291: @item
! 292: The function nc obtains Z from the value of gmvector by Prop 7.1 of [GM2016].
! 293: @item
! 294: See options for gmvector.
1.1 takayama 295: @end itemize
296:
1.2 ! takayama 297: @comment --- @example〜@end example は実行例の表示 ---
! 298: Example: A 2x3 contingency table.
1.1 takayama 299: @example
1.2 ! takayama 300: [2237] gtt_ekn3.nc([[4,5],[2,4,3]],[[1,1/2,1/3],[1,1,1]]);
1.1 takayama 301: [4483/124416,[ 353/7776 1961/15552 185/1728 ]
302: [ 553/20736 1261/15552 1001/13824 ]]
303: @end example
304:
305:
1.2 ! takayama 306: @comment --- 参照(リンク)を書く ---
! 307: @table @t
! 308: @item Refer to
! 309: @ref{gtt_ekn3.setup}
! 310: @ref{gtt_ekn3.lognc}
! 311: @end table
! 312:
! 313:
! 314:
! 315: @comment **********************************************************
! 316: @node gtt_ekn3.lognc,,, hypergeometric function E(k,n)
! 317: @subsection @code{gtt_ekn3.lognc}
! 318: @comment --- 索引用キーワード
! 319: @findex gtt_ekn3.lognc
! 320:
! 321: @table @t
! 322: @item gtt_ekn3.lognc(@var{beta},@var{p})
! 323: :: It returns the logarithm of Z.
! 324: @end table
! 325:
! 326: @comment --- 引数の簡単な説明 --- 以下まだ書いてない.
! 327: @table @var
! 328: @item return
! 329: A list [log(Z), [[d_11 log(Z), d_12 log(Z), ...], [d_21 log(Z),...], ... ]
! 330: @end table
! 331:
! 332: @comment --- ここで関数の詳しい説明 ---
! 333: @comment --- @itemize〜@end itemize は箇条書き ---
! 334: @comment --- @bullet は黒点付き ---
! 335: @itemize @bullet
! 336: @item
! 337: This function is used to solve the conditional maximal likelihood estimation [TKT2015].
! 338: @item
! 339: See options of gmvector.
! 340: @end itemize
1.1 takayama 341:
1.2 ! takayama 342: @comment --- @example〜@end example は実行例の表示 ---
! 343: Example: A 2x3 contingency table. The first element is an approximate value of log(Z).
! 344: The rests are exact values when the arguments of lognc are rational numbers.
! 345: @example
! 346: [2238] gtt_ekn3.lognc([[4,5],[2,4,3]],[[1,1/2,1/3],[1,1,1]]);
! 347: [-3.32333832422461674630,[ 5648/4483 15688/4483 13320/4483 ]
! 348: [ 3318/4483 10088/4483 9009/4483 ]]
! 349: @end example
! 350:
! 351: @comment --- 参照(リンク)を書く ---
! 352: @table @t
! 353: @item Refer to
! 354: @ref{gtt_ekn3.setup}
! 355: @ref{gtt_ekn3.nc}
! 356: @end table
! 357:
! 358:
! 359: @comment **********************************************************
! 360: @node gtt_ekn3.expectation,,, hypergeometric function E(k,n)
! 361: @subsection @code{gtt_ekn3.expectation}
! 362: @comment --- 索引用キーワード
! 363: @findex gtt_ekn3.expectation
! 364:
! 365: @table @t
! 366: @item gtt_ekn3.expectation(@var{beta},@var{p})
! 367: :: It returns the expectation of the hypergeometric distribution with the mariginal sum @var{beta} and the parameter @var{p}.
! 368: @end table
! 369:
! 370: @comment --- 引数の簡単な説明 --- 以下まだ書いてない.
! 371: @table @var
! 372: @item return
! 373: The expectation of each cell.
! 374: @end table
! 375:
! 376: @comment --- ここで関数の詳しい説明 ---
! 377: @comment --- @itemize〜@end itemize は箇条書き ---
! 378: @comment --- @bullet は黒点付き ---
! 379: @itemize @bullet
! 380: @item
! 381: It is an implementation of Algorithm 7.8 of [GM2016]. A faster algorithm in [TGKT]
! 382: is chosen with the default option path=3.
! 383: @item
! 384: By the option ``index'', it returns only the expections standing for the ``index''.
! 385: For example, index=[[0,0],[1,1]] in the case of a 2 x 2 contingency table,
! 386: it returns the expectations for the (2,1) and (2.2) elements
! 387: (0 stands for no evaluation and 1 stands for doing the evaluation).
! 388: @item
! 389: See also options of gmvector.
! 390: @end itemize
! 391:
! 392: @comment --- @example〜@end example は実行例の表示 ---
! 393:
! 394: Examples of the evaluation of expectations for 2 x 2 and 3 x 3 contingency tables.
! 395: @example
! 396: [2235] gtt_ekn3.expectation([[1,4],[2,3]],[[1,1/3],[1,1]]);
! 397: [ 2/3 1/3 ]
! 398: [ 4/3 8/3 ]
! 399: [2236] gtt_ekn3.expectation([[4,5],[2,4,3]],[[1,1/2,1/3],[1,1,1]]);
! 400: [ 5648/4483 7844/4483 4440/4483 ]
! 401: [ 3318/4483 10088/4483 9009/4483 ]
! 402:
! 403: [2442] gtt_ekn3.expectation([[4,14,9],[11,6,10]],[[1,1/2,1/3],[1,1/5,1/7],[1,1,1]]);
! 404: [ 207017568232262040/147000422096729819 163140751505489940/147000422096729819
! 405: 217843368649167296/147000422096729819 ]
! 406: [ 1185482401011137878/147000422096729819 358095302885438604/147000422096729819
! 407: 514428205457640984/147000422096729819 ]
! 408: [ 224504673820628091/147000422096729819 360766478189450370/147000422096729819
! 409: 737732646860489910/147000422096729819 ]
! 410: @end example
! 411:
! 412:
! 413: @comment --- 参照(リンク)を書く ---
! 414: @table @t
! 415: @item Refer to
! 416: @ref{gtt_ekn3.setup}
! 417: @ref{gtt_ekn3.nc}
! 418: @end table
! 419:
! 420:
! 421: @comment **********************************************************
! 422: @comment --- ◯◯◯◯ の説明
! 423: @comment --- 個々の関数の説明の開始 ---
! 424: @comment --- section 名を正確に ---
! 425: @node gtt_ekn3.setup,,, hypergeometric function E(k,n)
! 426: @subsection @code{gtt_ekn3.setup}
! 427: @comment --- 索引用キーワード
! 428: @findex gtt_ekn3.setup
! 429:
! 430: @table @t
! 431: @item gtt_ekn3.setup()
! 432: :: It sets parameters for a distributed computation or report the current values of the parameters.
! 433: @end table
! 434:
! 435: @comment --- 引数の簡単な説明 --- 以下まだ書いてない.
! 436: @table @var
! 437: @item return
! 438: 0
! 439: @end table
! 440:
! 441: @comment --- ここで関数の詳しい説明 ---
! 442: @comment --- @itemize〜@end itemize は箇条書き ---
! 443: @comment --- @bullet は黒点付き ---
! 444: @itemize @bullet
! 445: @item It shows the number of processes, the number of primes, the minimal prime which is used.
! 446: @item Option nps : the number of processes.
! 447: @item Option nprm : the number of the primes used. When the argument of this option is a string, a list of primes are supposed to be given in the file by the name given by the string.
! 448: @item Option minp : the minimal prime. It is used with the option nprm. It generates nprm primes more than or equal to minp. When the option fgp is given, the generated primes are stored in the file of the name fgp.
! 449: @item The default values of nps, nprm, and fgp are nps=1. nprm=10. fgp=0 (no saving).
! 450: @item The option report=1 shows the current parameters.
! 451: @item Option subprogs=[file1,file2,...]. These files are loaded to the child processes. The default value is subprogs=["gtt_ekn3/childprocess.rr"].
! 452: @item The function gtt_ekn3.set_debug_level(Mode) is used to set a debug message level ( Ekn_debug )
! 453: @end itemize
! 454:
! 455: @comment --- @example〜@end example は実行例の表示 ---
! 456: Example: Generating a list of primes and outputing them to the file p.txt.
! 457: @example
! 458: gtt_ekn3.setup(|nps=2,nprm=20,minp=10^10,fgp="p.txt")$
! 459: @end example
! 460:
! 461: Example: Evaluating the gmvector by the Chinese remainder theorem (crt).
! 462: @example
! 463: [2867] gtt_ekn3.setup(|nprm=20,minp=10^20);
! 464: [2868] N=2; T2=gtt_ekn3.gmvector([[36*N,13*N-1],[38*N-1,11*N]],
! 465: [[1,(1-1/N)/56],[1,1]] | crt=1)$
! 466: @end example
! 467:
! 468:
! 469: @comment --- 参照(リンク)を書く ---
! 470: @table @t
! 471: @item Refer to
! 472: @ref{gtt_ekn3.nc}
! 473: @ref{gtt_ekn3.gmvector}
! 474: @end table
! 475:
! 476:
! 477: @comment **********************************************************
! 478: @comment --- ◯◯◯◯ の説明
! 479: @comment --- 個々の関数の説明の開始 ---
! 480: @comment --- section 名を正確に ---
! 481: @node gtt_ekn3.upAlpha,,, hypergeometric function E(k,n)
! 482: @node gtt_ekn3.downAlpha,,, hypergeometric function E(k,n)
! 483: @subsection @code{gtt_ekn3.upAlpha}, @code{gtt_ekn3.downAlpha}
! 484: @comment --- 索引用キーワード
! 485: @findex gtt_ekn3.upAlpha
! 486: @findex gtt_ekn3.downAlpha
! 487:
! 488: @table @t
! 489: @item gtt_ekn3.upAlpha(@var{i},@var{k},@var{n})
! 490: @item gtt_ekn3.downAlpha(@var{i},@var{k},@var{n})
! 491: ::
! 492: @end table
! 493:
! 494: @comment --- 引数の簡単な説明 --- 以下まだ書いてない.
! 495: @table @var
! 496: @item i
! 497: It indicates the direction of the contiguity relation to get. In other words, the contiguity relation from a_i to a_i+1 (from a_i to a_i-1, the downAlpha case) is obtained.
! 498: @item k, n
! 499: The contiguity relation for the hypergeometric function E(k+1,n+k+2) standing for the (k+1)×(n+1) contingency table is obtained.
! 500: @item return
! 501: The matrix representation of the contiguity relation with respect to the pfaffian_basis
! 502: (see gtt_ekn3.pfaffian_basis). See also Cor 6.3 of [GM2016].
! 503: @end table
! 504:
! 505: @comment --- ここで関数の詳しい説明 ---
! 506: @comment --- @itemize〜@end itemize は箇条書き ---
! 507: @comment --- @bullet は黒点付き ---
! 508: @itemize @bullet
! 509: @item
! 510: The function upAlpha returns the matrix U_i of Cor 6.3 in [GM2016].
! 511: @item
! 512: The function downAlpha is for the contiguity relation from a_i to a_i-1 .
! 513: @item
! 514: The function marginaltoAlpha([row sum,column sum]) translates the marginal sum to values of a_i's.
! 515: @item
! 516: The function pfaffian_basis returns F in section 4 of [GM2016]. See the example below.
! 517: @item
! 518: The variables a_i and x_i_j can be specialized to numbers by the optional arguments arule and xrule. See the example below.
! 519: @end itemize
! 520:
! 521: @comment --- @example〜@end example は実行例の表示 ---
! 522: Example: 2x2 contingency table (E(2,4)), 2x3 contingency table (E(2,5)).
! 523: Outputs of [2221] --- [2225] are left out.
! 524: @example
! 525: [2221] gtt_ekn3.marginaltoAlpha([[1,4],[2,3]]);
! 526: [[a_0,-4],[a_1,-1],[a_2,3],[a_3,2]]
! 527: [2222] gtt_ekn3.upAlpha(1,1,1); // contiguity relation of E(2,4)
! 528: // for the a_1 direction
! 529: [2223] gtt_ekn3.upAlpha(2,1,1); // E(2,4), a_2 direction
! 530: [2224] gtt_ekn3.upAlpha(3,1,1); // E(2,4), a_3 direction
! 531: [2225] function f(x_1_1);
! 532: [2232] gtt_ekn3.pfaffian_basis(f(x_1_1),1,1);
! 533: [ f(x_1_1) ]
! 534: [ (f{1}(x_1_1)*x_1_1)/(a_2) ]
! 535: [2233] function f(x_1_1,x_1_2);
! 536: f() redefined.
! 537: [2234] gtt_ekn3.pfaffian_basis(f(x_1_1,x_1_2),1,2); // E(2,5), 2*3 contingency table
! 538: [ f(x_1_1,x_1_2) ]
! 539: [ (f{1,0}(x_1_1,x_1_2)*x_1_1)/(a_2) ]
! 540: [ (f{0,1}(x_1_1,x_1_2)*x_1_2)/(a_3) ]
! 541:
! 542: [2235] RuleA=[[a_2,1/3],[a_3,1/2]]$ RuleX=[[x_1_1,1/5]]$
! 543: base_replace(gtt_ekn3.upAlpha(1,1,1),append(RuleA,RuleX))
! 544: -gtt_ekn3.upAlpha(1,1,1 | arule=RuleA, xrule=RuleX);
! 545:
! 546: [ 0 0 ]
! 547: [ 0 0 ]
! 548:
! 549: @end example
! 550:
! 551:
! 552: @comment --- 参照(リンク)を書く ---
! 553: @table @t
! 554: @item Refer to
! 555: @ref{gtt_ekn3.nc}
! 556: @ref{gtt_ekn3.gmvector}
! 557: @end table
! 558:
! 559:
! 560:
! 561: @comment **********************************************************
! 562: @comment --- ◯◯◯◯ の説明
! 563: @comment --- 個々の関数の説明の開始 ---
! 564: @comment --- section 名を正確に ---
! 565: @node gtt_ekn3.cmle,,, hypergeometric function E(k,n)
! 566: @subsection @code{gtt_ekn3.cmle}
! 567: @comment --- 索引用キーワード
! 568: @findex gtt_ekn3.cmle
! 569:
! 570: @table @t
! 571: @item gtt_ekn3.cmle(@var{u})
! 572: :: It finds a parameter p (cell probability) which maximizes P(U=u | row sum, column sum = these of U) for given observed data u. The value of p is an approximate value.
! 573: @end table
! 574:
! 575: @comment --- 引数の簡単な説明 --- 以下まだ書いてない.
! 576: @table @var
! 577: @item u
! 578: The observed data.
! 579: @item return
! 580: An estimated parameter p
! 581: @end table
! 582:
! 583: @comment --- ここで関数の詳しい説明 ---
! 584: @comment --- @itemize〜@end itemize は箇条書き ---
! 585: @comment --- @bullet は黒点付き ---
! 586: @itemize @bullet
! 587: @item Todo,
! 588: optional parameter to set the step size of the gradient descent.
! 589: @end itemize
! 590:
! 591: @comment --- @example〜@end example は実行例の表示 ---
! 592: Example: 2x4 contingency table.
! 593: @example
! 594: U=[[1,1,2,3],[1,3,1,1]];
! 595: gtt_ekn3.cmle(U);
! 596: [[ 1 1 2 3 ]
! 597: [ 1 3 1 1 ],[[7,6],[2,4,3,4]], // Data, row sum, column sum
! 598: [ 1 67147/183792 120403/64148 48801/17869 ] // p obtained.
! 599: [ 1 1 1 1 ]]
! 600: @end example
! 601:
! 602:
! 603: @comment --- 参照(リンク)を書く ---
! 604: @table @t
! 605: @item Refer to
! 606: @ref{gtt_ekn3.expectation}
! 607: @end table
! 608:
! 609:
! 610: @comment **********************************************************
! 611: @comment --- ◯◯◯◯ の説明
! 612: @comment --- 個々の関数の説明の開始 ---
! 613: @comment --- section 名を正確に ---
! 614: @node gtt_ekn3.set_debug_level,,, hypergeometric function E(k,n)
! 615: @node gtt_ekn3.contiguity_mat_list_2,,, hypergeometric function E(k,n)
! 616: @node gtt_ekn3.show_path,,, hypergeometric function E(k,n)
! 617: @node gtt_ekn3.get_svalue,,, hypergeometric function E(k,n)
! 618: @node gtt_ekn3.assert1,,, hypergeometric function E(k,n)
! 619: @node gtt_ekn3.assert2,,, hypergeometric function E(k,n)
! 620: @node gtt_ekn3.assert3,,, hypergeometric function E(k,n)
! 621: @node gtt_ekn3.prob1,,, hypergeometric function E(k,n)
! 622: @subsection @code{gtt_ekn3.set_debug_level}, @code{gtt_ekn3.show_path}, @code{gtt_ekn3.get_svalue}, @code{gtt_ekn3.assert1}, @code{gtt_ekn3.assert2}, @code{gtt_ekn3.assert3}, @code{gtt_ekn3.prob1}
! 623: @comment --- 索引用キーワード
! 624: @findex gtt_ekn3.set_debug_level
! 625: @findex gtt_ekn3.contiguity_mat_list_2
! 626: @findex gtt_ekn3.show_path
! 627: @findex gtt_ekn3.get_svalue
! 628: @findex gtt_ekn3.assert1
! 629: @findex gtt_ekn3.assert2
! 630: @findex gtt_ekn3.assert3
! 631: @findex gtt_ekn3.prob1
! 632:
! 633: @table @t
! 634: @item gtt_ekn3.set_debug_level(@var{m})
! 635: :: It sets the level of debug messages.
! 636: @item gtt_ekn3.contiguity_mat_list_2
! 637: :: It returns a list of contiguity directions to be used.
! 638: @item gtt_ekn3.show_path()
! 639: :: It returns the path to apply contiguity relations. See [TGKT].
! 640: @item gtt_ekn3.get_svalue()
! 641: :: It returns the values of the static variables.
! 642: @item gtt_ekn3.assert1(@var{N})
! 643: :: It checks the system by 2x2 contingency tables. @var{N} is proportional to the marginal sum.
! 644: @item gtt_ekn3.assert2(@var{N})
! 645: :: It checks the system by 3x3 contingency tables.
! 646: @item gtt_ekn3.assert3(@var{R1}, @var{R2}, @var{Size})
! 647: :: It checks the distributed computation system by R1 x R2 contingency tables.
! 648: @item gtt_ekn3.prob1(@var{R1},@var{R2},@var{Size})
! 649: :: It returns a test data for R1 x R2 contingency tables in the format
! 650: [marginal sum, parameter p].
! 651: The marginal sum is proportional to @var{Size}. See benchmark tests in [TGKT].
! 652: @end table
! 653:
! 654:
! 655: @comment --- ここで関数の詳しい説明 ---
! 656: @comment --- @itemize〜@end itemize は箇条書き ---
! 657: @comment --- @bullet は黒点付き ---
! 658: @itemize @bullet
! 659: @item
! 660: Let @var{m} be the debug level. When (@var{m} & 0x1) == 0x1, the values by g_mat_fac_test_plain and g_mat_fac_itor (distributed method is used) are compated.
! 661: Note that gtt_ekn3.setup() is properly executed before doing these evaluations.
! 662: @item
! 663: When (@var{m} & 0x2) == 0x2, the arguments of g_mat_fac_test are stored in the file tmp-input-[number].ab.
! 664: @item
! 665: When (@var{m} & 0x4) == 0x4, the arguments for the matrix factorial computation are printed.
! 666: @item
! 667: The function @code{get_svalue} returns the list of the values of @code{[Ekn_plist,Ekn_IDL,Ekn_debug,Ekn_mesg,XRule,ARule,Verbose,Ekn_Rq]}.
! 668: @item
! 669: Options of assert3: ``x=1'' shows the window attached to every subprocess.
! 670: With ``nps=m'', m processes are used to obtain contiguity relations.
! 671: The options crt, interval, ... of gmvector are also accepted.
! 672: In order to display the timing data, do load("gtt_ekn3/ekn_eval-timing.rr"); before starting this function.
! 673: @end itemize
! 674:
! 675: @comment --- @example〜@end example は実行例の表示 ---
! 676: Example:
! 677: @example
! 678: [2846] gtt_ekn3.set_debug_level(0x4);
! 679: [2847] N=2; T2=gtt_ekn3.gmvector([[36*N,13*N-1],[38*N-1,11*N]],
! 680: [[1,(1-1/N)/56],[1,1]])$
! 681: [2848]
! 682: level&0x4: g_mat_fac_test([ 113/112 ]
! 683: [ 1/112 ],[ (t+225/112)/(t^2+4*t+4) (111/112*t+111/112)/(t^2+4*t+4) ]
! 684: [ (1/112)/(t^2+4*t+4) (111/112*t+111/112)/(t^2+4*t+4) ],0,20,1,t)
! 685: Note: we do not use g_mat_fac_itor. Call gtt_ekn3.setup(); to use the crt option.
! 686: level&0x4: g_mat_fac_test([ 67/62944040755546030080000 ]
! 687: [ 1/125888081511092060160000 ],[ (t+24)/(t^2+25*t+46) (2442)/(t^2+25*t+46) ]
! 688: [ (1)/(t^2+25*t+46) (-111*t-111)/(t^2+25*t+46) ],0,73,1,t)
! 689: level&0x4: g_mat_fac_test ------ snip
! 690: @end example
! 691:
! 692: Example.
! 693: @example
! 694: [2659] gtt_ekn3.nc([[4,5,6],[2,4,9]],[[1,1/2,1/3],[1,1/5,1/7],[1,1,1]])$
! 695: [2660] L=matrix_transpose(gtt_ekn3.show_path())$
! 696: [2661] L[2];
! 697: [2 1]
! 698: @end example
! 699: This means that the contiguity relations for the directions [2 1] (a_2, a_1) are used to evaluate the normalizing constant Z.
! 700: L[0] is the contiguity matrix,
! 701: L[1] is a list of the steps to apply for corresponding relations.
! 702:
! 703: Example. Finding a path without evaluations of gmvectors.
! 704: @example
! 705: A=gtt_ekn3.marginaltoAlpha_list([[400,410,1011],[910,411,500]])$
! 706: [2666] gtt_ekn3.contiguity_mat_list_2(A,2,2)$
! 707: [2667] L=matrix_transpose(gtt_ekn3.show_path())$
! 708: [2668] L[2];
! 709: [ 2 1 5 4 3 ]
! 710: [2669] gtt_ekn3.contiguity_mat_list_3(A,2,2)$ // new alg in [TGKT]
! 711: [2670] L=matrix_transpose(gtt_ekn3.show_path())$
! 712: [2671] L[2];
! 713: [2 1] // shorter
! 714: @end example
! 715:
! 716: Example. When assert2() returns 0 matrices, then the results of g_mat_fac_plain and g_mat_fac_int
! 717: agree. In other words, the system is OK.
! 718: @example
! 719: [8859] gtt_ekn3.assert2(1);
! 720: Marginal=[[130,170,353],[90,119,444]]
! 721: P=[[17/100,1,10],[7/50,1,33/10],[1,1,1]]
! 722: Try g_mat_fac_test_int: Note: we do not use g_mat_fac_itor. Call gtt_ekn3.setup(); to use the crt option.
! 723: Timing (int) =0.413916 (CPU) + 0.590723 (GC) = 1.00464 (total), real time=0.990672
! 724:
! 725: Try g_mat_fac_test_plain: Note: we do not use g_mat_fac_itor. Call gtt_ekn3.setup(); to use the crt option.
! 726: Timing (rational) =4.51349 (CPU) + 6.32174 (GC) = 10.8352 (total)
! 727: diff of both method =
! 728: [ 0 0 0 ]
! 729: [ 0 0 0 ]
! 730: [ 0 0 0 ]
! 731: [8860]
! 732:
! 733: [8863] gtt_ekn3.setup(|nprm=100,minp=10^50);
! 734: Number of processes = 1.
! 735: Number of primes = 100.
! 736: Min of plist = 100000000000000000000000000000000000000000000000151.
! 737: 0
! 738: [8864] gtt_ekn3.assert2(1 | crt=1);
! 739: Marginal=[[130,170,353],[90,119,444]]
! 740: P=[[17/100,1,10],[7/50,1,33/10],[1,1,1]]
! 741: Try [[crt,1]]
! 742: ---- snip
! 743: @end example
! 744:
! 745: Example.
! 746: 3x5 contingency table.
! 747: The parameter p (cell probability) is a list of 1/(prime number) 's.
! 748: @example
! 749: @comment grep testnxn ekn/Prog2/*.rr ; grep test_nxn ekn/Prog2/*.rr も見よ.
! 750: [9054] L=gtt_ekn3.prob1(3,5,10 | factor=1, factor_row=3);
! 751: [[[10,20,420],[30,60,90,120,150]],[[1,1/2,1/3,1/5,1/7],[1,1/11,1/13,1/17,1/19],[1,1,1,1,1]]]
! 752: [9055] number_eval(gtt_ekn3.expectation(L[0],L[1]));
! 753: [ 1.65224223218613 ... snip ]
! 754: @end example
! 755:
! 756: Example.
! 757: @example
! 758: [5779] import("gtt_ekn3.rr"); load("gtt_ekn3/ekn_eval-timing.rr");
! 759: [5780] gtt_ekn3.assert3(5,5,100 | nps=32, interval=100);
! 760: -- snip
! 761: Parallel method: Number of process=32, File name tmp-gtt_ekn3/p300.txt is written.
! 762: Number of processes = 32.
! 763: -- snip
! 764: initialPoly of path=3: [ 2.184 0 124341044 2.1831 ] [CPU(s),0,*,real(s)]
! 765: contiguity_mat_list_3 of path=3: [ 0.04 0 630644 9.6774 ] [CPU(s),0,*,real(s)]
! 766: Note: interval option will lead faster evaluation. We do not use g_mat_fac_itor (crt). Call gtt_ekn3.setup(); to use the crt option.
! 767: g_mat_fac of path=3: [ 21.644 0 1863290168 21.6457 ] [CPU(s),0,*,real(s)]
! 768: Done. Saved in 2.ab
! 769: Diff (should be 0)=[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,..., 0,0,0]
! 770: @end example
! 771:
! 772: @comment --- 参照(リンク)を書く ---
! 773: @table @t
! 774: @item Refer to
! 775: @ref{gtt_ekn3.nc}
! 776: @end table
! 777:
! 778:
! 779:
! 780: @node Modular method,,, Top
! 781: @chapter Modular method
! 782:
! 783: @menu
! 784: * gtt_ekn3.chinese_itor::
! 785: @end menu
! 786:
! 787: @node Chinese remainder theorem and itor,,, Modular method
! 788: @section Chinese remainder theorem and itor
! 789:
! 790: @comment **********************************************************
! 791: @comment --- ◯◯◯◯ の説明
! 792: @comment --- 個々の関数の説明の開始 ---
! 793: @comment --- section 名を正確に ---
! 794: @node gtt_ekn3.chinese_itor,,,
! 795: @subsection @code{gtt_ekn3.chinese_itor}
! 796: @comment --- 索引用キーワード
! 797: @findex gtt_ekn3.chinese_itor Chinese remainder theorem and itor
! 798:
! 799: @table @t
! 800: @item gtt_ekn3.chinese_itor(@var{data},@var{idlist})
! 801: :: It performs a rational reconstruction by the Chinese remainder theorem (itor = integer to rational).
! 802: @end table
! 803:
! 804: @comment --- 引数の簡単な説明 --- 以下まだ書いてない.
! 805: @table @var
! 806: @item return
! 807: [val, n], the vector val is the value by the rational reconstruction. n = n1*n2*...
! 808: @item data
! 809: [[val1,n1],[val2,n2], ...], val1, val2 are values evaluated in mod n1, mod n2, ... respectively. The relations val mod n1 = val1, val mod n2 = val2,.. are satisfied.
! 810: @item idlist
! 811: The list of server id's for itor.
! 812: @end table
! 813:
! 814: @comment --- ここで関数の詳しい説明 ---
! 815: @comment --- @itemize〜@end itemize は箇条書き ---
! 816: @comment --- @bullet は黒点付き ---
! 817: @itemize @bullet
! 818: @item When it cannot find val, it returns failure.
! 819: @end itemize
! 820:
! 821: @comment --- @example〜@end example は実行例の表示 ---
! 822: Example: [3!, 5^3*3!]=[6,750] is the return value.
! 823: The relations 6 mod 109 =6, 750 mod 109=96 stand for [[6,96],109], ...
! 824: @example
! 825: gtt_ekn3.setup(|nps=2,nprm=3,minp=101,fgp="p_small.txt");
! 826: SS=gtt_ekn3.get_svalue();
! 827: SS[0];
! 828: [103,107,109] // list of primes
! 829: SS[1];
! 830: [0,2] // list of server ID's
! 831: gtt_ekn3.chinese_itor([[[ 6,96 ],109],[[ 6,29 ],103],[[ 6,1 ],107]],SS[1]);
! 832: [[ 6 750 ],1201289]
! 833:
! 834: // The argument may be a scalar.
! 835: gtt_ekn3.chinese_itor([[96,109],[29,103]],SS[1]);
! 836: [[ 750 ],11227]
! 837: @end example
! 838:
! 839:
! 840:
! 841:
! 842: @comment --- 参照(リンク)を書く ---
! 843: @table @t
! 844: @item Refer to
! 845: @ref{gtt_ekn3.setup}
! 846: @end table
! 847:
! 848:
! 849: @node Binary splitting,,, Top
! 850: @chapter Binary splitting
! 851:
! 852: @menu
! 853: * gtt_ekn3.init_dm_bsplit::
! 854: * gtt_ekn3.setup_dm_bsplit::
! 855: * gtt_ekn3.init_bsplit::
! 856: @end menu
! 857:
! 858: @node Matrix factorial,,, Binary splitting
! 859: @section Matrix factorial
! 860:
! 861: @comment **********************************************************
! 862: @comment --- ◯◯◯◯ の説明
! 863: @comment --- 個々の関数の説明の開始 ---
! 864: @comment --- section 名を正確に ---
! 865: @node gtt_ekn3.init_bsplit,,,
! 866: @node gtt_ekn3.init_dm_bsplit,,,
! 867: @node gtt_ekn3.setup_dm_bsplit,,,
! 868: @subsection @code{gtt_ekn3.init_bsplit, gtt_ekn3.init_dm_bsplit, gtt_ekn3.setup_dm_bsplit}
! 869: @comment --- 索引用キーワード
! 870: @findex gtt_ekn3.init_dm_bsplit matrix factorial
! 871: @findex gtt_ekn3.setup_dm_bsplit matrix factorial
! 872: @findex gtt_ekn3.init_bsplit matrix factorial
! 873:
! 874: @table @t
! 875: @item gtt_ekn3.init_bsplit(|minsize=16,levelmax=1);
! 876: :: It sets parameters for the binary splitting to evaluate the matrix factorial M(1) M(2) ... M(n) where M(k) is a matrix with a parameter k.
! 877: @item gtt_ekn3.init_dm_bsplit(|bsplit_x=0, bsplit_reduce=0)
! 878: :: It sets parameters for the binary splitting by a distributed computation.
! 879: @item gtt_ekn3.setup_dm_bsplit(C)
! 880: :: It starts C processes for the binary splitting.
! 881: @end table
! 882:
! 883: @comment --- 引数の簡単な説明 --- 以下まだ書いてない.
! 884: @table @var
! 885: @item Option minsize.
! 886: When the size of the matrix factorial is less than the minsize, the binary splitting is not used and sequential multiplication is used instead.
! 887: @item Option levelmax.
! 888: The maximum of recursions of the recursive binary splitting in the distributed computation. See gtt_ekn3/dm_bsplit.rr
! 889: C should be set to levelmax-1. When levalmax=1, the distributed computation is not performed.
! 890: @item Option bsplit_x.
! 891: When bsplit_x=1, a window attached to every process is opened.
! 892: @end table
! 893:
! 894:
! 895: @comment --- @example〜@end example は実行例の表示 ---
! 896: Example: A comparison of bs=1 and no bs.
! 897: @example
! 898: [4618] cputime(1)$
! 899: [4619] gtt_ekn3.expectation(Marginal=[[1950,2550,5295],[1350,1785,6660]],
! 900: P=[[17/100,1,10],[7/50,1,33/10],[1,1,1]]|bs=1)$
! 901: 4.912sec(4.914sec)
! 902: [4621] V2=gtt_ekn3.expectation(Marginal,P)$
! 903: 6.752sec(6.756sec)
! 904: @end example
! 905:
! 906:
! 907: @comment --- @example〜@end example は実行例の表示 ---
! 908: Example:
! 909: Note that distributed computations are often slower than computations on a single process
! 910: in our implementation of the binary splitting.
! 911: The option bsplit_x=1 opens
! 912: a debug windows, it makes things slower.
! 913: The function gtt_ekn3.test_bs_dist() is a test function of the binary splitting by a distributed computation.
! 914: @example
! 915: [3669] C=4$ gtt_ekn3.init_bsplit(|minsize=16,levelmax=C+1)$
! 916: gtt_ekn3.init_dm_bsplit(|bsplit_x=1)$
! 917: [3670] [3671] [3672] gtt_ekn3.setup_dm_bsplit(C);
! 918: [0,0]
! 919: [3673] gtt_ekn3.assert2(10|bs=1)$
! 920: @end example
! 921:
! 922: @comment --- 参照(リンク)を書く ---
! 923: @table @t
! 924: @item Refer to
! 925: @ref{gtt_ekn3.gmvector}
! 926: @ref{gtt_ekn3.expectation}
! 927: @ref{gtt_ekn3.assert1}
! 928: @ref{gtt_ekn3.assert2}
! 929: @end table
! 930:
! 931:
! 932: @comment --- おまじない ---
1.1 takayama 933: @node Index,,, Top
934: @unnumbered Index
935: @printindex fn
936: @printindex cp
937: @iftex
938: @vfill @eject
939: @end iftex
940: @summarycontents
941: @contents
1.2 ! takayama 942: @bye
! 943: @comment --- おまじない終り ---
1.1 takayama 944:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to gtt_ekn-en.texi CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM / src / asir-contrib / packages / doc / gtt_ekn