{"id":34861815,"url":"https://github.com/simulation-decomposition/simdec-matlab","last_synced_at":"2025-12-25T21:17:52.601Z","repository":{"id":157284322,"uuid":"631314390","full_name":"Simulation-Decomposition/simdec-matlab","owner":"Simulation-Decomposition","description":"Sensitivity analysis using simulation decomposition","archived":false,"fork":false,"pushed_at":"2025-05-16T08:05:09.000Z","size":5486,"stargazers_count":4,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-05-16T08:42:05.351Z","etag":null,"topics":["computational-modeling","sensitivity-analysis","uncertainty","visualization"],"latest_commit_sha":null,"homepage":"https://www.simdec.fi/","language":"MATLAB","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Simulation-Decomposition.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2023-04-22T16:18:19.000Z","updated_at":"2025-05-16T08:05:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"697636cb-467a-45d0-b9db-ef8487178dcd","html_url":"https://github.com/Simulation-Decomposition/simdec-matlab","commit_stats":{"total_commits":30,"total_committers":2,"mean_commits":15.0,"dds":0.4,"last_synced_commit":"308ef58c500a36df026f0943a3fde1861b35d3c1"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Simulation-Decomposition/simdec-matlab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Simulation-Decomposition%2Fsimdec-matlab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Simulation-Decomposition%2Fsimdec-matlab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Simulation-Decomposition%2Fsimdec-matlab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Simulation-Decomposition%2Fsimdec-matlab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Simulation-Decomposition","download_url":"https://codeload.github.com/Simulation-Decomposition/simdec-matlab/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Simulation-Decomposition%2Fsimdec-matlab/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28038032,"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","status":"online","status_checked_at":"2025-12-25T02:00:05.988Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["computational-modeling","sensitivity-analysis","uncertainty","visualization"],"created_at":"2025-12-25T21:17:52.059Z","updated_at":"2025-12-25T21:17:52.595Z","avatar_url":"https://github.com/Simulation-Decomposition.png","language":"MATLAB","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e **Warning**\n\u003e This library is under active development and things can change at anytime! Suggestions and help are greatly appreciated.\n\n![image](https://user-images.githubusercontent.com/37065157/233836694-5312496e-4ada-47cb-bc09-3bf8c00be135.png)\n\n**Simulation decomposition** or **SimDec** is an uncertainty and sensitivity analysis method, which is based on Monte Carlo simulation. \nSimDec consists of two major parts (and two corresponding funciton):\n1. Computing sensitivity indices, \n2. Visualizing the effects by creating multi-variable scenarios, mapping the output values to them, and color-coding the corresponding segments of the output distribution. \n\nSimDec reveals the nature of causalities and interaction effects in the model.  \n\n\n\n## Starting to work\nSimply download the matlab [functions](functions) and add them to your path when working with matlab. \n\nUse [sensitivity_indices.m](sensitivity_indices.m) for computing the indices and [simdec_visualization.m](simdec_visualization.m) for building the graphics.\n\n## Documentation\n\n### function [SI, FOE, SOE]  = [sensitivity_indices](sensitivity_indices.m) (output, inputs)\n\ncalculates how much variability of the output is explained by inputs. \n\nINPUTS\n- **output** - target variable (Y), size [N_runs, 1].\n- **inputs** - input variables (Xs), size [N_runs, N_factors].\n\nOUTPUTS\n- **FOE** - first-order effects (also called 'main' or 'individual'), size [N_factors, 1].\n- **SOE** - second-order effects (also called 'interaction'), size [N_factors, N_factors].\n- **SI**  - sensitivity indices, combined first- and second-order effect of each input, size [N_factors, 1].  \n\n### function [scenarios, scen_legend, boundaries_out] = [simdec_visualization](simdec_visualization.m) (output, inputs, SI, varargin)\n\nbuilds SimDec visualization using data decomposition.\n\nREQUIRED INPUTS\n\n- **output** - target variable (Y), size [N_runs, 1].\n- **inputs** - input variables (Xs), size [N_runs, N_factors].\n- **SI** - sensitivity indices.\n\nOPTIONAL ARGUMENTS\n\n- **DecompositionLimit** - threshold of cumulative importance (sum(SI)) for selection of input variables for decomposition. Default value 0.8*sum(SI). \n- **OrderOfVariables** - for custom decomposition specify the order of variables for decomposition, use zero to exclude. For example, if 4 input variables, third and second are desired for decomposition, then specify OrderOfVariables as [0 2 1 0]. Default value [].\n- **NumberOfStates** - the number of states for each input variable, i.e. [0 3 2 0]. Default value [].\n- **BoundaryType** - defines how the numerical boundaries between the states of inputs are defined:\n  - 'precentile-based' for same amount of observations in each state (default value),   \n  -  'interval-based' for equaly-spaced ranges of states.\n- **StateBoundaries** - maximums (numeric boundaries) of every state, leave the rest as NaN, e.g. [NaN   3  -1    NaN;    NaN   5   0    NaN;    NaN   7   NaN  NaN]. Default value [].\n- **XLim** - Minimum and maximum values for x-axis of the histogram or boxplot [xmin xmax]. \n- **YLim** - Minimum and maximum values for y-axis of the histogram in % values [ymin ymax].  \n - **OutputName** - name of the output variable. Default value 'Y'.\n - **InputNames** - names of the input variables in the order of their appearance in the original dataset. Default value {X1, X2, X3...}.\n - **MainColors** -  a cell array with HEX numbers of the main colors for decomposition (should correspond to the number of states of the first for decomposition input variable). \n - **GraphType** - 'stacked_histogram' as a default option and 'boxplot' as an alternative.\n - **NumberOfBins** - number of bins for the SimDec histogram.\n  - **Output2** - a second output variable, which will be displayed with a scatterhit and decomposition created for the main output variable.\n  - **Output2Name** - name for the second output variable, default 'Y2'.\n  - **ScatterFraction** - the portion of data / points displayed on the scatterplot. The default value is 1 - the entire dataset is displayed. A value of e.g. 0.5 will show every second point.\n  - **XLim2** - Minimum and maximum values for x-axis of the second rotated histogram [xmin xmax]. This scales the scatteplot (ylim) accordingly.\n  - **YLim2** - Minimum and maximum values for y-axis of the second rotated histogram in % values [ymin ymax].  \n\n\n OUTPUTS\n- **scenarios** - an array of the same size as Y with scenario indices for every simulation run.\n- **scen_legend** - a scenario table that shows which states of which variables compose different sceanrios.\n- **boundaries_out** - numeric boundaries of states of input variables.\n\n\n## Example\nThe following procedure is saved in the [main.m](main.m) and uses [example_data.xlsx](example_data.xlsx).\n\n### 1. Load data \nFirst the simulated `inputs` and the `output` need to be specified. They can result from a Monte Carlo simulation arranged directly in matlab, or conducted elsewhere and then loaded through a file, like in this example. \n\n```matlab   \n    Matrix = xlsread (\"example_data.xlsx\");\n    \n    output = Matrix(:,1);\n    inputs = Matrix(:,2:end);         \n```\n\n\n### 2. Compute sensitivity indices\nFunction [sensitivity_indices.m](sensitivity_indices.m) computes first-order effects `FOE` (main individual effect of every input variable), second-order effects `SOE` (interaction effects between pairs of variables) and combined sensitivity indices `SI`. \n\n```matlab\n    [SI, FOE, SOE]  = sensitivity_indices (output, inputs)\n    sum(SI) % shows what portion of the variance of the output is explained \n            % by the combined first- and second-order effects of the inputs\n```\nHere is the result it returns:\n\nSI =\n\n    0.0409\n    0.5155\n    0.0955\n    0.3506\n\nFOE =\n\n    0.0367\n    0.4910\n    0.1069\n    0.2777\n\nSOE =\n\n         0    0.0034    0.0015    0.0035\n         0         0   -0.0605    0.1059\n         0         0         0    0.0363\n         0         0         0         0\n\nsum(SI) = \n\n    1.0024\n\nEach value shows what portion of the variance of the output is explained (negative SOE values indicate correlation). In this example, SI shows that the most important inputs are X2 (52%) and X4 (35%). SOE points out that there is interaction between X2 and X3 (11%) and correlation between X2 and X3 (-6%). In total, 100% of the output variance is explained (a few percentage points can be attributed to noise).\n\n\n### 3. Visualize\nFunction [simdec_visualization.m](simdec_visualization.m) \n1. chooses the most important input variables, \n2. breaks them down into states, \n3. forms scenarios out of all combinations of those states, \n4. maps the scenarios onto the output values, and \n5. visualizes these scenarios by color-coding the distribution of the output.\n\n```matlab\n[scenarios, scen_legend, boundaries] = simdec_visualization (output, inputs, SI);\n```\n\n\nThe SimDec graph and the corresponding legend is generated automatically when running this function. \n\n![image](https://github.com/Simulation-Decomposition/simdec-matlab/assets/37065157/2304f44a-05b1-4c9d-88c8-d4862ca54258)\n\n\n**That's it, your SimDec analysis is completed!**\n\nBut you can customize it furhter.\n\nAnd feel free to go an extra step in your reporting, - name the states (i.e., *low*, *medium*, *high*) and merge the cells of the legend with the same state. The help to make those automatic in would be greatly approeciated! \n\n\n\n### 4. Customize\n\nThe [simdec_visualization.m](simdec_visualization.m) function has numerious optional arguments that can be used to polish the outlook of the results, tune and play with the decomposition set-up.\n\n#### 4.1. Boxplot\nAdd `'GraphType','boxplot'` to the function's input to display the results in the form of boxplot instead of stacked histogram. \n\n```matlab\n    [scenarios, scen_legend, boundaries] = simdec_visualization (output, inputs, SI,'GraphType','boxplot'); \n```\n![image](https://github.com/Simulation-Decomposition/simdec-matlab/assets/37065157/5bc2fae6-5cbf-4a1d-8fb4-d669b7e80703)\n\nThe boxplot visualization presents exactly the same decomposition and contains the same scenarios, color-coded in the same way as in the stacked histogram.\n\nThe boxplots are handy when some scenarios have little data and are poorly visible on the histogram. \n\n#### 4.2. Polishing: colors, names of variables\n\nUse `'OutputName'`, `'InputNames'` to add names of the variables. \nSpecify `'MainColors'` as a cell array of HEX codes of the desired main colors (the shades for subdivisions are produced automatically from the main colors). \n\n```matlab\n    output_name = 'Output';\n    input_names = {'Input1','Input2','Input3','Input4'};\n    colors = {'#3F45D0','#DC267F','26DCD1'}; % HEX codes for the main colors\n    \n    [scenarios, scen_legend, boundaries] = simdec_visualization (output, inputs,...\n        SI,'OutputName',output_name,'InputNames',input_names,'MainColors',colors);\n```\n\n![image](https://github.com/Simulation-Decomposition/simdec-matlab/assets/37065157/0d9be2e4-7f8f-462d-a3cc-2e34a19f0ea4)\n\n\n\n#### 4.3. Tuning decomposition: more variables, different state formation\n\nDeafult number of variables for decomposition is defined beased on the threshold `0.8*sum(SI)`. The threshold can be changed by using `'DecompositionLimit'` argument.\n\nThe `'BoundaryType'` argument defines how the numeric range of input variables is broken down into states. The deafult value `'percentile-based'` forms the states ensuring the same amount of observations in each state. The alternative `'interval-based'` approach divides input ranges into equaly-spaced intervals. Changing this argument would not make any difference for independent uniformly distributed inputs.\n\n\n```matlab\n    dec_limit = 0.9; % minimum overall importance [sum(SI)] of chosen for decomposition input variables\n    boundary_type = 'interval-based'; \n                                   \n    [scenarios, scen_legend, boundaries] = simdec_visualization (output, inputs,...\n        SI,'DecompositionLimit',dec_limit,'BoundaryType',boundary_type);\n```\n\n![image](https://github.com/Simulation-Decomposition/simdec-matlab/assets/37065157/305b660f-df12-4a78-bc34-aa61d004d760)\n\n\n\n#### 4.4. Tuning decomposition: more variables, different state formation\nThe decomposition can be further fully customized by altering the amount and the order of inputs for decomposition (`'OrderOfVariables'`), defining custom amount of states (`'NumberOfStates'`) and their boundaries (`'StateBoundaries'`). \n\n```matlab\n    manual_vars = [0 2 1 0]; % specify the order of variables for decomposition, \n        % use 0 to exclude, size (1, N_inputs). In this example we set that the third\n        % input variable is used first, and then the second one.  \n    manual_states = [0 3 2 0]; % specify the number of states for each variable, \n        % size (1, N_inputs), the position corresponds to the original order of inputs.\n        % Three states for the second input variable and two states for the third. \n    manual_boundaries =  [ NaN    min(inputs(:,2))     min(inputs(:,3))    NaN\n                           NaN         100                  657.5          NaN\n                           NaN         650             max(inputs(:,3))    NaN      \n                           NaN    max(inputs(:,2))          NaN            NaN]; \n        % specify numeric boundaries for every state, size(max(manual_states)+1, N_inputs).\n\n\n    [scenarios, scen_legend, boundaries] = simdec_visualization (output, inputs,...\n        SI,'OrderOfVariables',manual_vars,'NumberOfStates',manual_states,'StateBoundaries',manual_boundaries);\n```\n\n![image](https://github.com/Simulation-Decomposition/simdec-matlab/assets/37065157/ea3b79e1-c969-467d-a817-b23c55a01402)\n\nThe optional attributes can be used in any combination. \n\n\n### 5. Two-output scatterhist\nIf relationship between two output variables is in quesiton, the `simdec_visualization function` can build a scatterplot with two correponding histograms on the top and right side, all decomposed and colored by the logic created for the main output variable. \n\nTo create the scatterhist one needs to specify the second output variable for the argument `'Output2'`, additional optional arguments include `'Output2Name'` and `'ScatterFraction'`, which defines how many dots are shown on the scatterplot (1 - all, 0.5 - every second). Other considered above optional arguments work with scatterhist as well. \n\n\n```matlab   \nMatrix = xlsread (\"example_data2.xlsx\");\n    \n    output = Matrix(:,1);\n    output2 = Matrix(:,2);\n    inputs = Matrix(:,3:end); \n    \n    [SI, FOE, SOE]  = sensitivity_indices (output, inputs) \n    \n    outputname = 'Output1';\n    output2name = 'Output2';\n\n    share_of_data_shown = 0.005;\n    n_bins = 40;\n\n    [scenarios, scen_legend, boundaries] = simdec_visualization (output, inputs, SI,'OutputName',outputname...\n    ,'Output2',output2,'Output2Name',output2name,'ScatterFraction',share_of_data_shown,'NumberOfBins',n_bins);\n         \n```\n![alt text](image-1.png)\n\n#### 5.1. Playing with axis limits\nYou can change x- and y-axes limits for both histograms, the scatterplot scales accordingly. If only the axes of one histogram are changed, the scatterplot and the second histogram scale accordingly. \n\n```matlab \n    xlim_values = [1000 3000]; % affects x-axis of the top histogram and x-axis of the scatterplot.\n    ylim_values = [0 4]; % value in % for Probability y-axis of top histogram, does not affect the scatterplot.\n    [scenarios, scen_legend, boundaries] = simdec_visualization (output, inputs, SI,'OutputName',outputname...\n        ,'Output2',output2,'Output2Name',output2name,'ScatterFraction',share_of_data_shown,'NumberOfBins',n_bins...\n        ,'XLim',xlim_values,'YLim',ylim_values);\n```\n(The graph demonstrates that not only Output1 axis has been changed as specified in the code above (scatterplot x-axis), but the second histogram has been automatically truncated as well (x-axis of the rotated right histogram and the corresponding y-axis of the scatterplot) to avoid empty space in the scatterplot.)\n![alt text](image.png)\n\nIf the full control over the both axes of the scatterplot is needed, both `'XLim'` and `'XLim2'` should be specified.\n\n```matlab \n    xlim_values = [1000 3000]; % affects x-axis of the top histogram and x-axis of the scatterplot.\n    xlim_values_2 = [0 1000]; % affects (rotated) x-axis of the right histogram and y-axis of the scatterplot.\n    [scenarios, scen_legend, boundaries] = simdec_visualization (output, inputs, SI,'OutputName',outputname...\n        ,'Output2',output2,'Output2Name',output2name,'ScatterFraction',share_of_data_shown,'NumberOfBins',n_bins...\n        ,'XLim',xlim_values,'XLim2',xlim_values_2);\n```\n![alt text](image-2.png)\n\n\n## Links\n- See [how to read SimDec on wikipedia](https://en.wikipedia.org/wiki/SimDec)\n- Meet [people behind SimDec](https://www.simdec.fi/team)\n- Stay in touch via our [Sensitivity Analysis discord community](https://discord.gg/54SFcNsZS4)\n\n\n## Citations\n\nThe algorithms and visualizations used in this package came primarily out of research at **LUT University**, Lappeenranta, Finland, and **Stanford University**, California, U.S., supported with grants from ***Business Finland***, ***Wihuri Foundation***, ***Foundation for Economic Education***, and ***Natural Sciences and\nEngineering Research Council***. If you use SimDec in your research we would appreciate a citation to the following publications:\n\n- Kozlova, M., Moss, R. J., Yeomans, J. S., \u0026 Caers, J. (2024). Uncovering Heterogeneous Effects in Computational Models for Sustainable Decision-making. _Environmental Modelling \u0026 Software_, 171, 105898. [Available here](https://doi.org/10.1016/j.envsoft.2023.105898)\n- Kozlova, M., Moss, R. J., Roy, P., Alam, A., \u0026 Yeomans, J. S. (2024). SimDec algorithm and guidelines for its usage and interpretation. In M. Kozlova \u0026 J. S. Yeomans (Eds.), _Sensitivity Analysis for Business, Technology, and Policymaking. Made Easy with Simulation Decomposition_. Routledge.  [Available here](https://github.com/Simulation-Decomposition/SimDec-book/blob/74ce72c1d3dda650eba1c59e3b215a4bb35c6be0/chapters/02_SimDec_algorithm_and_instructions/Ch2.pdf).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimulation-decomposition%2Fsimdec-matlab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimulation-decomposition%2Fsimdec-matlab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimulation-decomposition%2Fsimdec-matlab/lists"}