# unidas
[](https://codecov.io/gh/dasdae/unidas)
[](https://pypi.python.org/pypi/unidas)
[](https://opensource.org/license/mit)
A DAS compatibility package.
There is an increasing number of open-source libraries for working with distributed acoustic sensing (DAS) data. Each of these has its own strengths and weaknesses, and often it is desirable to use features from multiple libraries in research workflows. Moreover, creators of DAS packages which perform specific operations (e.g., machine learning for phase picking) currently have to choose a single DAS library to support, or undertake writing conversion codes on their own.
Unidas solves these problems by providing simple ways to interoperate between DAS libraries.
## Usage
There are two ways to use unidas. First, the `adapter` decorator allows a function to simply declare which library's data structure to use.
```python
import unidas
@unidas.adapter("daspy.Section")
def daspy_function(sec, **kwargs):
"""A useful daspy function"""
# Regardless of the actual input type, adapter will convert it to a daspy section
# then convert it back after the return.
return sec
import dascore as dc
patch = dc.get_example_patch()
# even though we call a daspy function, the input/output is a dascore patch.
out = daspy_function(patch)
assert isinstance(out, dc.Patch)
```
You can also use `adpater` to wrap un-wrapped functions.
```python
import dascore as dc
import unidas
from xdas.signal import hilbert
dascore_hilbert = unidas.adapter("xdas.DataArray")(hilbert)
patch = dc.get_example_patch()
patch_hilberto = dascore_hilbert(patch)
```
The `convert` function converts from one library's data structure to another library's data structure.
```python
import daspy
import unidas
# Use lightguide's afk filter with a daspy section.
sec = daspy.read()
blast = unidas.convert(sec, to="lightguide.Blast")
blast.afk_filter(exponent=0.8)
sec_out = unidas.convert(blast, to='daspy.Section')
```
## Installation
Simply install unidas with pip or mamba:
```bash
pip install unidas
```
```bash
mamba install unidas
```
By design, unidas has no hard dependencies other than numpy, but an `ImportError` will be raised if the libraries needed to perform a requested conversion are not installed.
Unidas is single file (src/unidas.py) so it can also be vendored (copied directly into your project). If you do this, please consider sharing any improvements so the entire community can benefit.
## Guidance for package developers
If you are creating/maintaining a library for doing some kind of specialized DAS processing in python, we recommend you do two things:
1. Pick the DAS library you prefer and use it internally.
2. Apply the `adapter` decorator to your project's API.
Doing so will make your project easily accessible by users of all the libraries supported by unidas.
For example:
```python
import unidas
@unidas.adapter("daspy.Section")
def fancy_machine_learning_function(sec):
"""Cutting edge machine learning DAS research function."""
# Here we will use daspy internally, but the function accepts
# data structures from other libraries with no additional effort
# because of the adapter decorator.
... # Fancy stuff goes here.
return sec
```
## Adding support for new libraries to unidas
To add support for a new data structure/library, you need to do two things:
1. Create a subclass of `Converter` which has (at least) a conversion method to unidas' BaseDAS.
2. Add a conversion method to UnidasBasDASConverter to convert from unidas' BaseDAS back to your data structure.
3. Write a test in test/test_unidas.py (this is important for maintainability).
Feel free to open a discussion if you need help.
## Supported libraries (in alphabetical order)
- [DASCore](https://github.com/DASDAE/dascore)
- [DASPy](https://github.com/HMZ-03/DASPy)
- [Lightguide](https://github.com/pyrocko/lightguide)
- [Xdas](https://github.com/xdas-dev/xdas)
Raw data
{
"_id": null,
"home_page": null,
"name": "unidas",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "distributed-acoustic-sensing, geophysics",
"author": null,
"author_email": "Derrick Chambers <chambers.ja.derrick@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/a7/89/2f4d3bf7c682d232af95876381701d68739dffad03ac126c90cf120f7aa1/unidas-0.0.1.tar.gz",
"platform": null,
"description": "# unidas\n\n[](https://codecov.io/gh/dasdae/unidas)\n[](https://pypi.python.org/pypi/unidas)\n[](https://opensource.org/license/mit)\n\nA DAS compatibility package.\n\nThere is an increasing number of open-source libraries for working with distributed acoustic sensing (DAS) data. Each of these has its own strengths and weaknesses, and often it is desirable to use features from multiple libraries in research workflows. Moreover, creators of DAS packages which perform specific operations (e.g., machine learning for phase picking) currently have to choose a single DAS library to support, or undertake writing conversion codes on their own.\n\nUnidas solves these problems by providing simple ways to interoperate between DAS libraries. \n\n## Usage\n\nThere are two ways to use unidas. First, the `adapter` decorator allows a function to simply declare which library's data structure to use. \n\n```python\nimport unidas\n\n\n@unidas.adapter(\"daspy.Section\")\ndef daspy_function(sec, **kwargs):\n \"\"\"A useful daspy function\"\"\"\n # Regardless of the actual input type, adapter will convert it to a daspy section\n # then convert it back after the return.\n return sec\n\n\nimport dascore as dc\n\npatch = dc.get_example_patch()\n# even though we call a daspy function, the input/output is a dascore patch.\nout = daspy_function(patch)\nassert isinstance(out, dc.Patch)\n```\n\nYou can also use `adpater` to wrap un-wrapped functions. \n\n```python\nimport dascore as dc\nimport unidas\nfrom xdas.signal import hilbert\n\ndascore_hilbert = unidas.adapter(\"xdas.DataArray\")(hilbert)\npatch = dc.get_example_patch()\n\npatch_hilberto = dascore_hilbert(patch)\n```\n\nThe `convert` function converts from one library's data structure to another library's data structure.\n\n```python\nimport daspy\nimport unidas\n\n# Use lightguide's afk filter with a daspy section. \nsec = daspy.read()\nblast = unidas.convert(sec, to=\"lightguide.Blast\")\nblast.afk_filter(exponent=0.8)\nsec_out = unidas.convert(blast, to='daspy.Section')\n```\n\n## Installation\nSimply install unidas with pip or mamba:\n\n```bash\npip install unidas \n```\n\n```bash\nmamba install unidas\n```\n\nBy design, unidas has no hard dependencies other than numpy, but an `ImportError` will be raised if the libraries needed to perform a requested conversion are not installed.\n\nUnidas is single file (src/unidas.py) so it can also be vendored (copied directly into your project). If you do this, please consider sharing any improvements so the entire community can benefit. \n\n## Guidance for package developers\nIf you are creating/maintaining a library for doing some kind of specialized DAS processing in python, we recommend you do two things:\n\n1. Pick the DAS library you prefer and use it internally. \n2. Apply the `adapter` decorator to your project's API.\n\nDoing so will make your project easily accessible by users of all the libraries supported by unidas. \n\nFor example:\n\n```python\nimport unidas\n\n@unidas.adapter(\"daspy.Section\")\ndef fancy_machine_learning_function(sec):\n \"\"\"Cutting edge machine learning DAS research function.\"\"\"\n # Here we will use daspy internally, but the function accepts \n # data structures from other libraries with no additional effort\n # because of the adapter decorator. \n \n ... # Fancy stuff goes here.\n \n return sec\n```\n\n## Adding support for new libraries to unidas\n\nTo add support for a new data structure/library, you need to do two things:\n\n1. Create a subclass of `Converter` which has (at least) a conversion method to unidas' BaseDAS.\n2. Add a conversion method to UnidasBasDASConverter to convert from unidas' BaseDAS back to your data structure.\n3. Write a test in test/test_unidas.py (this is important for maintainability).\n\nFeel free to open a discussion if you need help. \n\n## Supported libraries (in alphabetical order)\n\n- [DASCore](https://github.com/DASDAE/dascore)\n- [DASPy](https://github.com/HMZ-03/DASPy)\n- [Lightguide](https://github.com/pyrocko/lightguide)\n- [Xdas](https://github.com/xdas-dev/xdas)\n",
"bugtrack_url": null,
"license": null,
"summary": "A DAS compatibility library",
"version": "0.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/unidas-dev/unidas",
"Documentation": "https://github.com/unidas-dev/unidas",
"Homepage": "https://github.com/unidas-dev/unidas"
},
"split_keywords": [
"distributed-acoustic-sensing",
" geophysics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d812814acef5cee1530a31f409e342abe4c523869e4eb0166cba976bbe361505",
"md5": "64046e20509b59b8f734882af1825196",
"sha256": "489a0f38da4eaffab52802145ff8030bf46f4f0d9503a8a6c4bd31ca218ff4ca"
},
"downloads": -1,
"filename": "unidas-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "64046e20509b59b8f734882af1825196",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 11295,
"upload_time": "2024-12-18T15:05:26",
"upload_time_iso_8601": "2024-12-18T15:05:26.961092Z",
"url": "https://files.pythonhosted.org/packages/d8/12/814acef5cee1530a31f409e342abe4c523869e4eb0166cba976bbe361505/unidas-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a7892f4d3bf7c682d232af95876381701d68739dffad03ac126c90cf120f7aa1",
"md5": "d9a55c51c9c9b0ceb3d721f22f940fc4",
"sha256": "8a635543af6021503455b80f7067c2c862436e0af6f7662c0303586ce18d10b9"
},
"downloads": -1,
"filename": "unidas-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "d9a55c51c9c9b0ceb3d721f22f940fc4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 17376,
"upload_time": "2024-12-18T15:05:27",
"upload_time_iso_8601": "2024-12-18T15:05:27.914358Z",
"url": "https://files.pythonhosted.org/packages/a7/89/2f4d3bf7c682d232af95876381701d68739dffad03ac126c90cf120f7aa1/unidas-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-18 15:05:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "unidas-dev",
"github_project": "unidas",
"github_not_found": true,
"lcname": "unidas"
}
JSON
