[](http://www.astropy.org/)
Astrolabel is a lightweight Python package that allows to efficiently manage astronomy plot labels.
## Installation
```shell
$ pip install astrolabel
```
## Requirements
- `python>=3.8`
- `astropy>=5.0`
- `dacite>=1.8.0`
## Quick Start
Create a `LabelLibrary` object:
```python
>>> from astrolabel import LabelLibrary
>>> ll = LabelLibrary.read()
```
Get a label by its key:
```python
>>> ll.get_label('sfr') # output: '$\\mathrm{SFR}$ [$\\mathrm{M_{\\odot}\\,yr^{-1}}$]'
```
Change the label format:
```python
>>> ll.get_label('sfr', fmt='log') # output: '$\\log_{10}\\,\\left(\\mathrm{SFR} / \\mathrm{M_{\\odot}\\,yr^{-1}}\\right)$'
```
Print the list of available labels:
```python
>>> ll.info() # prints the list of available labels to the console
```
## Label Library
### Overview
Astrolabel reads the label data from a [YAML](https://yaml.org) file, which we call a _label library_. Here is an example of a minimal label library which contains only one label:
```yaml
formats:
default: '__symbol__'
default_u: '__symbol__ [__unit__]'
labels:
sfr:
symbol: '\mathrm{SFR}'
unit: 'Msun yr-1' # optional
description: 'Star-formation rate' # optional
```
The `formats` sections contains the list of custom template strings used by the `get_label()` method to format the label. When this method is called, the template string is modified as follows: `__symbol__` is replaced with the `symbol` attribute of the label, and `__unit__` is replaced with the `unit` attribute of the label. Note that all template strings must come in two variants: one for labels with a unit, and another one for labels without a unit. The name of the template string where units are used must end with `_u` (e.g., `my_format_u`).
Here is a more advanced example of template strings which can be used to create labels for plots with logarithmic axes:
```yaml
log: '$\log_{10}\,__symbol__$'
log_u: '$\log_{10}\,\left(__symbol__ / __unit__\right)$'
```
The `labels` section of the label library contains the list of custom plot labels, each of which has the following attributes:
- `symbol`: the symbol representing the plotted parameter. Note that math mode is applied to all symbols by default. Therefore, use `\mathrm{}` in cases where the upright letter notation is preferable (e.g., `\mathrm{SFR}`);
- **\[optional\]** `unit`: the plotted parameter's unit of measurement. All units are converted to the LaTeX format using the Astropy's [`Quantity.to_string()` method](https://docs.astropy.org/en/stable/api/astropy.units.Quantity.html#astropy.units.Quantity.to_string). The list of units supported by Astropy and hence by Astrolabel can be found in the Astropy's official documentation [here](https://docs.astropy.org/en/stable/units/index.html). This list covers most (if not all) units used in astronomy. However, if you want to define new units, follow the instructions on [this page](https://docs.astropy.org/en/stable/units/combining_and_defining.html#defining-units);
- **\[optional\]** `description`: the text description of the plotted parameter.
**Note:** due to the specifics of YAML, it is highly recommended to use single quotes (`'`) when adding new labels or label formats to the label library.
### Specifying the library location
The path to the label library can be passed to the `LabelLibrary` constructor:
```python
>>> ll = LabelLibrary.read('/path/to/label/library.yml')
```
In case no arguments are passed to the constructor, Astrolabel looks for the label library in three locations, in the following order:
1. `astrolabel.yml` in the current working directory.
2. `$ASTROLABEL` - the best option for users who want to use the same library across different projects.
3. The default library location (see below). Note that the default library will be overwritten each time you reinstall or update the package.
To check the location of the currently active library, call the `library_fname()` method of the `LabelLibrary` object:
```python
>>> ll.library_fname() # output: PosixPath('/home/foo/.../bar/astrolabel.yml')
```
### The default library
The Astrolabel package comes with a label library which includes two label formats (`default` and `log`) and some labels commonly used for astronomy plots. The location of the default label library is stored in the `DEFAULT_LIBRARY_PATH` constant:
```python
>>> from astrolabel import DEFAULT_LIBRARY_PATH
>>> DEFAULT_LIBRARY_PATH # output: '/home/foo/.../astrolabel/astrolabel/data/astrolabel.yml'
```
Raw data
{
"_id": null,
"home_page": "https://github.com/ivkram/astrolabel",
"name": "astrolabel",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Ivan Kramarenko",
"author_email": "im.kramarenko@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/5a/30/3e009999c6c7a63586590c61370fc9503c7394d723855a32b3287a65499f/astrolabel-0.1.1.tar.gz",
"platform": null,
"description": "[](http://www.astropy.org/)\n\nAstrolabel is a lightweight Python package that allows to efficiently manage astronomy plot labels.\n\n## Installation\n\n```shell\n$ pip install astrolabel\n```\n\n## Requirements\n\n- `python>=3.8`\n- `astropy>=5.0`\n- `dacite>=1.8.0`\n\n## Quick Start\n\nCreate a `LabelLibrary` object:\n\n```python\n>>> from astrolabel import LabelLibrary\n>>> ll = LabelLibrary.read()\n```\n\nGet a label by its key:\n\n```python\n>>> ll.get_label('sfr') # output: '$\\\\mathrm{SFR}$ [$\\\\mathrm{M_{\\\\odot}\\\\,yr^{-1}}$]'\n```\n\nChange the label format:\n```python\n>>> ll.get_label('sfr', fmt='log') # output: '$\\\\log_{10}\\\\,\\\\left(\\\\mathrm{SFR} / \\\\mathrm{M_{\\\\odot}\\\\,yr^{-1}}\\\\right)$'\n```\n\nPrint the list of available labels:\n\n```python\n>>> ll.info() # prints the list of available labels to the console\n```\n\n## Label Library\n\n### Overview\n\nAstrolabel reads the label data from a [YAML](https://yaml.org) file, which we call a _label library_. Here is an example of a minimal label library which contains only one label:\n\n```yaml\nformats:\n default: '__symbol__'\n default_u: '__symbol__ [__unit__]'\n\nlabels:\n sfr:\n symbol: '\\mathrm{SFR}'\n unit: 'Msun yr-1' # optional\n description: 'Star-formation rate' # optional\n```\n\nThe `formats` sections contains the list of custom template strings used by the `get_label()` method to format the label. When this method is called, the template string is modified as follows: `__symbol__` is replaced with the `symbol` attribute of the label, and `__unit__` is replaced with the `unit` attribute of the label. Note that all template strings must come in two variants: one for labels with a unit, and another one for labels without a unit. The name of the template string where units are used must end with `_u` (e.g., `my_format_u`).\n\nHere is a more advanced example of template strings which can be used to create labels for plots with logarithmic axes:\n```yaml\nlog: '$\\log_{10}\\,__symbol__$'\nlog_u: '$\\log_{10}\\,\\left(__symbol__ / __unit__\\right)$'\n```\n\nThe `labels` section of the label library contains the list of custom plot labels, each of which has the following attributes:\n\n- `symbol`: the symbol representing the plotted parameter. Note that math mode is applied to all symbols by default. Therefore, use `\\mathrm{}` in cases where the upright letter notation is preferable (e.g., `\\mathrm{SFR}`);\n- **\\[optional\\]** `unit`: the plotted parameter's unit of measurement. All units are converted to the LaTeX format using the Astropy's [`Quantity.to_string()` method](https://docs.astropy.org/en/stable/api/astropy.units.Quantity.html#astropy.units.Quantity.to_string). The list of units supported by Astropy and hence by Astrolabel can be found in the Astropy's official documentation [here](https://docs.astropy.org/en/stable/units/index.html). This list covers most (if not all) units used in astronomy. However, if you want to define new units, follow the instructions on [this page](https://docs.astropy.org/en/stable/units/combining_and_defining.html#defining-units);\n- **\\[optional\\]** `description`: the text description of the plotted parameter.\n\n**Note:** due to the specifics of YAML, it is highly recommended to use single quotes (`'`) when adding new labels or label formats to the label library.\n\n### Specifying the library location\n\nThe path to the label library can be passed to the `LabelLibrary` constructor:\n\n```python\n>>> ll = LabelLibrary.read('/path/to/label/library.yml')\n```\n\nIn case no arguments are passed to the constructor, Astrolabel looks for the label library in three locations, in the following order:\n\n1. `astrolabel.yml` in the current working directory.\n2. `$ASTROLABEL` - the best option for users who want to use the same library across different projects.\n3. The default library location (see below). Note that the default library will be overwritten each time you reinstall or update the package. \n\nTo check the location of the currently active library, call the `library_fname()` method of the `LabelLibrary` object:\n\n```python\n>>> ll.library_fname() # output: PosixPath('/home/foo/.../bar/astrolabel.yml')\n```\n\n\n### The default library\n\nThe Astrolabel package comes with a label library which includes two label formats (`default` and `log`) and some labels commonly used for astronomy plots. The location of the default label library is stored in the `DEFAULT_LIBRARY_PATH` constant:\n\n```python\n>>> from astrolabel import DEFAULT_LIBRARY_PATH\n>>> DEFAULT_LIBRARY_PATH # output: '/home/foo/.../astrolabel/astrolabel/data/astrolabel.yml'\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A lightweight Python package for managing astronomy plot labels",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/ivkram/astrolabel",
"Repository": "https://github.com/ivkram/astrolabel"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8458cfa30f8b7459c84d13c92c7e5cd659c87c2efe42015e2ab0e5c9a251d591",
"md5": "f117341791b97bd8741a241690c4a767",
"sha256": "30881af133029479249000c93ca2ab3002b01493389ac598b2307287ba51d7b9"
},
"downloads": -1,
"filename": "astrolabel-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f117341791b97bd8741a241690c4a767",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7641,
"upload_time": "2023-08-11T10:50:57",
"upload_time_iso_8601": "2023-08-11T10:50:57.573148Z",
"url": "https://files.pythonhosted.org/packages/84/58/cfa30f8b7459c84d13c92c7e5cd659c87c2efe42015e2ab0e5c9a251d591/astrolabel-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5a303e009999c6c7a63586590c61370fc9503c7394d723855a32b3287a65499f",
"md5": "f7f41503a0c77d8cb2b2baa2e3c72a83",
"sha256": "0895a75cb45b319b34095249676c9861075274ac42a0341b6b65e8bdd59995b6"
},
"downloads": -1,
"filename": "astrolabel-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "f7f41503a0c77d8cb2b2baa2e3c72a83",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 6335,
"upload_time": "2023-08-11T10:50:59",
"upload_time_iso_8601": "2023-08-11T10:50:59.009000Z",
"url": "https://files.pythonhosted.org/packages/5a/30/3e009999c6c7a63586590c61370fc9503c7394d723855a32b3287a65499f/astrolabel-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-11 10:50:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ivkram",
"github_project": "astrolabel",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "astrolabel"
}
JSON
