{"id":20669476,"url":"https://github.com/iitis/cumulants.jl","last_synced_at":"2025-03-10T16:35:40.044Z","repository":{"id":52260675,"uuid":"78840100","full_name":"iitis/Cumulants.jl","owner":"iitis","description":"Multivariate cumulants of any order","archived":false,"fork":false,"pushed_at":"2023-05-17T08:24:29.000Z","size":249,"stargazers_count":14,"open_issues_count":1,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-02-20T21:41:19.566Z","etag":null,"topics":["cumulants","tensor"],"latest_commit_sha":null,"homepage":"","language":"Julia","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iitis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-01-13T10:35:41.000Z","updated_at":"2024-10-31T19:30:22.000Z","dependencies_parsed_at":"2025-01-17T13:30:17.402Z","dependency_job_id":"c6217c02-1c1d-4461-aeac-42098c76b73b","html_url":"https://github.com/iitis/Cumulants.jl","commit_stats":{"total_commits":205,"total_committers":12,"mean_commits":"17.083333333333332","dds":0.3268292682926829,"last_synced_commit":"8eacfac99240f804a79e2bd7057324a407115977"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iitis%2FCumulants.jl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iitis%2FCumulants.jl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iitis%2FCumulants.jl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iitis%2FCumulants.jl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iitis","download_url":"https://codeload.github.com/iitis/Cumulants.jl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242884481,"owners_count":20201125,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cumulants","tensor"],"created_at":"2024-11-16T20:14:29.529Z","updated_at":"2025-03-10T16:35:40.005Z","avatar_url":"https://github.com/iitis.png","language":"Julia","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cumulants.jl\n[![Coverage Status](https://coveralls.io/repos/github/iitis/Cumulants.jl/badge.svg?branch=master)](https://coveralls.io/github/iitis/Cumulants.jl?branch=master)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7034176.svg)](https://doi.org/10.5281/zenodo.7034176)\n\n\nCalculates cumulant tensors of any order for multivariate data.\nFunctions return tensor or array of tensors in `SymmetricTensors` type. Requires [SymmetricTensors.jl](https://github.com/ZKSI/SymmetricTensors.jl). To convert to array, run:\n\n```julia\njulia\u003e Array(data::SymmetricTensors{T, N})\n```\n\nAs of 01/01/2017 [kdomino](https://github.com/kdomino) is the lead maintainer of this package.\n\n## Installation\n\nWithin Julia, run\n\n```julia\npkg\u003e add Cumulants\n```\n\nto install the files. Julia 1.0 or later is required.\n\n\n## Functions\n### Moment\n\n```julia\njulia\u003e moment(data::Matrix{T}, m::Int, b::Int = 2) where T\u003c: AbstractFloat\n```\n\nReturns a `SymmetricTensor{T, m}` of the moment of order `m` of multivariate data represented by a `t` by `n` matrix, i.e. data with `n` marginal variables and `t` realisations. The argument `b` with defalt value `2`, is an optional `Int` that determines the size\nof the blocks in `SymmetricTensors` type.\n\n```julia\njulia\u003e data = reshape(collect(1.:15.),(5,3))\n5×3 Array{Float64,2}:\n 1.0   6.0  11.0\n 2.0   7.0  12.0\n 3.0   8.0  13.0\n 4.0   9.0  14.0\n 5.0  10.0  15.0\n```\n\n```julia\njulia\u003e m = moment(data, 3)\nSymmetricTensor{Float64,3}(Union{Nothing, Array{Float64,3}}[[45.0 100.0; 100.0 230.0]\n\n[100.0 230.0; 230.0 560.0] nothing; nothing nothing]\n\nUnion{Nothing, Array{Float64,3}}[[155.0 360.0; 360.0 890.0] [565.0; 1420.0]; nothing [2275.0]], 2, 2, 3, false)\n```\nTo convert to array use:\n\n```julia\njulia\u003e Array(m)\n3×3×3 Array{Float64,3}:\n[:, :, 1] =\n  45.0  100.0  155.0\n 100.0  230.0  360.0\n 155.0  360.0  565.0\n\n[:, :, 2] =\n 100.0  230.0   360.0\n 230.0  560.0   890.0\n 360.0  890.0  1420.0\n\n[:, :, 3] =\n 155.0   360.0   565.0\n 360.0   890.0  1420.0\n 565.0  1420.0  2275.0\n ```\n\n ### Cumulants\n\n ```julia\njulia\u003e cumulants(data::Matrix{T}, m::Int = 4, b::Int = 2) where T\u003c: AbstractFloat\n```\n\nReturns a vector of `SymmetricTensor{T, i}` `i = 1,2,3,...,m` of cumulants of\norder `1,2,3,...,m`. Cumulants are calculated for multivariate data represented\nby matrix of size `t` by `n`, i.e. data with `n` marginal variables and `t`\nrealisations.\n\n\n```julia\njulia\u003e c = cumulants(data, 3);\n\njulia\u003e c[2]\nSymmetricTensor{Float64,2}(Union{Nothing, Array{Float64,2}}[[2.0 2.0; 2.0 2.0] [2.0; 2.0]; nothing [2.0]], 2, 2, 3, false)\n\njulia\u003e c[3]\nSymmetricTensor{Float64,3}(Union{Nothing, Array{Float64,3}}[[0.0 0.0; 0.0 0.0]\n\n[0.0 0.0; 0.0 0.0] nothing; nothing nothing]\n\nUnion{Nothing, Array{Float64,3}}[[0.0 0.0; 0.0 0.0] [0.0; 0.0]; nothing [0.0]], 2, 2, 3, false)\n\n```\nTo convert to array:\n\n```julia\njulia\u003e Array(c[2])\n3×3 Array{Float64,2}:\n 2.0  2.0  2.0\n 2.0  2.0  2.0\n 2.0  2.0  2.0\n\n julia\u003e Array(c[3])\n3×3×3 Array{Float64,3}:\n[:, :, 1] =\n 0.0  0.0  0.0\n 0.0  0.0  0.0\n 0.0  0.0  0.0\n\n[:, :, 2] =\n 0.0  0.0  0.0\n 0.0  0.0  0.0\n 0.0  0.0  0.0\n\n[:, :, 3] =\n 0.0  0.0  0.0\n 0.0  0.0  0.0\n 0.0  0.0  0.0\n```\n\n#### Block size\n\nThe argument `b` with default value `2`, is an optional `Int`\nthat determines a size of blocks in `SymmetricTensors` type. This block size `b` is the parameter that affect\nthe algorithm performance, for most cases the performance is optimal for `b = 2, 3`. The block size must \nfulfil `0 \u003c b ≦ size(data, 2)` otherwise error will be raised. For the performance analysis for various bolck sizes see `Section 5.2.1` in \nKrzysztof Domino, Piotr Gawron, Łukasz Pawela, *Efficient Computation of Higher-Order Cumulant Tensors*, SIAM J. Sci. Comput. 40, A1590 (2018) [![DOI](10.1137/17M1149365)](https://doi.org/10.1137/17M1149365), https://arxiv.org/abs/1701.05420. For benchmarking one can also use `benchmarks/comptimeblocks.jl`\n\nThe purpose of this package is to compute moments and cumulants for multivariate data. It works for univariate data `X` structured in the form of matrix with `size(X, 2) = 1` if taking `b=1`. Such univariate application is not efficient however.\n\n```julia\njulia\u003e X = [1., 2., 3., 4.];\n\njulia\u003e X = reshape(X, (4,1));\n\njulia\u003e c = cumulants(X,4,1);\n\njulia\u003e map(x -\u003e Array(x)[1], c)\n4-element Array{Float64,1}:\n  2.5\n  1.25\n  0.0\n -2.125\n```\nWe do not suply exact univariate fisher's k-statistics.\n\n\n#### Parallel computation\n\nParallel computation is efficient for large number of data realisations, e.g. `t = 1000000`. For parallel computation just run\n```julia\njulia\u003e addprocs(n)\njulia\u003e @everywhere using Cumulants\n```\n\nNaive algorithms of moment and cumulant tensors calculations are also available.\n\n ```julia\njulia\u003e naivemoment(data::Matrix{T}, m::Int = 4) where T\u003c: AbstractFloat\n```\nReturns array{T, m} of the m'th moment of data. calculated using a naive algorithm.\n\n\n```julia\njulia\u003e naivemoment(data, 3)\n3×3×3 Array{Float64,3}:\n[:, :, 1] =\n  45.0  100.0  155.0\n 100.0  230.0  360.0\n 155.0  360.0  565.0\n\n[:, :, 2] =\n 100.0  230.0   360.0\n 230.0  560.0   890.0\n 360.0  890.0  1420.0\n\n[:, :, 3] =\n 155.0   360.0   565.0\n 360.0   890.0  1420.0\n 565.0  1420.0  2275.0\n```\n\n ```julia\njulia\u003e naivecumulant(data::Matrix{T}, m::Int = 4) where T\u003c: AbstractFloat\n```\nReturns `Array{T, m}` of the `m`'th cumulant of data, calculated using a naive algorithm. Works for `1 \u003c= m  \u003c 7`, for `m \u003e= 7` throws exception.\n\n\n```julia\njulia\u003e naivecumulant(data, 2)\n3×3 Array{Float64,2}:\n 2.0  2.0  2.0\n 2.0  2.0  2.0\n 2.0  2.0  2.0\n```\n\n\n```julia\njulia\u003e naivecumulant(data, 3)\n3×3×3 Array{Float64,3}:\n[:, :, 1] =\n 0.0  0.0  0.0\n 0.0  0.0  0.0\n 0.0  0.0  0.0\n\n[:, :, 2] =\n 0.0  0.0  0.0\n 0.0  0.0  0.0\n 0.0  0.0  0.0\n\n[:, :, 3] =\n 0.0  0.0  0.0\n 0.0  0.0  0.0\n 0.0  0.0  0.0\n```\n\n# Performance analysis, folder `benchmarks`\n\nTo analyse the computational time of cumulants vs naivecumulants and moment vs naivemoment, we supply the executable script `comptimes.jl`.\nThis script returns to a .jld file computational times, given following parameters:\n* `-m (Int)`: cumulant's order, by default `m = 4`,\n* `-n (vararg Int)`: numbers of marginal variables, by default `m = 20 24 28`,\n* `-t (vararg Int)`: number of realisations of random variable, by defalut `t = 10000`.\nBe careful while using `n`\u003e`4` and large `m`, where naive algorithms might need a large computational time and memory usage. Naive algorithms does not use the block structures, hence they computes and stores a whole cumulant tensor regardless its symmetry. All comparisons performed by this script use one core.\n\nTo analyse the computational time of cumulants for different block sizes `1 =\u003c b =\u003c Int(sqrt(n))`, we supply the executable script `comptimeblocks.jl`.\nThis script returns to a .jld file computational times, given following parameters:\n* `-m (Int)`: cumulant's order, by default `m = 4`,\n* `-n (Int)`: numbers of marginal variables, by default `m = 48`,\n* `-t (vararg Int)`: number of realisations of random variable, by default `t = 10000 20000`.\nComputational times and parameters are saved in the .jld file in /res directory. All comparisons performed by this script use one core.\n\nTo analyse the computational time of moment on different numbers of processes, we supply the executable script `comptimeprocs.jl`.\nThis script returns to a .jld file computational times, given following parameters:\n* `-m (Int)`: moment's order, by default `m = 4`,\n* `-n (Int)`: numbers of marginal variables, by default `m = 50`,\n* `-t (Int)`: number of realisations of random variable, by default `t = 100000`,\n* `-p (Int)`: maximal number of processes, by default `p = 4`,\n* `-b (Int)`: blocks size, by default `b = 2`.\n\nAll result files are saved in /res directory. To plot a graph run /res/plotcomptimes.jl followed by a `*.jld` file name\n\nFor the computational example on data use the following.\n\nThe script `gandata.jl` generates `t = 150000000` realisations of `n = 4` dimensional data form the `t`-multivariate distribution with `ν = 14` degrees of freedom, and theoretical\nsuper-diagonal elements of those cumulants. Results are saved in `data/datafortests.jld`\n\nThe script `testondata.jl` computes cumulant tensors of order `m = 1 - 6` for `data/datafortests.jld`, results are saved in `data/cumulants.jld`.\n\nTo read `cumulants.jld` please run\n\n```julia\njulia\u003e using JLD\n\njulia\u003e using SymmetricTensors\n\njulia\u003e load(\"cumulants.jld\")\n\n```\n\nTo plot super-diagonal elements of those cumulants and their theoretical values from t-student distribution pleas run `plotsuperdiag.jl`\n\n\n# Citing this work\n\n\nKrzysztof Domino, Piotr Gawron, Łukasz Pawela, *Efficient Computation of Higher-Order Cumulant Tensors*, SIAM J. Sci. Comput. 40, A1590 (2018) [![DOI](10.1137/17M1149365)](https://doi.org/10.1137/17M1149365), https://arxiv.org/abs/1701.05420\n\nThis project was partially financed by the National Science Centre, Poland – project number 2014/15/B/ST6/05204.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiitis%2Fcumulants.jl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiitis%2Fcumulants.jl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiitis%2Fcumulants.jl/lists"}