 
**forgeffects** is a Python package designed for the analysis and computation of forgotten effects and direct effects. It leverages tensor-based computations, aggregating data from multiple key informants to process chained bipartite or complete graphs using 3D tensors.
## Installation
Install the package from PyPI:
```
pip install forgeffects
```
## Included Datasets
The **forgeffects** package includes three 3D incidence matrices: `CC`, `CE`, and `EE`, used in the study *Application of Forgotten Effects Theory to Evaluate Public Policy on Air Pollution in the Municipality of Valdivia, Chile*.
The data corresponds to sixteen incentives, four behaviors, and ten key informants. These matrices can be loaded using the `load_test_data()` function, which accesses `.npy` files stored in the package.
Example:
```
import forgeffects as fe
CC = fe.load_test_data("CC.npy")
CE = fe.load_test_data("CE.npy")
EE = fe.load_test_data("EE.npy")
```
# Usage
## Graph Types
- **Complete Graphs**: To perform calculations with complete graphs, you only need to provide either the `CC` matrix (cause-cause relationships) or the `EE` matrix (effect-effect relationships). The `CE` matrix is not required for this type of graph.
- **Chained Bipartite Graphs**: To perform calculations with chained bipartite graphs, all three matrices (`CC`, `CE`, and `EE`) must be provided. These matrices represent cause-cause, cause-effect, and effect-effect relationships, respectively, and are necessary to construct the bipartite graph structure.
## Forgotten Effects
The `FE()` function identifies indirect paths between causes and effects, enabling the discovery of forgotten effects. It uses iterative max-min convolutions to analyze these paths, filtering results based on a specified significance threshold and exploring up to a defined maximum order of forgotten effects.
#### Parameters:
- `CC`: A 3D incidence matrix for cause-cause relationships. This matrix must be in Numpy format with the shape (key informants, rows, columns).
- `CE`: A 3D incidence matrix for cause-effect relationships. This matrix must be in Numpy format with the shape (key informants, rows, columns).
- `EE`: A 3D incidence matrix for effect-effect relationships. This matrix must be in Numpy format with the shape (key informants, rows, columns).
- `causes`: (optional) A list or tuple of strings representing custom names for the causes. If not specified, the causes will be automatically named using the notation $a_1, a_2, \dots, a_n$, where $n$ is the number of evaluated causes.
- `effects`: (optional) A list or tuple of strings representing custom names for the effects. If not specified, the effects will be automatically named using the notation $b_1, b_2, \dots, b_m$, where $m$ is the number of evaluated effects.
- `THR` (float): Defines the degree of truth in which incidence is considered significant within the range [0,1] (default $0.5$).
- `maxorder` (int): Maximum order of forgotten effects to compute (default $2$).
- `reps` (int): Number of replicas for empirical resampling (default $1000$).
#### Returns:
A list of DataFrames, each corresponding to an evaluated order of forgotten effects, with the following columns:
- `From`: Origin node of the indirect relationship.
- `Through_x`: Intermediary nodes (dynamic based on the evaluated order).
- `To`: Destination node of the indirect relationship.
- `Count`: Number of times a forgotten effect is repeated across different experts.
- `Mean`: Mean of the forgotten effects identified.
- `SD`: Standard deviation.
### Example (Chained bipartite graph)
```
import forgeffects as fe
# Compute forgotten effects
fe_results = fe.FE(CC, CE, EE, rep=10000, THR=0.5, maxorder=3)
# Display the results for the second-order forgotten effects
print(fe_results[0])
# Note: If additional orders are found, the results for third-order effects can be accessed using fe_results[1],
# for fourth-order effects using fe_results[2], and so on.
```
### Results
The example demonstrates the second-order forgotten effects identified by the function
| From | Through1 | To | Count | Mean | SD |
|:----:|:--------:|:---:|:-----:|:--------:|:--------:|
| a10 | a11 | a14 | 2134 | 0.660128 | 0.088254 |
| a13 | a16 | a1 | 2038 | 0.638836 | 0.080122 |
| a3 | a6 | a9 | 1910 | 0.642309 | 0.081263 |
| a8 | a13 | a10 | 1905 | 0.713915 | 0.100976 |
| a13 | a6 | a9 | 1698 | 0.662080 | 0.083397 |
| ... | ... | ... | ... | ... | ... |
| a9 | a3 | a10 | 1 | 0.531971 | 0.000000 |
| a5 | b2 | b4 | 1 | 0.513954 | 0.000000 |
| a5 | a14 | a9 | 1 | 0.541666 | 0.000000 |
| a2 | a16 | a5 | 1 | 0.582708 | 0.000000 |
| a3 | a10 | b4 | 1 | 0.517474 | 0.000000 |
<p><b>[3725 rows x 6 columns]</b></p>
## Direct Effects
The `directEffects()` function calculates direct effects by estimating mean incidences, confidence intervals, and p-values. It uses a one-sided t-test with bootstrapping to evaluate the significance of direct relationships.
#### Parameters:
- `CC`: A 3D incidence matrix for cause-cause relationships. This matrix must be in Numpy format with the shape (key informants, rows, columns).
- `CE`: A 3D incidence matrix for cause-effect relationships. This matrix must be in Numpy format with the shape (key informants, rows, columns).
- `EE`: A 3D incidence matrix for effect-effect relationships. This matrix must be in Numpy format with the shape (key informants, rows, columns).
- `causes`: (optional) A list or tuple of strings representing custom names for the causes. If not specified, the causes will be automatically named using the notation $a_1, a_2, \dots, a_n$, where $n$ is the number of evaluated causes.
- `effects`: (optional) A list or tuple of strings representing custom names for the effects. If not specified, the effects will be automatically named using the notation $b_1, b_2, \dots, b_m$, where $m$ is the number of evaluated effects.
- `THR` (float): Defines the degree of truth in which incidence is considered significant within the range [0,1] (default $0.5$).
- `conf_level` (float): Confidence level for intervals (default $0.95$).
- `reps` (int): Defines the number of bootstrap replicates (default $10000$).
#### Returns:
A DataFrame with the following columns:
- `From`: Origin node of the incidence.
- `To`: Destination node of the incidence.
- `Mean`: Mean incidence across experts.
- `UCI`: Upper confidence interval limit.
- `p.value`: Calculated p-value.
### Example (Chained bipartite graph)
```
import forgeffects as fe
# Compute direct effects
de_results = fe.directEffects(CC, CE, EE, rep=10000, THR=0.5, conf_level=0.95)
# Display the results
print(de_results)
```
### Results
The example demonstrates the direct effects identified by the function:
| From | To | Mean | UCI | p.value |
|:----:|:----:|:------:|:------:|:-------:|
| a1 | a2 | 0.525 | 0.650 | 0.5979 |
| a1 | a3 | 0.450 | 0.590 | 0.2855 |
| a1 | a4 | 0.525 | 0.665 | 0.6086 |
| a1 | a5 | 0.465 | 0.650 | 0.3648 |
| a1 | a6 | 0.645 | 0.805 | 0.8767 |
| ... | ... | ... | ... | ... |
| b3 | b2 | 0.835 | 0.890 | 0.9996 |
| b3 | b4 | 0.645 | 0.785 | 0.8997 |
| b4 | b1 | 0.800 | 0.920 | 0.9267 |
| b4 | b2 | 0.805 | 0.900 | 0.9974 |
| b4 | b3 | 0.820 | 0.900 | 0.9994 |
<p><b>[316 rows x 5 columns]</b></p>
## References
[1] Kaufmann, A. and Gil Aluja, J. *Models for the Research of Forgotten Effects*. Milladoiro, Santiago de Compostela, Spain, 1988.
[2] Manna, E. M., Rojas-Mora, J., & Mondaca-Marino, C. *Application of the Forgotten Effects Theory for Assessing the Public Policy on Air Pollution of the Commune of Valdivia, Chile*. In *From Science to Society* (pp. 61-72). Springer, Cham, 2018.
[3] Mardones-Arias, E.; Rojas-Mora, J. *foRgotten*. R package version 1.1.0, 2022.
[4] Chávez-Bustamante, F.; Mardones-Arias, E.; Rojas-Mora, J.; Tijmes-Ihl, J.\
*A Forgotten Effects Approach to the Analysis of Complex Economic Systems: Identifying Indirect Effects on Trade Networks*. Mathematics, 11(3), Article 531, 2023.
[5] Kohl, M. *MKinfer: Inferential Statistics*. R package version 1.2, 2024.
Raw data
{
"_id": null,
"home_page": "https://github.com/claudio-araya/forgeffects",
"name": "forgeffects",
"maintainer": null,
"docs_url": null,
"requires_python": "<=3.11,>=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Claudio Esteban Araya Toro",
"author_email": "claudioesteban.at@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/fc/c9/768f39b684dc0bf3d2f7ee2a9067db1983d124933b0f945edf2d9154e62f/forgeffects-0.2.4.tar.gz",
"platform": null,
"description": " \n\n**forgeffects** is a Python package designed for the analysis and computation of forgotten effects and direct effects. It leverages tensor-based computations, aggregating data from multiple key informants to process chained bipartite or complete graphs using 3D tensors.\n\n\n## Installation\n\nInstall the package from PyPI:\n\n``` \npip install forgeffects\n```\n\n## Included Datasets\n\nThe **forgeffects** package includes three 3D incidence matrices: `CC`, `CE`, and `EE`, used in the study *Application of Forgotten Effects Theory to Evaluate Public Policy on Air Pollution in the Municipality of Valdivia, Chile*.\n\nThe data corresponds to sixteen incentives, four behaviors, and ten key informants. These matrices can be loaded using the `load_test_data()` function, which accesses `.npy` files stored in the package.\n\nExample:\n\n``` \nimport forgeffects as fe\n\nCC = fe.load_test_data(\"CC.npy\")\nCE = fe.load_test_data(\"CE.npy\")\nEE = fe.load_test_data(\"EE.npy\")\n```\n\n# Usage\n\n## Graph Types\n\n- **Complete Graphs**: To perform calculations with complete graphs, you only need to provide either the `CC` matrix (cause-cause relationships) or the `EE` matrix (effect-effect relationships). The `CE` matrix is not required for this type of graph.\n\n- **Chained Bipartite Graphs**: To perform calculations with chained bipartite graphs, all three matrices (`CC`, `CE`, and `EE`) must be provided. These matrices represent cause-cause, cause-effect, and effect-effect relationships, respectively, and are necessary to construct the bipartite graph structure.\n\n\n## Forgotten Effects\n\nThe `FE()` function identifies indirect paths between causes and effects, enabling the discovery of forgotten effects. It uses iterative max-min convolutions to analyze these paths, filtering results based on a specified significance threshold and exploring up to a defined maximum order of forgotten effects.\n\n#### Parameters:\n\n- `CC`: A 3D incidence matrix for cause-cause relationships. This matrix must be in Numpy format with the shape (key informants, rows, columns).\n- `CE`: A 3D incidence matrix for cause-effect relationships. This matrix must be in Numpy format with the shape (key informants, rows, columns).\n- `EE`: A 3D incidence matrix for effect-effect relationships. This matrix must be in Numpy format with the shape (key informants, rows, columns).\n- `causes`: (optional) A list or tuple of strings representing custom names for the causes. If not specified, the causes will be automatically named using the notation $a_1, a_2, \\dots, a_n$, where $n$ is the number of evaluated causes.\n- `effects`: (optional) A list or tuple of strings representing custom names for the effects. If not specified, the effects will be automatically named using the notation $b_1, b_2, \\dots, b_m$, where $m$ is the number of evaluated effects.\n- `THR` (float): Defines the degree of truth in which incidence is considered significant within the range [0,1] (default $0.5$).\n- `maxorder` (int): Maximum order of forgotten effects to compute (default $2$).\n- `reps` (int): Number of replicas for empirical resampling (default $1000$).\n\n#### Returns:\n\nA list of DataFrames, each corresponding to an evaluated order of forgotten effects, with the following columns:\n\n- `From`: Origin node of the indirect relationship.\n- `Through_x`: Intermediary nodes (dynamic based on the evaluated order).\n- `To`: Destination node of the indirect relationship.\n- `Count`: Number of times a forgotten effect is repeated across different experts.\n- `Mean`: Mean of the forgotten effects identified.\n- `SD`: Standard deviation.\n\n### Example (Chained bipartite graph)\n\n``` \nimport forgeffects as fe\n\n# Compute forgotten effects\nfe_results = fe.FE(CC, CE, EE, rep=10000, THR=0.5, maxorder=3)\n\n# Display the results for the second-order forgotten effects\nprint(fe_results[0])\n\n# Note: If additional orders are found, the results for third-order effects can be accessed using fe_results[1],\n# for fourth-order effects using fe_results[2], and so on.\n```\n\n### Results\n\nThe example demonstrates the second-order forgotten effects identified by the function\n\n| From | Through1 | To | Count | Mean | SD |\n|:----:|:--------:|:---:|:-----:|:--------:|:--------:|\n| a10 | a11 | a14 | 2134 | 0.660128 | 0.088254 |\n| a13 | a16 | a1 | 2038 | 0.638836 | 0.080122 |\n| a3 | a6 | a9 | 1910 | 0.642309 | 0.081263 |\n| a8 | a13 | a10 | 1905 | 0.713915 | 0.100976 |\n| a13 | a6 | a9 | 1698 | 0.662080 | 0.083397 |\n| ... | ... | ... | ... | ... | ... |\n| a9 | a3 | a10 | 1 | 0.531971 | 0.000000 |\n| a5 | b2 | b4 | 1 | 0.513954 | 0.000000 |\n| a5 | a14 | a9 | 1 | 0.541666 | 0.000000 |\n| a2 | a16 | a5 | 1 | 0.582708 | 0.000000 |\n| a3 | a10 | b4 | 1 | 0.517474 | 0.000000 |\n\n<p><b>[3725 rows x 6 columns]</b></p>\n\n## Direct Effects\n\nThe `directEffects()` function calculates direct effects by estimating mean incidences, confidence intervals, and p-values. It uses a one-sided t-test with bootstrapping to evaluate the significance of direct relationships.\n\n#### Parameters:\n\n- `CC`: A 3D incidence matrix for cause-cause relationships. This matrix must be in Numpy format with the shape (key informants, rows, columns).\n- `CE`: A 3D incidence matrix for cause-effect relationships. This matrix must be in Numpy format with the shape (key informants, rows, columns).\n- `EE`: A 3D incidence matrix for effect-effect relationships. This matrix must be in Numpy format with the shape (key informants, rows, columns).\n- `causes`: (optional) A list or tuple of strings representing custom names for the causes. If not specified, the causes will be automatically named using the notation $a_1, a_2, \\dots, a_n$, where $n$ is the number of evaluated causes.\n- `effects`: (optional) A list or tuple of strings representing custom names for the effects. If not specified, the effects will be automatically named using the notation $b_1, b_2, \\dots, b_m$, where $m$ is the number of evaluated effects.\n- `THR` (float): Defines the degree of truth in which incidence is considered significant within the range [0,1] (default $0.5$).\n- `conf_level` (float): Confidence level for intervals (default $0.95$).\n- `reps` (int): Defines the number of bootstrap replicates (default $10000$).\n\n#### Returns:\n\nA DataFrame with the following columns:\n\n- `From`: Origin node of the incidence.\n- `To`: Destination node of the incidence.\n- `Mean`: Mean incidence across experts.\n- `UCI`: Upper confidence interval limit.\n- `p.value`: Calculated p-value.\n\n### Example (Chained bipartite graph)\n\n``` \nimport forgeffects as fe\n\n# Compute direct effects\nde_results = fe.directEffects(CC, CE, EE, rep=10000, THR=0.5, conf_level=0.95)\n\n# Display the results\nprint(de_results)\n```\n\n### Results\n\nThe example demonstrates the direct effects identified by the function:\n\n| From | To | Mean | UCI | p.value |\n|:----:|:----:|:------:|:------:|:-------:|\n| a1 | a2 | 0.525 | 0.650 | 0.5979 |\n| a1 | a3 | 0.450 | 0.590 | 0.2855 |\n| a1 | a4 | 0.525 | 0.665 | 0.6086 |\n| a1 | a5 | 0.465 | 0.650 | 0.3648 |\n| a1 | a6 | 0.645 | 0.805 | 0.8767 |\n| ... | ... | ... | ... | ... |\n| b3 | b2 | 0.835 | 0.890 | 0.9996 |\n| b3 | b4 | 0.645 | 0.785 | 0.8997 |\n| b4 | b1 | 0.800 | 0.920 | 0.9267 |\n| b4 | b2 | 0.805 | 0.900 | 0.9974 |\n| b4 | b3 | 0.820 | 0.900 | 0.9994 |\n\n<p><b>[316 rows x 5 columns]</b></p>\n\n\n## References\n\n[1] Kaufmann, A. and Gil Aluja, J. *Models for the Research of Forgotten Effects*. Milladoiro, Santiago de Compostela, Spain, 1988.\n\n[2] Manna, E. M., Rojas-Mora, J., & Mondaca-Marino, C. *Application of the Forgotten Effects Theory for Assessing the Public Policy on Air Pollution of the Commune of Valdivia, Chile*. In *From Science to Society* (pp. 61-72). Springer, Cham, 2018.\n\n[3] Mardones-Arias, E.; Rojas-Mora, J. *foRgotten*. R package version 1.1.0, 2022.\n\n[4] Ch\u00e1vez-Bustamante, F.; Mardones-Arias, E.; Rojas-Mora, J.; Tijmes-Ihl, J.\\\n*A Forgotten Effects Approach to the Analysis of Complex Economic Systems: Identifying Indirect Effects on Trade Networks*. Mathematics, 11(3), Article 531, 2023.\n\n[5] Kohl, M. *MKinfer: Inferential Statistics*. R package version 1.2, 2024.\n",
"bugtrack_url": null,
"license": null,
"summary": "A package for forgotten effects theory computation.",
"version": "0.2.4",
"project_urls": {
"Homepage": "https://github.com/claudio-araya/forgeffects"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9aecd1bd74583395000310f6fa38ea31345a612efa39d757ce1717b02100562e",
"md5": "bef6d3f24908271dca51127b7dd7916a",
"sha256": "c9553f4d92ca2c63bdfa76cd2271e92198df0800bfa147df67050061e659f488"
},
"downloads": -1,
"filename": "forgeffects-0.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bef6d3f24908271dca51127b7dd7916a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<=3.11,>=3.9",
"size": 21229,
"upload_time": "2024-12-08T03:49:22",
"upload_time_iso_8601": "2024-12-08T03:49:22.687246Z",
"url": "https://files.pythonhosted.org/packages/9a/ec/d1bd74583395000310f6fa38ea31345a612efa39d757ce1717b02100562e/forgeffects-0.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fcc9768f39b684dc0bf3d2f7ee2a9067db1983d124933b0f945edf2d9154e62f",
"md5": "e9b13a3f10d121c8372dcc6229fa9556",
"sha256": "548dce8abd7ef75055e1f2530b26cf403db4ab987175e34db1f2bb5e2b542260"
},
"downloads": -1,
"filename": "forgeffects-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "e9b13a3f10d121c8372dcc6229fa9556",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<=3.11,>=3.9",
"size": 20909,
"upload_time": "2024-12-08T03:49:23",
"upload_time_iso_8601": "2024-12-08T03:49:23.968057Z",
"url": "https://files.pythonhosted.org/packages/fc/c9/768f39b684dc0bf3d2f7ee2a9067db1983d124933b0f945edf2d9154e62f/forgeffects-0.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-08 03:49:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "claudio-araya",
"github_project": "forgeffects",
"github_not_found": true,
"lcname": "forgeffects"
}
JSON
