| Name | karstnet JSON |
| Version |
1.2.5
JSON |
| download |
| home_page | None |
| Summary | Statistical characterization of karst networks |
| upload_time | 2024-08-30 16:41:34 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License Copyright (c) 2018-2024 Karstnet Developers: Philippe Renard <philippe.renard@unine.ch> Pauline Collon <pauline.collon@univ-lorraine.fr> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
geomorphology
karst
graph
statistics
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
|
| coveralls test coverage |
No coveralls.
|
# Karstnet - statistics of karstic networks
Karstnet is a python3 project providing tools for the statistical analysis of karstic networks.
[](https://karstnet.readthedocs.io/en/latest/?badge=latest)
Version 1.2.5 - August 2024
Please check the file [changelog.md](changelog.md) to track the novel functionalities of karstnet.
## Simple installation from pypi.org
If you just need to use karstnet (e.g. in Jupyter notebooks), the simplest way to install it is to get it from [Pypi.org](https://pypi.org/) by typing the command:
`pip install karstnet`
This command should install directly all the required dependencies for a fully functional version of karstnet and you do not need to download manually anything.
## Installation from github
If you want to access the source code and potentially contribute. You should follow the following steps.
### 1. Download
Download karstnet from the [Github repository](https://github.com/karstnet/karstnet): green button "clone or download". Then, unzip it on your computer.
### 2. Go in the directory
Once this has been done, open a Python prompt (like the Anaconda prompt), and go to your directory location (ex:
`cd C:\Users\YourName\Documents\KARSTNET\karstnet`).
### 3. Launch the local installation
You have three options: the minimal one will install the code.
`pip install .`
Do not forget the point "." at the end of the command
If you want to run it directly from the source files (useful for development):
` pip install -e .`
You can also install all the dependencies used in karstnet to have complete development environment:
` pip install -e .[dev]`
All these options can also be run without moving previously in the karstnet folder.
In that case, just type in your Anaconda prompt :
` pip install -e your\path\to\karstnet`
### 4. Testing
If you start modifying the code, you should regularly check that you did not break some key features. For that you can run the unit tests. From source directory, and after instaling **karstnet** run:
`pytest tests/test_karstnet.py`
## In Jupyter notebooks
Example of jupyter notebooks are provided to help you use **karstnet**.
To use **karstnet** in notebooks, you just have to write
`import karstnet as kn`
A call-test function is available to help you check if the package is ready to use : just type:
`kn.test_kn()`
## Documentation
The html documentation is available in the sub directory: [docs/_build/html/index.html](docs/_build/html/index.html)
and it is available online at: https://karstnet.readthedocs.io/
A french version of a guide for students willing to code karstnet extensions is available:
[FR_GuideDebutant_karstnet_jupyter_github.pdf](docs/pdf/FR_GuideDebutant_karstnet_jupyter_github.pdf)
**Remark on ENTROPIES**:
Note that, by default, Karstnet computes Entropies as described in the paper (mode = "default") :
on normalized values ranged on 10 bins for branch lengths and on 18 bins of 10° for orientations
**If you want to compute entropies using Sturges'rule use** :
l_entrop = myKGraph.length_entropy(mode = "sturges")
or_entropy = myKGraph.orientation_entropy(mode = "sturges")
## Reference and Corrigendum
The karstnet package implements some of the statistical metrics that were
investigated and discussed in:
Collon, P., Bernasconi D., Vuilleumier C., and Renard P., 2017, Statistical
metrics for the characterization of karst network geometry and topology.
Geomorphology. 283: 122-142 doi:10.1016/j.geomorph.2017.01.034
<http://dx.doi.org/doi:10.1016/j.geomorph.2017.01.034>
An **updated paper** (see remarks below) is available in the "doc" folder of this github and
can be downloaded here <https://hal.univ-lorraine.fr/hal-01468055v3/document>.
(complete link : <https://hal.univ-lorraine.fr/hal-01468055>)
**Concerning the paper, important remarks should be made :**
There was some **errors** in the old Matlab implementation (the one used for the paper) **that have been corrected in Karstnet**.
A **corrigendum** has been published in Geomorphology journal : Geomorphology 389, 107848. <http://dx.doi.org/doi:10.1016/j.geomorph.2021.107848>.
The **results** obtained on the same 34 networks than the ones used for the paper but
with the **implementation of Karstnet** are proposed for information in the **doc part** (New_Statistics_results.xls)
as well as the updated author version of the paper in pdf : **2016Pap_Collon_Geomorphology_Autho_Upd_2021.pdf**.
Here we summarize the main differences :
**Correlation of Vertex Degrees, rk** : The corrected values of the correlation of vertex degree, rk, are all negative, indicating that the karstic networks in our data set are disassortative as it was reported for other natural networks by Newman (2002).
**Branch lengths entropy, Hlen** : In the previous Matlab code, we computed the branch length entropy on 11 bins instead of the 10 bins described in the paper. Correcting this (computing on 10 bins) slightly decreases the values, ranging now from 0.07 to 0.67 instead of 0.18 to 0.74 (page 9). The Karstnet values are now correct.
**CVlengths** : just an error of transcription in the table 2 of the paper where CVlen was supposed to be provided in %, but was provided in standard number
**branch lengths** : In the previous code, when computing the mean length of the branches, the looping branches (branches that closes on the starting point) were ignored. If this is meaningful for tortuosity computation, these branches should not be ignored for the mean length computation. This has been corrected and explains the minor differences observable for the mean length values of Agen Allwed, Daren Cilau, Foussoubie Goule, Krubera, Lechuguilla, MammuthHöhle, Ratasse, SaintMarcel, Sakany, Shuanghe, SiebenHengsteFull and SiebenHengsteSP2.
**SPL** : In addition, the previous code also ignored independent connected components of two nodes. This is not justified. This correction slightly impacts the values of the (SPL) coefficient of Agen Allwed, Arphidia Robinet, Daren Cilau, Grotte du Roy, Krubera, Lechuguilla, Llangattwg, MammuthHöhle Ratasse, SaintMarcel, Sakany, SiebenHengsteUpPart
We are sorry for any inconvenience.
Raw data
{
"_id": null,
"home_page": null,
"name": "karstnet",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "geomorphology, karst, graph, statistics",
"author": null,
"author_email": "Philippe Renard <philippe.renard@unine.ch>, Pauline Collon <pauline.collon@univ-lorraine.fr>",
"download_url": "https://files.pythonhosted.org/packages/3f/90/87bb4072d7e3b2ed3eb29f3f3a3a6de3d3e4ce5b4e88a293e8bcf89eabf8/karstnet-1.2.5.tar.gz",
"platform": null,
"description": "# Karstnet - statistics of karstic networks\r\n\r\nKarstnet is a python3 project providing tools for the statistical analysis of karstic networks.\r\n\r\n[](https://karstnet.readthedocs.io/en/latest/?badge=latest)\r\n\r\n\r\n\r\nVersion 1.2.5 - August 2024 \r\n\r\nPlease check the file [changelog.md](changelog.md) to track the novel functionalities of karstnet.\r\n\r\n\r\n## Simple installation from pypi.org\r\n\r\nIf you just need to use karstnet (e.g. in Jupyter notebooks), the simplest way to install it is to get it from [Pypi.org](https://pypi.org/) by typing the command:\r\n\r\n`pip install karstnet`\r\n\r\nThis command should install directly all the required dependencies for a fully functional version of karstnet and you do not need to download manually anything.\r\n\r\n## Installation from github\r\n\r\nIf you want to access the source code and potentially contribute. You should follow the following steps.\r\n\r\n### 1. Download\r\n\r\nDownload karstnet from the [Github repository](https://github.com/karstnet/karstnet): green button \"clone or download\". Then, unzip it on your computer. \r\n\r\n\r\n### 2. Go in the directory\r\n\r\nOnce this has been done, open a Python prompt (like the Anaconda prompt), and go to your directory location (ex: \r\n`cd C:\\Users\\YourName\\Documents\\KARSTNET\\karstnet`).\r\n\r\n### 3. Launch the local installation\r\n\r\nYou have three options: the minimal one will install the code.\r\n\r\n`pip install .`\r\n\r\nDo not forget the point \".\" at the end of the command\r\n\r\nIf you want to run it directly from the source files (useful for development):\r\n\r\n` pip install -e .`\r\n\r\nYou can also install all the dependencies used in karstnet to have complete development environment:\r\n\r\n` pip install -e .[dev]`\r\n\r\nAll these options can also be run without moving previously in the karstnet folder. \r\nIn that case, just type in your Anaconda prompt :\r\n\r\n` pip install -e your\\path\\to\\karstnet` \r\n\r\n### 4. Testing\r\n\r\nIf you start modifying the code, you should regularly check that you did not break some key features. For that you can run the unit tests. From source directory, and after instaling **karstnet** run:\r\n\r\n`pytest tests/test_karstnet.py`\r\n\r\n## In Jupyter notebooks\r\n\r\nExample of jupyter notebooks are provided to help you use **karstnet**. \r\nTo use **karstnet** in notebooks, you just have to write\r\n\r\n`import karstnet as kn`\r\n\r\nA call-test function is available to help you check if the package is ready to use : just type: \r\n`kn.test_kn()`\r\n\r\n## Documentation\r\n\r\nThe html documentation is available in the sub directory: [docs/_build/html/index.html](docs/_build/html/index.html)\r\n and it is available online at: https://karstnet.readthedocs.io/\r\n\r\nA french version of a guide for students willing to code karstnet extensions is available:\r\n[FR_GuideDebutant_karstnet_jupyter_github.pdf](docs/pdf/FR_GuideDebutant_karstnet_jupyter_github.pdf)\r\n\r\n\r\n**Remark on ENTROPIES**:\r\nNote that, by default, Karstnet computes Entropies as described in the paper (mode = \"default\") : \r\non normalized values ranged on 10 bins for branch lengths and on 18 bins of 10\u00b0 for orientations\r\n\r\n**If you want to compute entropies using Sturges'rule use** : \r\nl_entrop = myKGraph.length_entropy(mode = \"sturges\")\r\nor_entropy = myKGraph.orientation_entropy(mode = \"sturges\")\r\n\r\n\r\n## Reference and Corrigendum\r\n\r\nThe karstnet package implements some of the statistical metrics that were\r\ninvestigated and discussed in:\r\nCollon, P., Bernasconi D., Vuilleumier C., and Renard P., 2017, Statistical\r\nmetrics for the characterization of karst network geometry and topology.\r\nGeomorphology. 283: 122-142 doi:10.1016/j.geomorph.2017.01.034\r\n<http://dx.doi.org/doi:10.1016/j.geomorph.2017.01.034>\r\n\r\nAn **updated paper** (see remarks below) is available in the \"doc\" folder of this github and \r\ncan be downloaded here <https://hal.univ-lorraine.fr/hal-01468055v3/document>. \r\n (complete link : <https://hal.univ-lorraine.fr/hal-01468055>)\r\n\r\n**Concerning the paper, important remarks should be made :** \r\n\r\nThere was some **errors** in the old Matlab implementation (the one used for the paper) **that have been corrected in Karstnet**. \r\nA **corrigendum** has been published in Geomorphology journal : Geomorphology 389, 107848. <http://dx.doi.org/doi:10.1016/j.geomorph.2021.107848>.\r\nThe **results** obtained on the same 34 networks than the ones used for the paper but \r\nwith the **implementation of Karstnet** are proposed for information in the **doc part** (New_Statistics_results.xls) \r\nas well as the updated author version of the paper in pdf : **2016Pap_Collon_Geomorphology_Autho_Upd_2021.pdf**.\r\n\r\nHere we summarize the main differences : \r\n\r\n**Correlation of Vertex Degrees, rk** : The corrected values of the correlation of vertex degree, rk, are all negative, indicating that the karstic networks in our data set are disassortative as it was reported for other natural networks by Newman (2002). \r\n\t\r\n**Branch lengths entropy, Hlen** : In the previous Matlab code, we computed the branch length entropy on 11 bins instead of the 10 bins described in the paper. Correcting this (computing on 10 bins) slightly decreases the values, ranging now from 0.07 to 0.67 instead of 0.18 to 0.74 (page 9). The Karstnet values are now correct. \r\n\r\n**CVlengths** : just an error of transcription in the table 2 of the paper where CVlen was supposed to be provided in %, but was provided in standard number\r\n\r\n**branch lengths** : In the previous code, when computing the mean length of the branches, the looping branches (branches that closes on the starting point) were ignored. If this is meaningful for tortuosity computation, these branches should not be ignored for the mean length computation. This has been corrected and explains the minor differences observable for the mean length values of Agen Allwed, Daren Cilau, Foussoubie Goule, Krubera, Lechuguilla, MammuthH\u00f6hle, Ratasse, SaintMarcel, Sakany, Shuanghe, SiebenHengsteFull and SiebenHengsteSP2.\r\n\t\r\n**SPL** : In addition, the previous code also ignored independent connected components of two nodes. This is not justified. This correction slightly impacts the values of the (SPL) coefficient of Agen Allwed, Arphidia Robinet, Daren Cilau, Grotte du Roy, Krubera, Lechuguilla, Llangattwg, MammuthH\u00f6hle Ratasse, SaintMarcel, Sakany, SiebenHengsteUpPart\r\n\r\nWe are sorry for any inconvenience.\r\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2018-2024 Karstnet Developers: Philippe Renard <philippe.renard@unine.ch> Pauline Collon <pauline.collon@univ-lorraine.fr> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Statistical characterization of karst networks",
"version": "1.2.5",
"project_urls": {
"Documentation": "https://karstnet.readthedocs.org",
"Issues": "https://github.com/karstnet/karstnet/issues",
"Repository": "https://github.com/karstnet/karstnet"
},
"split_keywords": [
"geomorphology",
" karst",
" graph",
" statistics"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "30e71cc4a1fe13c7cb330957339d2d70aee88e217c92f2c5ff195f7dd6478bda",
"md5": "0831cab0a7c7d4fc48ae4fd19ae7de57",
"sha256": "52a7372e1c02c53c9059920b002299f2c3e9f0d83f70f978839051668412405f"
},
"downloads": -1,
"filename": "karstnet-1.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0831cab0a7c7d4fc48ae4fd19ae7de57",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 20960,
"upload_time": "2024-08-30T16:41:33",
"upload_time_iso_8601": "2024-08-30T16:41:33.049588Z",
"url": "https://files.pythonhosted.org/packages/30/e7/1cc4a1fe13c7cb330957339d2d70aee88e217c92f2c5ff195f7dd6478bda/karstnet-1.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3f9087bb4072d7e3b2ed3eb29f3f3a3a6de3d3e4ce5b4e88a293e8bcf89eabf8",
"md5": "9e88ffb5f49153f448cf75bf2782bfa1",
"sha256": "dcc31447ccf95a582f91608d73cc1b22611a75a2903616618e15b92372a86df7"
},
"downloads": -1,
"filename": "karstnet-1.2.5.tar.gz",
"has_sig": false,
"md5_digest": "9e88ffb5f49153f448cf75bf2782bfa1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 25341,
"upload_time": "2024-08-30T16:41:34",
"upload_time_iso_8601": "2024-08-30T16:41:34.997685Z",
"url": "https://files.pythonhosted.org/packages/3f/90/87bb4072d7e3b2ed3eb29f3f3a3a6de3d3e4ce5b4e88a293e8bcf89eabf8/karstnet-1.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-30 16:41:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "karstnet",
"github_project": "karstnet",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "karstnet"
}
