[![Build Status](https://travis-ci.org/dbbs-lab/glia.svg?branch=master)](https://travis-ci.org/dbbs-lab/glia)
[![codecov](https://codecov.io/gh/dbbs-lab/glia/branch/master/graph/badge.svg)](https://codecov.io/gh/dbbs-lab/glia)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Documentation Status](https://readthedocs.org/projects/nrn-glia/badge/?version=latest)](https://nrn-glia.readthedocs.io/en/latest/?badge=latest)
# Glia: NEURON package manager
Glia is an asset manager for NEURON. It collects mod files from
different pip packages and compiles them into a central library that is
automatically loaded into NEURON. This removes the need for compiling
folder after folder with cluttered, duplicated mod files and allows you
to focus on using these mechanisms across multiple models.
Packaging your mod files as a Glia package allows you to distribute them
as dependencies of your Python models and delegates the installation,
distribution, versioning and archiving of your assets to Python's packet
manager pip.
To create Glia packages, check out the CLI tool
[Astrocyte](https://astrocyte.readthedocs.io/en/latest/). Astrocyte also
allows you to organize your personal mod collection\!
# Usage
Glia can be installed from pip:
pip install nrn-glia
Glia will check whether packages have been added, changed or removed and
will recompile and load the library if necessary. This means that except
for importing Glia there's not much you need to do\!
``` python
from neuron import h
import glia as g
section = h.Section(name="soma")
# Load your favourite Kv1 mechanism.
g.insert(section, "Kv1")
# Note: to load the library at import time you can import glia.library instead
import glia.library
```
Glia avoids conflicts between authors and even variants of the same
mechanism and allows you to select sensible default preferences on many
levels: globally, per script, per context or per function call.
# Asset management
Glia allows for multiple assets to refer to the same mechanism by giving
them a unique name per package. The standard naming convention is as
follows:
glia__<package-name>__<asset-name>__<variant-name>
Double underscores in packages, assets or variant names are not allowed.
This naming convention allows for multiple people to provide an
implementation of the same asset, and by using variants even one package
can provide multiple variations on the same mechanism. The default
variant is `0`
If you install multiple packages that provide the same asset, or if you
would like to specify another variant you will need to tell Glia which
one you require. You can do so by setting your asset preferences.
# Asset preferences
There are 4 different scopes for providing asset preferences:
- **Global scope:** Selects a default mechanism asset everywhere.
- **Script scope:** Selects a default mechanism asset for the
remainder of the Python script.
- **Context scope:** Select a preferred package or variant for all
`glia.insert` calls within the context block.
- **Single use:** Selects a mechanism asset for a single `glia.insert`
call
## Single use
Whenever you call `glia.insert` you can append your preferences for that
insert:
``` python
g.insert('Kv1', pkg='not_my_models', variant='high_activity')
```
## Context scope
Any `glia.insert` or `glia.resolve` call within the with statement will
preferably use the given package or variant:
``` python
from patch import p
s = p.Section()
with g.context(pkg='not_my_models'):
g.insert(s, 'Kv1')
g.insert(s, 'Kv1', variant='high_activity')
```
You can also specify a dictionary with multiple asset-specific preferences:
``` python
from patch import p
s = p.Section()
with g.context(assets={
'Kv1': {'package': 'not_my_models', 'variant': 'high_activity'},
'HCN1': {'variant': 'revised'}
}):
g.insert(s, 'Kv1')
g.insert(s, 'HCN1')
# Not affected by the context:
g.insert(s, 'Kir2.3')
```
And you can even combine, preferring a certain package unless the
dictionary specifies otherwise:
``` python
from patch import p
s = p.Section()
with g.context(assets={
'Kv1': {'package': 'not_my_models', 'variant': 'high_activity'},
'HCN1': {'variant': 'revised'}
}, package='some_pkg_name'):
g.insert(s, 'Kv1')
g.insert(s, 'HCN1')
```
Finally for those of you that have really crazy preferences you can even
nest contexts, where the innermost preferences take priority.
## Script scope
Use `glia.select` to select a preferred mechanism asset, similar to the
single use syntax, for the remainder of the lifetime of the glia module:
``` python
section_global_Kv1 = h.Section()
section_local_Kv1 = h.Section()
g.insert(section_global_Kv1, 'Kv1') # Will use your global Kv1 mechanism
g.select('Kv1', pkg='not_my_models', variant='high_activity')
g.insert(section_local_Kv1, 'Kv1') # Will use the above selected Kv1 mechanism
```
## Global scope
Applying global scope uses the Glia command-line tool and will configure
glia to always select a mechanism asset as default.
Go to your favorite command-line and enter:
glia select Kv1 --pkg=some_pkg_name --variant=non_default
This will set your preference in any script you use.
Raw data
{
"_id": null,
"home_page": "https://github.com/dbbs-lab/glia",
"name": "nrn-glia",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Robin De Schepper",
"author_email": "robingilbert.deschepper@unipv.it",
"download_url": "",
"platform": "",
"description": "[![Build Status](https://travis-ci.org/dbbs-lab/glia.svg?branch=master)](https://travis-ci.org/dbbs-lab/glia)\n[![codecov](https://codecov.io/gh/dbbs-lab/glia/branch/master/graph/badge.svg)](https://codecov.io/gh/dbbs-lab/glia)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Documentation Status](https://readthedocs.org/projects/nrn-glia/badge/?version=latest)](https://nrn-glia.readthedocs.io/en/latest/?badge=latest)\n\n# Glia: NEURON package manager\n\nGlia is an asset manager for NEURON. It collects mod files from\ndifferent pip packages and compiles them into a central library that is\nautomatically loaded into NEURON. This removes the need for compiling\nfolder after folder with cluttered, duplicated mod files and allows you\nto focus on using these mechanisms across multiple models.\n\nPackaging your mod files as a Glia package allows you to distribute them\nas dependencies of your Python models and delegates the installation,\ndistribution, versioning and archiving of your assets to Python's packet\nmanager pip.\n\nTo create Glia packages, check out the CLI tool\n[Astrocyte](https://astrocyte.readthedocs.io/en/latest/). Astrocyte also\nallows you to organize your personal mod collection\\!\n\n# Usage\n\nGlia can be installed from pip:\n\n pip install nrn-glia\n\nGlia will check whether packages have been added, changed or removed and\nwill recompile and load the library if necessary. This means that except\nfor importing Glia there's not much you need to do\\!\n\n``` python\nfrom neuron import h\nimport glia as g\n\nsection = h.Section(name=\"soma\")\n# Load your favourite Kv1 mechanism.\ng.insert(section, \"Kv1\")\n\n# Note: to load the library at import time you can import glia.library instead\nimport glia.library\n```\n\nGlia avoids conflicts between authors and even variants of the same\nmechanism and allows you to select sensible default preferences on many\nlevels: globally, per script, per context or per function call.\n\n# Asset management\n\nGlia allows for multiple assets to refer to the same mechanism by giving\nthem a unique name per package. The standard naming convention is as\nfollows:\n\n glia__<package-name>__<asset-name>__<variant-name>\n\nDouble underscores in packages, assets or variant names are not allowed.\n\nThis naming convention allows for multiple people to provide an\nimplementation of the same asset, and by using variants even one package\ncan provide multiple variations on the same mechanism. The default\nvariant is `0`\n\nIf you install multiple packages that provide the same asset, or if you\nwould like to specify another variant you will need to tell Glia which\none you require. You can do so by setting your asset preferences.\n\n# Asset preferences\n\nThere are 4 different scopes for providing asset preferences:\n\n - **Global scope:** Selects a default mechanism asset everywhere.\n - **Script scope:** Selects a default mechanism asset for the\n remainder of the Python script.\n - **Context scope:** Select a preferred package or variant for all\n `glia.insert` calls within the context block.\n - **Single use:** Selects a mechanism asset for a single `glia.insert`\n call\n\n## Single use\n\nWhenever you call `glia.insert` you can append your preferences for that\ninsert:\n\n``` python\ng.insert('Kv1', pkg='not_my_models', variant='high_activity')\n```\n\n## Context scope\n\nAny `glia.insert` or `glia.resolve` call within the with statement will\npreferably use the given package or variant:\n\n``` python\nfrom patch import p\ns = p.Section()\nwith g.context(pkg='not_my_models'):\n g.insert(s, 'Kv1')\n g.insert(s, 'Kv1', variant='high_activity')\n```\n\nYou can also specify a dictionary with multiple asset-specific preferences:\n\n``` python\nfrom patch import p\ns = p.Section()\nwith g.context(assets={\n 'Kv1': {'package': 'not_my_models', 'variant': 'high_activity'},\n 'HCN1': {'variant': 'revised'}\n}):\n g.insert(s, 'Kv1')\n g.insert(s, 'HCN1')\n # Not affected by the context:\n g.insert(s, 'Kir2.3')\n```\n\nAnd you can even combine, preferring a certain package unless the\ndictionary specifies otherwise:\n\n``` python\nfrom patch import p\ns = p.Section()\nwith g.context(assets={\n 'Kv1': {'package': 'not_my_models', 'variant': 'high_activity'},\n 'HCN1': {'variant': 'revised'}\n}, package='some_pkg_name'):\n g.insert(s, 'Kv1')\n g.insert(s, 'HCN1')\n```\n\nFinally for those of you that have really crazy preferences you can even\nnest contexts, where the innermost preferences take priority.\n\n## Script scope\n\nUse `glia.select` to select a preferred mechanism asset, similar to the\nsingle use syntax, for the remainder of the lifetime of the glia module:\n\n``` python\nsection_global_Kv1 = h.Section()\nsection_local_Kv1 = h.Section()\ng.insert(section_global_Kv1, 'Kv1') # Will use your global Kv1 mechanism\ng.select('Kv1', pkg='not_my_models', variant='high_activity')\ng.insert(section_local_Kv1, 'Kv1') # Will use the above selected Kv1 mechanism\n```\n\n## Global scope\n\nApplying global scope uses the Glia command-line tool and will configure\nglia to always select a mechanism asset as default.\n\nGo to your favorite command-line and enter:\n\n glia select Kv1 --pkg=some_pkg_name --variant=non_default\n\nThis will set your preference in any script you use.\n\n\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "Package manager for NEURON",
"version": "0.5.1",
"project_urls": {
"Homepage": "https://github.com/dbbs-lab/glia"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c791a76a3cae9635f6bb1e2cc4d5199e4e4553f83c83479b12a193270c0ab497",
"md5": "f25860023b60d9774aeafc952a750086",
"sha256": "9b4782b6166bcfe9aced77a060a06f4b6f688804a45c58751a42d9fb2294f3b4"
},
"downloads": -1,
"filename": "nrn_glia-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f25860023b60d9774aeafc952a750086",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 32059,
"upload_time": "2021-12-13T19:20:39",
"upload_time_iso_8601": "2021-12-13T19:20:39.647547Z",
"url": "https://files.pythonhosted.org/packages/c7/91/a76a3cae9635f6bb1e2cc4d5199e4e4553f83c83479b12a193270c0ab497/nrn_glia-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-12-13 19:20:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dbbs-lab",
"github_project": "glia",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "nrn-glia"
}