# Welcome to `fast_boltzmann`
`fast_boltzmann` is a Python package developed for the fast computation of the Boltzmann Entropy (also known as configurational entropy) for a two-dimensional numerical or nominal data array. This package focuses on streamlining the sliding window-based computation procedure to achieve lightweight, fast, and user-friendly calculations. It does this by utilizing matrix calculations and vectorized functions.
## Installation
You can easily install this package using `pip`:
```bash
pip install fast_boltzmann
```
## Dependencies
- numpy (>= 1.20.0)
## Example usage
Calculate the Boltzmann Entropy of the first band and the average of all bands in a multi-spectral Landsat raster image.
```python
>>> import fast_boltzmann as fb
>>> from osgeo import gdal
>>> img_array = gdal.Open('./example/example_multispectral_image.tif').ReadAsArray()
>>> img_array.shape # Check whether the data array has 2 dims.
(6, 500, 500) # The data array has 3 dims. Extracting each band is required.
>>> img_array.dtype # Check whether the datatype is integer.
dtype('uint16') # The datatype is non-negative integer that meets the requirement.
>>> b1 = img_array[0, :, :] # Take the first band as an example.
>>> b1_bnu = fb.BoltzNumerical(b1)
>>> BE_b1 = b1_bnu.get_boltzmann_numerical() # resampling-based method, relative BE, normlize to all pixels
>>> round(BE_b1, 4)
8.6047
>>> res_list = [fb.BoltzNumerical(img_array[i, :, :]).get_boltzmann_numerical() for i in range(img_array.shape[0])]
>>> res_list # Store BE values for all bands in a list
[8.60467561853229, 9.03175324743007, 9.853283840481888, 9.992600722500507, 10.293043710639683, 10.09777221607461]
>>> BE_img_average = sum(res_list)/img_array.shape[0] # Calculate the average BE value of the image
>>> round(BE_img_average, 4)
9.6455
```
## Limitation
Currently, only **non-negative integer** arrays can be used to calculate the Boltzmann Entropy. If your data range is between 0-1, you may consider multiplying the data array by 10 or 100 and taking it to integer, or extending it to an integer range of 0-255. If you are fairly certain that the array can be **safely** converted to the integer, please use `data=data.astype(‘int’)`.
For the aggregation-based method, there may be dangling pixels that cannot be covered by the 2*2 window/chunk. The input data array may lose some features as these pixels are removed in the computation.
Please refer to the references listed below for more information.
## References
- Gao, P., Zhang, H., & Li, Z. (2017). A hierarchy-based solution to calculate the configurational entropy of landscape gradients. Landscape ecology, 32(6), 1133-1146.
- Gao, P., & Li, Z. (2019a). Aggregation-based method for computing absolute Boltzmann entropy of landscape gradient with full thermodynamic consistency. Landscape Ecology, 34(8), 1837-1847.
- Gao, P., & Li, Z. (2019b). Computation of the Boltzmann entropy of a landscape: A review and a generalization. Landscape Ecology, 34(9), 2183-2196.
Raw data
{
"_id": null,
"home_page": "https://github.com/geoye/fast_boltzmann",
"name": "fast-boltzmann",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "python,entropy,quality assessment,thermodynamic consistency,landscape ecology",
"author": "Yuxuan YE<yuxuanye145@gmail.com>, Xinghua Cheng<cxh9791156936@gmail.com>",
"author_email": "yuxuanye145@gmail.com, cxh9791156936@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/fe/3c/461661178543138a1fae2b5290bae79c4f3410bdeb075f52deb3d976c073/fast_boltzmann-1.0.0.tar.gz",
"platform": null,
"description": "# Welcome to `fast_boltzmann`\n`fast_boltzmann` is a Python package developed for the fast computation of the Boltzmann Entropy (also known as configurational entropy) for a two-dimensional numerical or nominal data array. This package focuses on streamlining the sliding window-based computation procedure to achieve lightweight, fast, and user-friendly calculations. It does this by utilizing matrix calculations and vectorized functions.\n\n## Installation\n\nYou can easily install this package using `pip`:\n\n```bash\npip install fast_boltzmann\n```\n\n## Dependencies\n\n- numpy (>= 1.20.0)\n\n## Example usage\n\nCalculate the Boltzmann Entropy of the first band and the average of all bands in a multi-spectral Landsat raster image.\n\n```python\n>>> import fast_boltzmann as fb\n>>> from osgeo import gdal\n>>> img_array = gdal.Open('./example/example_multispectral_image.tif').ReadAsArray()\n>>> img_array.shape # Check whether the data array has 2 dims.\n(6, 500, 500) # The data array has 3 dims. Extracting each band is required.\n>>> img_array.dtype # Check whether the datatype is integer.\ndtype('uint16') # The datatype is non-negative integer that meets the requirement.\n>>> b1 = img_array[0, :, :] # Take the first band as an example.\n>>> b1_bnu = fb.BoltzNumerical(b1)\n>>> BE_b1 = b1_bnu.get_boltzmann_numerical() # resampling-based method, relative BE, normlize to all pixels\n>>> round(BE_b1, 4)\n8.6047\n>>> res_list = [fb.BoltzNumerical(img_array[i, :, :]).get_boltzmann_numerical() for i in range(img_array.shape[0])]\n>>> res_list # Store BE values for all bands in a list\n[8.60467561853229, 9.03175324743007, 9.853283840481888, 9.992600722500507, 10.293043710639683, 10.09777221607461]\n>>> BE_img_average = sum(res_list)/img_array.shape[0] # Calculate the average BE value of the image\n>>> round(BE_img_average, 4)\n9.6455\n```\n\n## Limitation\n\nCurrently, only **non-negative integer** arrays can be used to calculate the Boltzmann Entropy. If your data range is between 0-1, you may consider multiplying the data array by 10 or 100 and taking it to integer, or extending it to an integer range of 0-255. If you are fairly certain that the array can be **safely** converted to the integer, please use `data=data.astype(\u2018int\u2019)`. \n\nFor the aggregation-based method, there may be dangling pixels that cannot be covered by the 2*2 window/chunk. The input data array may lose some features as these pixels are removed in the computation.\n\nPlease refer to the references listed below for more information.\n\n## References\n- Gao, P., Zhang, H., & Li, Z. (2017). A hierarchy-based solution to calculate the configurational entropy of landscape gradients. Landscape ecology, 32(6), 1133-1146.\n- Gao, P., & Li, Z. (2019a). Aggregation-based method for computing absolute Boltzmann entropy of landscape gradient with full thermodynamic consistency. Landscape Ecology, 34(8), 1837-1847.\n- Gao, P., & Li, Z. (2019b). Computation of the Boltzmann entropy of a landscape: A review and a generalization. Landscape Ecology, 34(9), 2183-2196.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "`fast_boltzmann` is a Python package developed for the fast computation of the Boltzmann Entropy (also known as configurational entropy) for a two-dimensional numerical or nominal data array.",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/geoye/fast_boltzmann/issues",
"Homepage": "https://github.com/geoye/fast_boltzmann",
"Source": "https://github.com/geoye/fast_boltzmann"
},
"split_keywords": [
"python",
"entropy",
"quality assessment",
"thermodynamic consistency",
"landscape ecology"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fe3c461661178543138a1fae2b5290bae79c4f3410bdeb075f52deb3d976c073",
"md5": "f192761ddda7e6a8777b836ecda197cc",
"sha256": "665b20ab233552806396a9dc1523bdf6139dd9cde7ed5a622e113062a968ad93"
},
"downloads": -1,
"filename": "fast_boltzmann-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "f192761ddda7e6a8777b836ecda197cc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 7356,
"upload_time": "2023-07-07T17:07:11",
"upload_time_iso_8601": "2023-07-07T17:07:11.949768Z",
"url": "https://files.pythonhosted.org/packages/fe/3c/461661178543138a1fae2b5290bae79c4f3410bdeb075f52deb3d976c073/fast_boltzmann-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-07 17:07:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "geoye",
"github_project": "fast_boltzmann",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "fast-boltzmann"
}
JSON
